| MIL 10 Reference
| Customize Help
| Save Settings

MthrControlMp



See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
Synopsis
Control a MIL multi-core processing setting of a thread context.
Syntax
void MthrControlMp(
MIL_ID ThrId, //in
MIL_INT64 ControlType, //in
MIL_INT64 TypeFlag, //in
MIL_INT64 TypeValue, //in
void *ValuePtr //in
)
Description

This function controls a MIL multi-core processing setting of a thread context. It establishes whether MIL can use multi-core processing to execute certain parts of MIL functions on the specified thread. It also sets how multi-core processing is performed for the specified thread.

MthrControlMp() always takes precedence over MappControlMp().

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
ThrId

Specifies the identifier of a user-allocated MIL thread context allocated using MthrAlloc().

function map For specifying the identifier of a user-allocated MIL thread context
CollapseValue Description
Collapse M_DEFAULT

Specifies the default MIL thread context identifier associated with the current Host thread.

Collapse MIL thread context identifier

Specifies the identifier of a user-allocated MIL thread context.

ControlType

Specifies the type of multi-core processing setting to control.

See the Parameter associations section for possible values that can be specified.

TypeFlag

Reserved for future expansion. This parameter must be set to M_DEFAULT.

TypeValue

Specifies the setting's new value.

See the Parameter associations section for possible values that can be specified.

ValuePtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_UINT64

Specifies the address which contains more information about the setting's new value. Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

The table below lists possible values for the ControlType, TypeValue, and ValuePtr parameters.

function map For specifying multi-core processing thread context settings
CollapseControlType Description
TypeValue
ValuePtr
Collapse M_CORE_AFFINITY_MASK

Sets the core affinity bit-mask, which indicates on which CPU core(s) (processor(s)) to run the multi-core processing part of MIL functions. Essentially, the core affinity mask defines the preferred processing CPU core(s) to use for MIL multi-core processing.

The number of CPU cores actually used for multi-core processing will be affected by M_CORE_MAX (or M_CORE_MAX_FOR_COPY for copy type functions such as MbufCopy()) and M_CORE_AFFINITY_MASK. Typically, the number of cores used for multi-processing will be the lesser of the two values.

To establish which CPU cores are assigned to the process running your MIL application, call MappInquireMp() with M_CORE_AFFINITY_MASK_PROCESS.

(summarize)
Collapse TypeValue

Specifies how to define the mask.

(summarize)
Collapse M_DEFAULT

Specifies the default value. This is the same as the value specified using MappControlMp() with M_CORE_AFFINITY_MASK.

(summarize)
Collapse M_ALL

Specifies to use all CPU cores available to the process running the MIL application, as per the operating system.

Collapse M_USER_DEFINED

Specifies to use a user-defined core affinity bit-mask.

Collapse ValuePtr
Data type info

Data type: array of type MIL_UINT64
Array size: MappInquireMp() with M_CORE_AFFINITY_MASK_ARRAY_SIZE

Specifies the core affinity bit-mask to use when defining a M_USER_DEFINED mask. INQ

(summarize)
Collapse M_NULL

Specifies that a user-defined mask is not used.

Collapse Non-zero initialized bit-mask array

Specifies a bit-mask array in which each bit represents one CPU core.

The first element of the array represents the first 64 CPU cores. The least-significant bit of the first element represents CPU core 0. The most-significant bit of the first element represents CPU core 63. The least-significant bit of the second element represents CPU core 64 and so on. CPU cores can be used for multi-core processing if their corresponding bit is enabled (1). If their corresponding bit is disabled (0), multi-core processing is not allowed to occur on those CPU cores. CPU cores always have the same indices, as long as the hardware in your computer and the operating system does not change.

A normal core affinity bit-mask should have at least one bit enabled so that at least one CPU core is enabled for processing. A core affinity bit-mask whose bits are all set to zero is therefore a special case and represents the default setting of all CPU cores being enabled for processing.

(summarize)
Collapse M_CORE_MAX

Sets the maximum number of CPU cores to use to process the multi-core processing part of each MIL function on the specified thread, when multi-core processing is enabled. Multi-core processing can be enabled using the MILConfig utility, MappControlMp() with M_MP_USE, or MthrControlMp() with M_MP_USE.

Note that this control type overrides the value set with the MILConfig utility and MappControlMp().

The number of CPU cores actually used for multi-core processing will be affected by M_CORE_MAX (or M_CORE_MAX_FOR_COPY for copy type functions such as MbufCopy()) and M_CORE_AFFINITY_MASK. Typically, the number of cores used for multi-processing will be the lesser of the two values.

The effective number of CPU cores available to MIL is limited by the number of CPU cores installed in your computer and any limits imposed by the operating system. To establish the number of CPU cores assigned to the process running your MIL application, call MappInquireMp() with M_CORE_NUM_PROCESS.

Note that the first call to MappAlloc() or MappAllocDefault() determines the number of CPU cores available from the operating system. This information is stored in MIL and not updated dynamically. Changing the number of processors available at the operating-system level, after your application is allocated in MIL, can result in erratic and unpredictable behavior.

(summarize)
Collapse TypeValue

Specifies one of the following.INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value. This is the same as the value specified using MappControlMp() with M_CORE_MAX.

(summarize)
Collapse 1 <= Value <= 65535

Specifies the maximum number of CPU cores to use. To use only one CPU core and disable multi-core processing, set the value to 1 or use the M_MP_USE control type.

Note that specifying the number of cores to use as 1 is effectively the equivalent of setting M_MP_USE to M_DISABLE.

(summarize)
Collapse M_CORE_MAX_FOR_COPY

Sets the maximum number of CPU cores to use to process the multi-core processing part of copy type functions, such as MbufCopy(), on the specified thread, when multi-core processing is enabled. Multi-core processing can be enabled using the MILConfig utility, MappControlMp() with M_MP_USE, or MthrControlMp() with M_MP_USE.

Note that this control type overrides the value set with the MILConfig utility and MappControlMp().

The number of cores set with M_CORE_MAX_FOR_COPY only affects copy type functions, and supercedes the number of cores set with M_CORE_MAX. For instance, if M_CORE_MAX specifies to use 4 cores, then all functions will use 4 cores. If afterwards M_CORE_MAX_FOR_COPY specifies 2 cores, all copy type functions will use 2 cores, while the remaining functions will still use 4.

The number of CPU cores actually used for multi-core processing will be affected by M_CORE_MAX (or M_CORE_MAX_FOR_COPY for copy type functions such as MbufCopy()) and M_CORE_AFFINITY_MASK. Typically, the number of cores used for multi-processing will be the lesser of the two values.

The effective number of CPU cores available to MIL is limited by the number of CPU cores installed in your computer and any limits imposed by the operating system. To establish the number of CPU cores assigned to the process running your MIL application, call MappInquireMp() with M_CORE_NUM_PROCESS.

Note that the first call to MappAlloc() or MappAllocDefault() determines the number of CPU cores available from the operating system. This information is stored in MIL and not updated dynamically. Changing the number of processors available at the operating-system level, after your application is allocated in MIL, can result in erratic and unpredictable behavior.

(summarize)
Collapse TypeValue

Specifies one of the following.INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value. This is the same as the value specified using MappControlMp() with M_CORE_MAX_FOR_COPY.

(summarize)
Collapse M_FOLLOW_CORE_MAX

Specifies to use the current value of M_CORE_MAX.

Collapse 1 <= Value <= 65535

Specifies the maximum number of CPU cores to use. To use only one CPU core and disable multi-core processing for copy type functions, set the value to 1.

(summarize)
Collapse M_CORE_SHARING

Sets whether MIL multi-core processing can use multiple logical cores per physical CPU core, when hyper-threading is enabled and supported.

An Intel processor's hyper-threading technology allows each of its physical CPU cores to be represented by multiple logical CPU cores, typically improving parallelization of computations. However, depending on the processing operation, this might reduce the processing speed. If you disable M_CORE_SHARING, MIL multi-core processing executes as if hyper-threading was disabled and restricts multi-core processing to one logical core per physical CPU core, minimizing logical core interactions.

Note that a thread might not have exclusive access to a CPU core; other processes or threads might still use the other logical cores of a physical CPU core and might impede multi-core processing restricted this way.

This control type only affects how the multi-core processing part of MIL functions is performed.

(summarize)
Collapse TypeValue

Specifies one of the following.INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value. This is the same as the value specified using MappControlMp() with M_CORE_SHARING.

(summarize)
Collapse M_DISABLE

Uses only one logical core per physical CPU core, if hyper-threading is enabled.

Collapse M_ENABLE

Uses all the logical cores of a physical CPU core, if hyper-threading is enabled.

Collapse M_MP_PRIORITY

Controls the processing priority of the multi-core processing part of MIL functions.

(summarize)
Collapse TypeValue

Specifies one of the following.INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value. This is the same as the value specified using MappControlMp() with M_MP_PRIORITY.

(summarize)
Collapse M_ABOVE_NORMAL

Specifies that the multi-core processing part of MIL functions will be executed with above normal priority.

Collapse M_BELOW_NORMAL

Specifies that the multi-core processing part of MIL functions will be executed with below normal priority.

Collapse M_HIGHEST

Specifies that the multi-core processing part of MIL functions will be executed with high priority. Only M_TIME_CRITICAL assigns a higher priority.

(summarize)
Collapse M_IDLE

Specifies that the multi-core processing part of MIL functions will be executed with idle priority. All idle priority processing objects are only executed when a CPU core is idle.

(summarize)
Collapse M_LOWEST

Specifies that the multi-core processing part of MIL functions will be executed with low priority.

Collapse M_NORMAL

Specifies that the multi-core processing part of MIL functions will be executed with normal priority.

Collapse M_TIME_CRITICAL

Specifies that the multi-core processing part of MIL functions will be executed with time critical priority. Time critical processing objects have highest priority.

(summarize)
Collapse M_MP_USE

Sets whether multi-core processing can be used to execute certain parts of MIL functions.

Note that the MILConfig utility can override and disable all MIL multi-core processing. To inquire whether the MILConfig utility has disabled MIL multi-core processing, use MappInquireMp() with M_MP_FORCED_DISABLE.

(summarize)
Collapse TypeValue

Specifies one of the following.INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value. This is the same as the value specified using MappControlMp() with M_MP_USE.

(summarize)
Collapse M_DISABLE

Specifies that multi-core processing cannot be used for MIL functions on the specified thread.

Collapse M_ENABLE

Specifies that multi-core processing can be used for MIL functions on the specified thread.

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll, milmp.dll.
DEFAULT CORE AFFINITY MASK DEFAULT ALL USER DEFINED NULL CORE MAX DEFAULT CORE MAX FOR COPY DEFAULT FOLLOW CORE MAX CORE SHARING DEFAULT DISABLE ENABLE MP PRIORITY DEFAULT ABOVE NORMAL BELOW NORMAL HIGHEST IDLE LOWEST NORMAL TIME CRITICAL MP USE DEFAULT DISABLE ENABLE