Embedded Multicore Building Blocks V1.0.0
Classes | Functions

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

Detailed Description

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.

Function Documentation

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.
See also
mtapi_actionattr_init(), mtapi_actionattr_set(), mtapi_action_delete(), mtapi_finalize()
Returns
Handle to newly created action, invalid handle on error
Concurrency
Thread-safe
Parameters
[in]job_idJob id
[in]functionAction function pointer
[in]node_local_dataData shared across tasks
[in]node_local_data_sizeSize of shared data
[in]attributesPointer to attributes
[out]statusPointer 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.
See also
mtapi_actionattr_set()
Concurrency
Not thread-safe
Parameters
[in]actionAction handle
[in]attribute_numAttribute id
[in]attributePointer to attribute value
[in]attribute_sizeSize of attribute value. may be 0, attribute is interpreted as value in that case
[out]statusPointer 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.
See also
mtapi_actionattr_set()
Concurrency
Thread-safe and wait-free
Parameters
[in]actionAction handle
[in]attribute_numAttribute id
[out]attributePointer to attribute value
[in]attribute_sizeSize of attribute value
[out]statusPointer 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:

  • If mtapi_action_delete() is called on an action that is currently executing, the associated task's state will be set to 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.
  • Tasks that are started or enqueued but waiting for execution by the MTAPI runtime when mtapi_action_delete() is called will not be executed anymore if the deleted action is the only action associated with that task. A call to mtapi_task_wait() will return the status MTAPI_ERR_ACTION_DELETED.
  • Tasks that are started or enqueued after deletion of the action will return 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.
See also
mtapi_context_taskstate_get(), mtapi_context_status_set(), mtapi_task_wait()
Concurrency
Thread-safe
Parameters
[in]actionAction handle
[in]timeoutTimeout duration in milliseconds
[out]statusPointer 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:

  • If mtapi_action_disable() is called on an action that is currently executing, the associated task's state will be set to 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.
  • Tasks that are started or enqueued but waiting for execution by the MTAPI runtime when mtapi_action_disable() is called will not be executed anymore if the disabled action is the only action associated with that task. A call to mtapi_task_wait() will return the status MTAPI_ERR_ACTION_DISABLED.
  • Tasks that are started or enqueued after the action has been disabled will return 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.
See also
mtapi_context_taskstate_get(), mtapi_context_status_set(), mtapi_task_wait()
Concurrency
Thread-safe and wait-free
Parameters
[in]actionAction handle
[in]timeoutTimeout duration in milliseconds
[out]statusPointer 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.
Concurrency
Thread-safe and wait-free
Parameters
[in]actionAction handle
[out]statusPointer to error code, may be MTAPI_NULL