Embedded Multicore Building Blocks V1.0.0
Modules | Typedefs | Functions
MTAPI Extensions

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

Detailed Description

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 Documentation

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.

Function Documentation

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.
See also
mtapi_action_delete(), mtapi_finalize()
Returns
Handle to newly created plugin action, invalid handle on error
Concurrency
Thread-safe
Parameters
[in]job_idJob id
[in]task_start_functionTask start function
[in]task_cancel_functionTask cancel function
[in]action_finalize_functionFinalize action function
[in]plugin_dataPointer to plugin data
[in]node_local_dataPointer to node local data
[in]node_local_data_sizeSize of node local data
[out]attributesPointer to attributes
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_ext_yield ( )

This function yields execution to the MTAPI scheduler for at most one task.

Concurrency
Not thread-safe