Embedded Multicore Building Blocks V1.0.0
Typedefs | Functions
Action Functions

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

Detailed Description

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 Documentation

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.

Function Documentation

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 completion
  • MTAPI_ERR_ACTION_CANCELLED if the action execution is canceled
  • MTAPI_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.
See also
mtapi_task_wait(), mtapi_group_wait_any()
Concurrency
Not thread-safe
Parameters
[in,out]task_contextPointer to task context
[in]error_codeTask return value
[out]statusPointer 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:

  • To trigger prefetching of data for further processing
  • To order execution via queues there might be point in the action code where the next task in the queue may be started, even if the current code, started from the same queue, is still executing

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.
Concurrency
Not thread-safe
Parameters
[in]task_contextPointer to task context
[in]notificationNotification id
[in]dataPointer to associated data
[in]data_sizeSize of data
[out]statusPointer 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.
Returns
Task state of current context
Concurrency
Not thread-safe
Parameters
[in]task_contextPointer to task context
[out]statusPointer 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.
Returns
Instance number of current task
Concurrency
Not thread-safe
Parameters
[in]task_contextPointer to task context
[out]statusPointer 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.
Returns
Total number of parallel task instances
Concurrency
Not thread-safe
Parameters
[in]task_contextPointer to task context
[out]statusPointer 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.
Returns
Worker thread index the current task is running on
Concurrency
Not thread-safe
Parameters
[in]task_contextPointer to task context
[out]statusPointer to error code, may be MTAPI_NULL