Embedded Multicore Building Blocks V1.0.0
|
Provides extensions to the standard MTAPI API. More...
Modules | |
MTAPI OpenCL Plugin | |
Provides functionality to execute tasks on OpenCL devices. | |
MTAPI Network Plugin | |
Provides functionality to distribute tasks across nodes in a TCP/IP network. | |
MTAPI CUDA Plugin | |
Provides functionality to execute tasks on CUDA devices. | |
Typedefs | |
typedef void(* | mtapi_ext_plugin_task_start_function_t) (MTAPI_IN mtapi_task_hndl_t task, MTAPI_OUT mtapi_status_t *status) |
Represents a callback function that is called when a plugin action is about to start a plugin task. More... | |
typedef void(* | mtapi_ext_plugin_task_cancel_function_t) (MTAPI_IN mtapi_task_hndl_t task, MTAPI_OUT mtapi_status_t *status) |
Represents a callback function that is called when a plugin task is about to be canceled. More... | |
typedef void(* | mtapi_ext_plugin_action_finalize_function_t) (MTAPI_IN mtapi_action_hndl_t action, MTAPI_OUT mtapi_status_t *status) |
Represents a callback function that is called when a plugin action is about to be finalized. More... | |
Functions | |
mtapi_action_hndl_t | mtapi_ext_plugin_action_create (MTAPI_IN mtapi_job_id_t job_id, MTAPI_IN mtapi_ext_plugin_task_start_function_t task_start_function, MTAPI_IN mtapi_ext_plugin_task_cancel_function_t task_cancel_function, MTAPI_IN mtapi_ext_plugin_action_finalize_function_t action_finalize_function, MTAPI_IN void *plugin_data, MTAPI_IN void *node_local_data, MTAPI_IN mtapi_size_t node_local_data_size, MTAPI_IN mtapi_action_attributes_t *attributes, MTAPI_OUT mtapi_status_t *status) |
This function creates a plugin action. More... | |
void | mtapi_ext_yield () |
This function yields execution to the MTAPI scheduler for at most one task. More... | |
Provides extensions to the standard MTAPI API.
There are two extension functions defined here. One to support user defined behavior of an action to allow for actions that are not implemented locally in software, but e.g., on a remote node in a network or on an accelerator device like a GPU or an FPGA. The other one is used to specify job attributes.
typedef void(* mtapi_ext_plugin_task_start_function_t) (MTAPI_IN mtapi_task_hndl_t task, MTAPI_OUT mtapi_status_t *status) |
Represents a callback function that is called when a plugin action is about to start a plugin task.
This function should return MTAPI_SUCCESS if the task could be started and the appropriate MTAPI_ERR_* if not.
typedef void(* mtapi_ext_plugin_task_cancel_function_t) (MTAPI_IN mtapi_task_hndl_t task, MTAPI_OUT mtapi_status_t *status) |
Represents a callback function that is called when a plugin task is about to be canceled.
This function should return MTAPI_SUCCESS if the task could be canceled and the appropriate MTAPI_ERR_* if not.
typedef void(* mtapi_ext_plugin_action_finalize_function_t) (MTAPI_IN mtapi_action_hndl_t action, MTAPI_OUT mtapi_status_t *status) |
Represents a callback function that is called when a plugin action is about to be finalized.
This function should return MTAPI_SUCCESS if the action could be deleted and the appropriate MTAPI_ERR_* if not.
mtapi_action_hndl_t mtapi_ext_plugin_action_create | ( | MTAPI_IN mtapi_job_id_t | job_id, |
MTAPI_IN mtapi_ext_plugin_task_start_function_t | task_start_function, | ||
MTAPI_IN mtapi_ext_plugin_task_cancel_function_t | task_cancel_function, | ||
MTAPI_IN mtapi_ext_plugin_action_finalize_function_t | action_finalize_function, | ||
MTAPI_IN void * | plugin_data, | ||
MTAPI_IN void * | node_local_data, | ||
MTAPI_IN mtapi_size_t | node_local_data_size, | ||
MTAPI_IN mtapi_action_attributes_t * | attributes, | ||
MTAPI_OUT mtapi_status_t * | status | ||
) |
This function creates a plugin action.
It is called on the node where the plugin action is implemented. A plugin action is an abstract encapsulation of a user defined action that is needed to implement a job that does not represent a software action. A plugin action contains a reference to a job, callback functions to start and cancel tasks and a reference to an callback function to finalize the action. After a plugin 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
. A plugin action's life-cycle begins with mtapi_ext_plugin_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.
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_NODE_NOTINIT | The calling node is not initialized. |
[in] | job_id | Job id |
[in] | task_start_function | Task start function |
[in] | task_cancel_function | Task cancel function |
[in] | action_finalize_function | Finalize action function |
[in] | plugin_data | Pointer to plugin data |
[in] | node_local_data | Pointer to node local data |
[in] | node_local_data_size | Size of node local data |
[out] | attributes | Pointer to attributes |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_ext_yield | ( | ) |
This function yields execution to the MTAPI scheduler for at most one task.