Embedded Multicore Building Blocks V1.0.0
|
Affinities for executing action functions on subsets of cores. More...
Typedefs | |
typedef mtapi_uint64_t | mtapi_affinity_t |
Core affinity type. More... | |
Functions | |
void | mtapi_affinity_init (mtapi_affinity_t *mask, const mtapi_boolean_t affinity, mtapi_status_t *status) |
This function initializes an affinity mask object. More... | |
void | mtapi_affinity_set (mtapi_affinity_t *mask, const mtapi_uint_t core_num, const mtapi_boolean_t affinity, mtapi_status_t *status) |
This function is used to change the default values of an affinity mask object. More... | |
mtapi_boolean_t | mtapi_affinity_get (mtapi_affinity_t *mask, const mtapi_uint_t core_num, mtapi_status_t *status) |
Returns the affinity that corresponds to the given core_num for this affinity mask. More... | |
Affinities for executing action functions on subsets of cores.
To set core affinities, the application must allocate an affinity mask object of type mtapi_affinity_t
and initialize it with a call to mtapi_affinity_init(). Affinities are specified by calling mtapi_affinity_set(). The application must also allocate and initialize an action attributes object of type mtapi_action_attributes_t
. The affinity mask object is then passed to mtapi_actionattr_set() to set the prescribed affinities in the action attributes object. The action attributes object is then passed to mtapi_action_create() to create a new action with those attributes.
It is in the nature of core affinities to be highly hardware dependent. The least common denominator for different architectures is enabling and disabling core numbers in the affinity mask. Action-to-core affinities can be set via the action attribute MTAPI_ACTION_AFFINITY
during the creation of an action.
typedef mtapi_uint64_t mtapi_affinity_t |
Core affinity type.
void mtapi_affinity_init | ( | mtapi_affinity_t * | mask, |
const mtapi_boolean_t | affinity, | ||
mtapi_status_t * | status | ||
) |
This function initializes an affinity mask object.
The affinity to all cores will be initialized to the value of affinity. This function should be called prior to calling mtapi_affinity_set() to specify non-default affinity settings. The affinity mask object may then be used to set the MTAPI_ACTION_AFFINITY
attribute when creating an action with mtapi_action_create().
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_AFFINITY_MASK | Invalid mask parameter. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[out] | mask | Pointer to affinity mask |
[in] | affinity | Initial affinity |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_affinity_set | ( | mtapi_affinity_t * | mask, |
const mtapi_uint_t | core_num, | ||
const mtapi_boolean_t | affinity, | ||
mtapi_status_t * | status | ||
) |
This function is used to change the default values of an affinity mask object.
The affinity mask object can then be passed to mtapi_actionattr_set() to set the MTAPI_ACTION_AFFINITY
action attribute. An action function will be executed on a core only if the core's affinity is set to MTAPI_TRUE
. Calls to mtapi_affinity_set() have no effect on action attributes after the action has been created.
mask
must be a pointer to an affinity mask object previously initialized with mtapi_affinity_init().
The core_num
is a hardware- and implementation-specific numeric identifier for a single core of the current node.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_AFFINITY_MASK | Invalid mask parameter. |
MTAPI_ERR_CORE_NUM | Unknown core number. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in,out] | mask | Pointer to affinity mask |
[in] | core_num | Core number |
[in] | affinity | Affinity to given core |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_boolean_t mtapi_affinity_get | ( | mtapi_affinity_t * | mask, |
const mtapi_uint_t | core_num, | ||
mtapi_status_t * | status | ||
) |
Returns the affinity that corresponds to the given core_num
for this affinity mask.
mask
is a pointer to an affinity mask object previously initialized with mtapi_affinity_init().
Note that affinities may be queried but may not be changed for an action after it has been created. If affinities need to be modified at runtime, new actions must be created.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_AFFINITY_MASK | Invalid mask parameter. |
MTAPI_ERR_CORE_NUM | Unknown core number. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
MTAPI_TRUE
if affinity to core_num
is set, MTAPI_FALSE
otherwise [out] | mask | Pointer to affinity mask |
[in] | core_num | Core number |
[out] | status | Pointer to error code, may be MTAPI_NULL |