Embedded Multicore Building Blocks V1.0.0
|
Hardware or software implementations of jobs. More...
Classes | |
struct | mtapi_action_attributes_struct |
Action attributes. More... | |
struct | mtapi_action_hndl_struct |
Action handle. More... | |
Functions | |
mtapi_action_hndl_t | mtapi_action_create (const mtapi_job_id_t job_id, const mtapi_action_function_t function, const void *node_local_data, const mtapi_size_t node_local_data_size, const mtapi_action_attributes_t *attributes, mtapi_status_t *status) |
This function creates a software action (hardware actions are considered to be pre-existent and do not need to be created). More... | |
void | mtapi_action_set_attribute (const mtapi_action_hndl_t action, const mtapi_uint_t attribute_num, const void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status) |
This function changes the value of the attribute that corresponds to the given attribute_num for this action. More... | |
void | mtapi_action_get_attribute (const mtapi_action_hndl_t action, const mtapi_uint_t attribute_num, void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status) |
Returns the attribute value that corresponds to the given attribute_num for this action. More... | |
void | mtapi_action_delete (const mtapi_action_hndl_t action, const mtapi_timeout_t timeout, mtapi_status_t *status) |
This function deletes a software action (Hardware actions exist perpetually and cannot be deleted). More... | |
void | mtapi_action_disable (const mtapi_action_hndl_t action, const mtapi_timeout_t timeout, mtapi_status_t *status) |
This function disables an action. More... | |
void | mtapi_action_enable (const mtapi_action_hndl_t action, mtapi_status_t *status) |
This function enables a previously disabled action. More... | |
Hardware or software implementations of jobs.
An action is referenced by an opaque handle of type mtapi_action_hndl_t
, or indirectly through a handle to a job of type mtapi_job_hndl_t
. A job refers to all actions implementing the same job, regardless of the node(s) where they are implemented.
An action's lifetime begins when the application successfully calls mtapi_action_create() and obtains a handle to the action. Its lifetime ends upon successful completion of mtapi_action_delete() or mtapi_finalize().
While an opaque handle to an action may be used in the scope of one node only, a job can be used to refer to all its associated actions implementing the same job, regardless of the node where they are implemented. Tasks may be invoked in this way from nodes that do not share memory or even the same ISA with the node where the action resides.
mtapi_action_hndl_t mtapi_action_create | ( | const mtapi_job_id_t | job_id, |
const mtapi_action_function_t | function, | ||
const void * | node_local_data, | ||
const mtapi_size_t | node_local_data_size, | ||
const mtapi_action_attributes_t * | attributes, | ||
mtapi_status_t * | status | ||
) |
This function creates a software action (hardware actions are considered to be pre-existent and do not need to be created).
It is called on the node where the action function is implemented. An action is an abstract encapsulation of everything needed to implement a job. An action contains attributes, a reference to a job, a reference to an action function, and a reference to node-local data. After an action is created, it is referenced by the application using a node-local handle of type mtapi_action_hndl_t
, or indirectly through a node-local job handle of type mtapi_job_hndl_t
. An action's life-cycle begins with mtapi_action_create(), and ends when mtapi_action_delete() or mtapi_finalize() is called.
To create an action, the application must supply the domain-wide job ID of the job associated with the action. Job IDs must be predefined in the application and runtime, of type mtapi_job_id_t
, which is an implementation-defined type. The job ID is unique in the sense that it is unique for the job implemented by the action. However several actions may implement the same job for load balancing purposes.
For non-default behavior, *attributes
must be prepared with mtapi_actionattr_init() and mtapi_actionattr_set() prior to calling mtapi_action_create(). If attributes is MTAPI_NULL
, then default attributes will be used.
If node_local_data_size
is not zero, node_local_data
specifies the start of node local data shared by action functions executed on the same node. node_local_data_size
can be used by the runtime for cache coherency operations.
On success, an action handle is returned and *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below. In the case where the action already exists, status
will be set to MTAPI_ERR_ACTION_EXISTS
and the handle returned will not be a valid handle.
Error code | Description |
---|---|
MTAPI_ERR_JOB_INVALID | The job_id is not a valid job ID, i.e., no action was created for that ID or the action has been deleted. |
MTAPI_ERR_ACTION_EXISTS | This action is already created. |
MTAPI_ERR_ACTION_LIMIT | Exceeded maximum number of actions allowed. |
MTAPI_ERR_ACTION_NOAFFINITY | The action was created with an MTAPI_ACTION_AFFINITY attribute that has set the affinity to all cores of the node to MTAPI_FALSE . |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
MTAPI_ERR_PARAMETER | Invalid attributes parameter. |
[in] | job_id | Job id |
[in] | function | Action function pointer |
[in] | node_local_data | Data shared across tasks |
[in] | node_local_data_size | Size of shared data |
[in] | attributes | Pointer to attributes |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_action_set_attribute | ( | const mtapi_action_hndl_t | action, |
const mtapi_uint_t | attribute_num, | ||
const void * | attribute, | ||
const mtapi_size_t | attribute_size, | ||
mtapi_status_t * | status | ||
) |
This function changes the value of the attribute that corresponds to the given attribute_num
for this action.
attribute
must point to the attribute value, and attribute_size
must be set to the exact size of the attribute value. See mtapi_actionattr_set() for a list of predefined attribute numbers and the sizes of their values.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_PARAMETER | Invalid attribute parameter. |
MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. |
MTAPI_ERR_ATTR_NUM | Unknown attribute number. |
MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | action | Action handle |
[in] | attribute_num | Attribute id |
[in] | attribute | Pointer to attribute value |
[in] | attribute_size | Size of attribute value. may be 0, attribute is interpreted as value in that case |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_action_get_attribute | ( | const mtapi_action_hndl_t | action, |
const mtapi_uint_t | attribute_num, | ||
void * | attribute, | ||
const mtapi_size_t | attribute_size, | ||
mtapi_status_t * | status | ||
) |
Returns the attribute value that corresponds to the given attribute_num
for this action.
attribute
must point to the location where the attribute value is to be returned, and attribute_size
must be set to the exact size of the attribute value. See mtapi_actionattr_set() for a list of predefined attribute numbers and the sizes of their values.
On success, *status
is set to MTAPI_SUCCESS
and the attribute value is returned in *attribute
. On error, *status
is set to the appropriate error defined below and *attribute
is undefined.
Error code | Description |
---|---|
MTAPI_ERR_PARAMETER | Invalid attribute parameter. |
MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. |
MTAPI_ERR_ATTR_NUM | Unknown attribute number. |
MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | action | Action handle |
[in] | attribute_num | Attribute id |
[out] | attribute | Pointer to attribute value |
[in] | attribute_size | Size of attribute value |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_action_delete | ( | const mtapi_action_hndl_t | action, |
const mtapi_timeout_t | timeout, | ||
mtapi_status_t * | status | ||
) |
This function deletes a software action (Hardware actions exist perpetually and cannot be deleted).
mtapi_action_delete() may be called by any node that has a valid action handle. Tasks associated with an action that has been deleted may still be executed depending on their internal state:
MTAPI_TASK_CANCELLED
and execution will continue. To accomplish this, action functions must poll the task state with mtapi_context_taskstate_get(). A call to mtapi_task_wait() on the task executing this code will return the status set by mtapi_context_status_set(), or MTAPI_SUCCESS
if not explicitly set.MTAPI_ERR_ACTION_DELETED
.MTAPI_ERR_ACTION_INVALID
if the deleted action is the only action associated with that task.Calling mtapi_action_get_attribute() on a deleted action will return MTAPI_ERR_ACTION_INVALID
if all actions implementing the job had been deleted.
The function mtapi_action_delete() blocks until the corresponding action code is left by all tasks that are executing the code or until the timeout is reached. If timeout
is a constant 0 or the symbolic constant MTAPI_NOWAIT
, this function only returns MTAPI_SUCCESS
if no tasks are executing the action when it is called. If it is set to MTAPI_INFINITE
, the function may block infinitely.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. |
MTAPI_TIMEOUT | Timeout was reached. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | action | Action handle |
[in] | timeout | Timeout duration in milliseconds |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_action_disable | ( | const mtapi_action_hndl_t | action, |
const mtapi_timeout_t | timeout, | ||
mtapi_status_t * | status | ||
) |
This function disables an action.
Tasks associated with an action that has been disabled may still be executed depending on their internal state:
MTAPI_TASK_CANCELLED
and execution will continue. To accomplish this, action functions must poll the task with mtapi_context_taskstate_get(). A call to mtapi_task_wait() on the task executing this code will return the status set by mtapi_context_status_set(), or MTAPI_SUCCESS
if not explicitly set.MTAPI_ERR_ACTION_DISABLED
.MTAPI_ERR_ACTION_DISABLED
if either the disabled action is the only action associated with a task or all actions associated with a task are disabled. mtapi_action_disable() blocks until all running tasks exit the code, or until the timeout is reached. If timeout is the constant 0 or the symbolic constant MTAPI_NOWAIT
, this function only returns MTAPI_SUCCESS
if no tasks are executing the action when it is called. If it is set to MTAPI_INFINITE
the function may block infinitely.On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. |
MTAPI_TIMEOUT | Timeout was reached. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | action | Action handle |
[in] | timeout | Timeout duration in milliseconds |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_action_enable | ( | const mtapi_action_hndl_t | action, |
mtapi_status_t * | status | ||
) |
This function enables a previously disabled action.
If this function is called on an action that no longer exists, an MTAPI_ERR_ACTION_INVALID
error will be returned.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | action | Action handle |
[out] | status | Pointer to error code, may be MTAPI_NULL |