Skip to main content

MthrControlMp

Control an Aurora Imaging Library multi-core processing setting of a thread context.

Syntax​

void MthrControlMp(
    AIL_ID    ThrId,        //out
    AIL_INT64 ControlType,  //in
    AIL_INT64 TypeFlag,     //in
    AIL_INT64 TypeValue,    //in
    void *    ValuePtr      //in
)

Description​

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

MthrControlMp always takes precedence over MappControlMp.

Parameters​

ThrId (out, AIL_ID)​

Specifies the identifier of a user-allocated Aurora Imaging Library thread context allocated using MthrAlloc.

For specifying the identifier of a user-allocated Aurora Imaging Library thread context

ValueDescription
M_DEFAULTSpecifies the default Aurora Imaging Library thread context identifier associated with the current Host thread.
Thread context identifierSpecifies the identifier of a user-allocated Aurora Imaging Library thread context.

ControlType (in, AIL_INT64)​

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

TypeFlag (in, AIL_INT64)​

Reserved for future expansion. This parameter must be set toM_DEFAULT.

TypeValue (in, AIL_INT64)​

Specifies the setting's new value.

ValuePtr *(in, void)​

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

Parameter Associations​

For specifying multi-core processing thread context settings​

Note, if unused, theValuePtrparameter must be set to M_NULL.

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 Aurora Imaging Library functions. Essentially, the core affinity mask defines the preferred processing CPU core(s) to use for Aurora Imaging Library multi-core processing. To establish which CPU cores are assigned to the process running your Aurora Imaging Library application, call MappInquireMp with M_CORE_AFFINITY_MASK_PROCESS.

ValueDescription
M_DEFAULTSpecifies the default value. This is the same as the value specified using MappControlMp with M_CORE_AFFINITY_MASK.
M_ALLSpecifies to use all CPU cores available to the process running the Aurora Imaging Library application, as per the operating system.
M_USER_DEFINEDSpecifies to use a user-defined core affinity bit-mask.
M_NULLSpecifies that a user-defined mask is not used.
Non-zero initialized bit-mask arraySpecifies 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.

M_CORE_MAX​

Sets the maximum number of CPU cores to use to process the multi-core processing part of each Aurora Imaging Library function on the specified thread, when multi-core processing is enabled. Multi-core processing can be enabled using the Aurora Imaging Configurator utility, MappControlMp with M_MP_USE, or MthrControlMp with M_MP_USE. > Note: Note that this control type overrides the value set with the Aurora Imaging Configurator utility and MappControlMp. The effective number of CPU cores available to Aurora Imaging Library 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 Aurora Imaging Library application, call MappInquireMp with M_CORE_NUM_PROCESS. > Note: 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 Aurora Imaging Library and not updated dynamically. Changing the number of processors available at the operating-system level, after your application is allocated in Aurora Imaging Library, can result in erratic and unpredictable behavior.

ValueDescription
M_DEFAULTSpecifies the default value. This is the same as the value specified using MappControlMp with M_CORE_MAX.
1 <= Value <= 65535Specifies 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: Note that specifying the number of cores to use as 1 is effectively the equivalent of setting M_MP_USE to M_DISABLE.

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 Aurora Imaging Configurator utility, MappControlMp with M_MP_USE, or MthrControlMp with M_MP_USE. > Note: Note that this control type overrides the value set with the Aurora Imaging Configurator 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 effective number of CPU cores available to Aurora Imaging Library 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 Aurora Imaging Library application, call MappInquireMp with M_CORE_NUM_PROCESS. > Note: 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 Aurora Imaging Library and not updated dynamically. Changing the number of processors available at the operating-system level, after your application is allocated in Aurora Imaging Library, can result in erratic and unpredictable behavior.

ValueDescription
M_DEFAULTSpecifies the default value. This is the same as the value specified using MappControlMp with M_CORE_MAX_FOR_COPY.
M_FOLLOW_CORE_MAXSpecifies to use the current value of M_CORE_MAX.
1 <= Value <= 65535Specifies 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.

M_CORE_SHARING​

Sets whether Aurora Imaging Library 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, Aurora Imaging Library 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 Aurora Imaging Library functions is performed.

ValueDescription
M_DEFAULTSpecifies the default value. This is the same as the value specified using MappControlMp with M_CORE_SHARING.
M_DISABLEUses only one logical core per physical CPU core, if hyper-threading is enabled.
M_ENABLEUses all the logical cores of a physical CPU core, if hyper-threading is enabled.

M_MP_PRIORITY​

Controls the processing priority of the multi-core processing part of Aurora Imaging Library functions.

ValueDescription
M_DEFAULTSpecifies the default value. This is the same as the value specified using MappControlMp with M_MP_PRIORITY.
M_ABOVE_NORMALSpecifies that the multi-core processing part of Aurora Imaging Library functions will be executed with above normal priority.
M_BELOW_NORMALSpecifies that the multi-core processing part of Aurora Imaging Library functions will be executed with below normal priority.
M_HIGHESTSpecifies that the multi-core processing part of Aurora Imaging Library functions will be executed with high priority. Only M_TIME_CRITICAL assigns a higher priority.
M_IDLESpecifies that the multi-core processing part of Aurora Imaging Library functions will be executed with idle priority. All idle priority processing objects are only executed when a CPU core is idle.
M_LOWESTSpecifies that the multi-core processing part of Aurora Imaging Library functions will be executed with low priority.
M_NORMALSpecifies that the multi-core processing part of Aurora Imaging Library functions will be executed with normal priority.
M_TIME_CRITICALSpecifies that the multi-core processing part of Aurora Imaging Library functions will be executed with time critical priority. Time critical processing objects have highest priority.

M_MP_USE​

Sets whether multi-core processing can be used to execute certain parts of Aurora Imaging Library functions. > Note: Note that the Aurora Imaging Configurator utility can override and disable all Aurora Imaging Library multi-core processing. To inquire whether the Aurora Imaging Configurator utility has disabled Aurora Imaging Library multi-core processing, use MappInquireMp with M_MP_FORCED_DISABLE.

ValueDescription
M_DEFAULTSpecifies the default value. This is the same as the value specified using MappControlMp with M_MP_USE.
M_DISABLESpecifies that multi-core processing cannot be used for Aurora Imaging Library functions on the specified thread.
M_ENABLESpecifies that multi-core processing can be used for Aurora Imaging Library functions on the specified thread.

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.

Copyright © 2026 Zebra Technologies.