Embedded Multicore Building Blocks V1.0.0
|
Executable software functions that implement actions. More...
Typedefs | |
typedef void(* | mtapi_action_function_t) (const void *args, mtapi_size_t args_size, void *result_buffer, mtapi_size_t result_buffer_size, const void *node_local_data, mtapi_size_t node_local_data_size, mtapi_task_context_t *context) |
An action function is the executable software function that implements an action. More... | |
Functions | |
void | mtapi_context_status_set (mtapi_task_context_t *task_context, const mtapi_status_t error_code, mtapi_status_t *status) |
This function can be called from an action function to set the status that can be obtained by a subsequent call to mtapi_task_wait() or mtapi_group_wait_any(). More... | |
void | mtapi_context_runtime_notify (const mtapi_task_context_t *task_context, const mtapi_notification_t notification, const void *data, const mtapi_size_t data_size, mtapi_status_t *status) |
This function can be called from an action function to notify the runtime system. More... | |
mtapi_task_state_t | mtapi_context_taskstate_get (const mtapi_task_context_t *task_context, mtapi_status_t *status) |
An action function may call this function to obtain the state of the task that is associated with the action function. More... | |
mtapi_uint_t | mtapi_context_instnum_get (const mtapi_task_context_t *task_context, mtapi_status_t *status) |
This function can be called from an action function to query the instance number of the associated task. More... | |
mtapi_uint_t | mtapi_context_numinst_get (const mtapi_task_context_t *task_context, mtapi_status_t *status) |
This function can be called from an action function to query the total number of parallel task instances. More... | |
mtapi_uint_t | mtapi_context_corenum_get (const mtapi_task_context_t *task_context, mtapi_status_t *status) |
This function can be called from an action function to query the current core number for debugging purposes. More... | |
Executable software functions that implement actions.
The runtime passes arguments to the action function when a task is started. Passing arguments from one node to another node should be implemented as a copy operation. Just as the arguments are passed before start of execution, the result buffer is copied back to the calling node after the action function terminates. In shared memory environments, the copying of data in both cases is not necessary. The node-local data is data used by several action functions being executed on the same node (or at least in the same address space). The shared data is specified when the action is created.
An action function can interact with the runtime environment through a task context object of type mtapi_task_context_t
. A task context object is allocated and managed by the runtime. The runtime passes a pointer to the context object when the action function is invoked.The action may then query information about the execution context(e.g., its core number, the number of tasks and task number in a multi - instance task, polling the task state) by calling the mtapi_context_*
functions. Furthermore it is possible to pass information from the action function to the runtime system which is executing the action function(setting the status manually, for example). All of these mtapi_context_*
functions are called in the context of task execution.
typedef void(* mtapi_action_function_t) (const void *args,mtapi_size_t args_size,void *result_buffer,mtapi_size_t result_buffer_size,const void *node_local_data,mtapi_size_t node_local_data_size,mtapi_task_context_t *context) |
An action function is the executable software function that implements an action.
The runtime passes arguments to the action function when a task is started. Passing arguments from one node to another node should be implemented as a copy operation. Just as the arguments are passed before start of execution, the result buffer is copied back to the calling node after the action function terminates. In shared memory environments, the copying of data in both cases is not necessary. The node-local data is data used by several action functions being executed on the same node (or at least in the same address space). The shared data is specified when the action is created.
An action function can interact with the runtime environment through a task context object of type mtapi_task_context_t . A task context object is allocated and managed by the runtime. The runtime passes a pointer to the context object when the action function is invoked. The action may then query information about the execution context (e.g., its core number, the number of tasks and task number in a multi-instance task, polling the task state) by calling the mtapi_context_* functions. Furthermore it is possible to pass information from the action function to the runtime system which is executing the action function (setting the status manually, for example). All of these mtapi_context_* functions are called in the context of task execution.
void mtapi_context_status_set | ( | mtapi_task_context_t * | task_context, |
const mtapi_status_t | error_code, | ||
mtapi_status_t * | status | ||
) |
This function can be called from an action function to set the status that can be obtained by a subsequent call to mtapi_task_wait() or mtapi_group_wait_any().
task_context
must be the same value as the context parameter that the runtime passes to the action function when it is invoked.
The status can be passed from the action function to the runtime system by setting error_code to one of the following values:
MTAPI_SUCCESS
for successful completionMTAPI_ERR_ACTION_CANCELLED
if the action execution is canceledMTAPI_ERR_ACTION_FAILED
if the task could not be completed as intended The error code will be especially important in future versions of MTAPI where tasks shall be chained (flow graphs). The chain execution can then be aborted if the error code is not MTAPI_SUCCESS
.On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_CONTEXT_OUTOFCONTEXT | Not called in the context of a task execution. This function must be used in an action function only. The action function must be called from the MTAPI runtime system. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in,out] | task_context | Pointer to task context |
[in] | error_code | Task return value |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_context_runtime_notify | ( | const mtapi_task_context_t * | task_context, |
const mtapi_notification_t | notification, | ||
const void * | data, | ||
const mtapi_size_t | data_size, | ||
mtapi_status_t * | status | ||
) |
This function can be called from an action function to notify the runtime system.
This is used to communicate certain states to the runtime implementation to allow it to optimize task execution.
task_context
must be the same value as the context parameter that the runtime passes to the action function when it is invoked.
The underlying type mtapi_notification_t
and the valid values for notification are implementation-defined. The notification system is meant to be flexible, and can be used in many ways, for example:
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_CONTEXT_OUTOFCONTEXT | Not called in the context of a task execution. This function must be used in an action function only. The action function must be called from the MTAPI runtime system. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | task_context | Pointer to task context |
[in] | notification | Notification id |
[in] | data | Pointer to associated data |
[in] | data_size | Size of data |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_task_state_t mtapi_context_taskstate_get | ( | const mtapi_task_context_t * | task_context, |
mtapi_status_t * | status | ||
) |
An action function may call this function to obtain the state of the task that is associated with the action function.
task_context
must be the same value as the context parameter that the runtime passes to the action function when it is invoked.
The underlying representation of type mtapi_task_state_t
is implementation-defined. Values of type mtapi_task_state_t
may be copied, assigned, and compared with other values of type mtapi_task_state_t
, but the caller should make no other assumptions about its type or contents. A minimal implementation must return a status of MTAPI_TASK_CANCELLED
if the task is canceled, and MTAPI_TASK_RUNNING
otherwise. Other values of the task state are implementation-defined. This task state can be used to abort a long running computation inside an action function.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_CONTEXT_OUTOFCONTEXT | Not called in the context of a task execution. This function must be used in an action function only. The action function must be called from the MTAPI runtime system. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | task_context | Pointer to task context |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_uint_t mtapi_context_instnum_get | ( | const mtapi_task_context_t * | task_context, |
mtapi_status_t * | status | ||
) |
This function can be called from an action function to query the instance number of the associated task.
A task can have multiple instances (multi-instance tasks), in which case the same job is executed multiple times in parallel. Each instance has a number, and this function gives the instance number. Task instances are numbered sequentially, starting at zero.
task_context
must be the same value as the context parameter that the runtime passes to the action function when it is invoked.
On success, *status
is set to MTAPI_SUCCESS
and the task instance number is returned. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_CONTEXT_OUTOFCONTEXT | Not called in the context of a task execution. This function must be used in an action function only. The action function must be called from the MTAPI runtime system. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | task_context | Pointer to task context |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_uint_t mtapi_context_numinst_get | ( | const mtapi_task_context_t * | task_context, |
mtapi_status_t * | status | ||
) |
This function can be called from an action function to query the total number of parallel task instances.
This value is greater than one for multi-instance tasks.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_CONTEXT_OUTOFCONTEXT | Not called in the context of a task execution. This function must be used in an action function only. The action function must be called from the MTAPI runtime system. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | task_context | Pointer to task context |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_uint_t mtapi_context_corenum_get | ( | const mtapi_task_context_t * | task_context, |
mtapi_status_t * | status | ||
) |
This function can be called from an action function to query the current core number for debugging purposes.
The core numbering is implementation-defined.
task_context
must be the same value as the context parameter that the runtime passes to the action function when it was invoked.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_CONTEXT_OUTOFCONTEXT | Not called in the context of a task execution. This function must be used in an action function only. The action function must be called from the MTAPI runtime system. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | task_context | Pointer to task context |
[out] | status | Pointer to error code, may be MTAPI_NULL |