Embedded Multicore Building Blocks V1.0.0
Typedefs | Functions
Core Affinities

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...
 

Detailed Description

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 Documentation

typedef mtapi_uint64_t mtapi_affinity_t

Core affinity type.

Function Documentation

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.
See also
mtapi_affinity_set(), mtapi_action_create()
Concurrency
Not thread-safe
Parameters
[out]maskPointer to affinity mask
[in]affinityInitial affinity
[out]statusPointer 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.
See also
mtapi_actionattr_set(), mtapi_affinity_init()
Concurrency
Not thread-safe
Parameters
[in,out]maskPointer to affinity mask
[in]core_numCore number
[in]affinityAffinity to given core
[out]statusPointer 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.
See also
mtapi_affinity_init()
Returns
MTAPI_TRUE if affinity to core_num is set, MTAPI_FALSE otherwise
Concurrency
Thread-safe and wait-free
Parameters
[out]maskPointer to affinity mask
[in]core_numCore number
[out]statusPointer to error code, may be MTAPI_NULL