Embedded Multicore Building Blocks V1.0.0
|
Tasks representing pieces of work "in flight" (similar to a thread handles). More...
Classes | |
struct | mtapi_task_attributes_struct |
Task attributes. More... | |
struct | mtapi_task_hndl_struct |
Task handle. More... | |
Functions | |
mtapi_task_hndl_t | mtapi_task_start (const mtapi_task_id_t task_id, const mtapi_job_hndl_t job, const void *arguments, const mtapi_size_t arguments_size, void *result_buffer, const mtapi_size_t result_size, const mtapi_task_attributes_t *attributes, const mtapi_group_hndl_t group, mtapi_status_t *status) |
This function schedules a task for execution. More... | |
mtapi_task_hndl_t | mtapi_task_enqueue (const mtapi_task_id_t task_id, const mtapi_queue_hndl_t queue, const void *arguments, const mtapi_size_t arguments_size, void *result_buffer, const mtapi_size_t result_size, const mtapi_task_attributes_t *attributes, const mtapi_group_hndl_t group, mtapi_status_t *status) |
This function schedules a task for execution using a queue. More... | |
void | mtapi_task_get_attribute (const mtapi_task_hndl_t task, const mtapi_uint_t attribute_num, void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status) |
Returns a copy of the attribute value that corresponds to the given attribute_num for the specified task. More... | |
void | mtapi_task_cancel (const mtapi_task_hndl_t task, mtapi_status_t *status) |
This function cancels a task and sets the task status to MTAPI_TASK_CANCELLED . More... | |
void | mtapi_task_wait (const mtapi_task_hndl_t task, const mtapi_timeout_t timeout, mtapi_status_t *status) |
This function waits for the completion of the specified task. More... | |
Tasks representing pieces of work "in flight" (similar to a thread handles).
A task is associated with a job object, which is associated with one or more actions implementing the same job for load balancing purposes. A task may optionally be associated with a task group. A task has attributes, and an internal state. A task begins its lifetime with a call to mtapi_task_start() or mtapi_task_enqueue(). A task is referenced by a handle of type mtapi_task_hndl_t
. The underlying type of mtapi_task_hndl_t
is implementation defined. Task handles may be copied, assigned, and passed as arguments, but otherwise the application should make no assumptions about the internal representation of a task handle.
Once a task is started, it is possible to wait for task completion from other parts of the program.
mtapi_task_hndl_t mtapi_task_start | ( | const mtapi_task_id_t | task_id, |
const mtapi_job_hndl_t | job, | ||
const void * | arguments, | ||
const mtapi_size_t | arguments_size, | ||
void * | result_buffer, | ||
const mtapi_size_t | result_size, | ||
const mtapi_task_attributes_t * | attributes, | ||
const mtapi_group_hndl_t | group, | ||
mtapi_status_t * | status | ||
) |
This function schedules a task for execution.
A task is associated with a job. A job is associated with one or more actions. An action provides an action function, which is the executable implementation of a job. If more than one action is associated with the job, the runtime system chooses dynamically which action is used for execution for load balancing purposes.
task_id
is an optional ID provided by the application for debugging purposes. If not needed, it can be set to MTAPI_TASK_ID_NONE
. The minimum and maximum values for task_id
may be derived from MTAPI_MIN_USER_TASK_ID
and MTAPI_MAX_USER_TASK_ID
.
job
must be a handle to a job obtained by a previous call to mtapi_job_get().
If arguments_size
is not zero, then arguments must point to data of arguments_size
bytes. The arguments will be transferred by the runtime from the node where the action was created to the executing node if necessary. Marshalling of arguments is not part of the MTAPI specification and is implementation-defined.
If attributes
is MTAPI_NULL
, the task will be started with default attribute values. Otherwise attributes
must point to a task attributes object previously prepared using mtapi_taskattr_init() and mtapi_taskattr_set(). The attributes of a task cannot be changed after the task is created.
group
must be set to MTAPI_GROUP_NONE
if the task is not part of a task group. Otherwise group
must be a group handle obtained by a previous call to mtapi_group_create().
On success, a task handle is returned and *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_TASK_LIMIT | Exceeded maximum number of tasks allowed. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
MTAPI_ERR_PARAMETER | Invalid attributes parameter. |
MTAPI_ERR_GROUP_INVALID | Argument is not a valid group handle. |
MTAPI_ERR_JOB_INVALID | The associated job is not valid. |
[in] | task_id | Task id |
[in] | job | Job handle |
[in] | arguments | Pointer to arguments |
[in] | arguments_size | Size of arguments |
[out] | result_buffer | Pointer to result buffer |
[in] | result_size | Size of one result |
[in] | attributes | Pointer to attributes |
[in] | group | Group handle, may be MTAPI_GROUP_NONE |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_task_hndl_t mtapi_task_enqueue | ( | const mtapi_task_id_t | task_id, |
const mtapi_queue_hndl_t | queue, | ||
const void * | arguments, | ||
const mtapi_size_t | arguments_size, | ||
void * | result_buffer, | ||
const mtapi_size_t | result_size, | ||
const mtapi_task_attributes_t * | attributes, | ||
const mtapi_group_hndl_t | group, | ||
mtapi_status_t * | status | ||
) |
This function schedules a task for execution using a queue.
A queue is a task associated with a job. A job is associated with one or more actions. An action provides an action function, which is the executable implementation of a job.
task_id
is an optional ID provided by the application for debugging purposes. If not needed, it can be set to MTAPI_TASK_ID_NONE
. The underlying type of mtapi_task_id_t
is implementation-defined. The minimum and maximum values for task_id
may be derived from MTAPI_MIN_USER_TASK_ID
and MTAPI_MAX_USER_TASK_ID
.
queue
must be a handle to a queue obtained by a previous call to mtapi_queue_create().
If arguments_size
is not zero, then arguments must point to data of arguments_size
bytes. The arguments will be transferred by the runtime from the node where the action was created to the executing node. Marshalling of arguments is not part of the MTAPI specification and is implementation-defined.
If attributes
is MTAPI_NULL
, the task will be started with default attribute values. Otherwise attributes
must point to a task attributes object previously prepared using mtapi_taskattr_init() and mtapi_taskattr_set(). Once a task has been enqueued, its attributes may not be changed.
group
must be set to MTAPI_GROUP_NONE
if the task is not part of a task group. Otherwise group
must be a group handle obtained by a previous call to mtapi_group_create().
On success, a task handle is returned and *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_TASK_LIMIT | Exceeded maximum number of tasks allowed. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
MTAPI_ERR_PARAMETER | Invalid attributes parameter. |
MTAPI_ERR_QUEUE_INVALID | Argument is not a valid queue handle. |
[in] | task_id | Task id |
[in] | queue | Queue handle |
[in] | arguments | Pointer to arguments |
[in] | arguments_size | Size of arguments |
[out] | result_buffer | Pointer to result buffer |
[in] | result_size | Size of one result |
[in] | attributes | Pointer to task attributes |
[in] | group | Group handle, may be MTAPI_GROUP_NONE |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_task_get_attribute | ( | const mtapi_task_hndl_t | task, |
const mtapi_uint_t | attribute_num, | ||
void * | attribute, | ||
const mtapi_size_t | attribute_size, | ||
mtapi_status_t * | status | ||
) |
Returns a copy of the attribute value that corresponds to the given attribute_num
for the specified task.
The attribute value will be returned in *attribute
. Note that task attributes may be queried but may not be changed after a task has been created.
task
must be a valid handle to a task that was obtained by a previous call to mtapi_task_start() or mtapi_task_enqueue().
See mtapi_taskattr_set() for a list of predefined attribute numbers and the sizes of the attribute values. The application is responsible for allocating sufficient space for the returned attribute value and for setting attribute_size
to the exact size in bytes of the attribute value.
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 the attribute value is undefined. If this function is called on a task that no longer exists, an MTAPI_ERR_TASK_INVALID
error code will be returned.
Error code | Description |
---|---|
MTAPI_ERR_PARAMETER | Invalid attribute parameter. |
MTAPI_ERR_TASK_INVALID | Argument is not a valid task 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. |
[in] | task | Task handle |
[in] | attribute_num | Attribute id |
[out] | attribute | Pointer to attribute value |
[in] | attribute_size | Size of attribute value |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_task_cancel | ( | const mtapi_task_hndl_t | task, |
mtapi_status_t * | status | ||
) |
This function cancels a task and sets the task status to MTAPI_TASK_CANCELLED
.
task
must be a valid handle to a task that was obtained by a previous call to mtapi_task_start() or mtapi_task_enqueue().
If the execution of a task has not been started, the runtime system might remove the task from the runtime-internal task queues. If task execution is already running, an action function implemented in software can poll the task status and react accordingly.
Since the task is referenced by a task handle which can only be used node-locally, a task can be canceled only on the node where the task was created.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_TASK_INVALID | Argument is not a valid task handle. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | task | Task handle |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_task_wait | ( | const mtapi_task_hndl_t | task, |
const mtapi_timeout_t | timeout, | ||
mtapi_status_t * | status | ||
) |
This function waits for the completion of the specified task.
task
must be a valid handle to a task that was obtained by a previous call to mtapi_task_start() or mtapi_task_enqueue(). The task handle becomes invalid on a successful wait, i.e., after the task had run to completion and mtapi_task_wait() returns MTAPI_SUCCESS
.
timeout
determines how long the function should wait for tasks already started via that queue to finish. The underlying type of mtapi_timeout_t
is implementation-defined. If timeout
is a constant 0 or the symbolic constant MTAPI_NOWAIT
, this function does not block and returns immediately. If timeout
is set to MTAPI_INFINITE
the function may block infinitely. Other values for timeout
and the units of measure are implementation-defined.
Results of completed tasks can be obtained via result_buffer
associated with the task. The size of the buffer has to be equal to the result size written in the action code. If the result is not needed by the calling code, result_buffer
may be set to MTAPI_NULL
. For multi-instance tasks, the result buffer is filled by an array of all the task instances' results. I.e., the result buffer has to be allocated big enough (number of instances times size of result).
Calling mtapi_task_wait() more than once for the same task results in undefined behavior.
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below. If this function is called on a task that no longer exists, an MTAPI_ERR_TASK_INVALID
error code will be returned. status
will be MTAPI_ERR_ARG_SIZE
or MTAPI_ERR_RESULT_SIZE
if the sizes of arguments or result buffer do not match.
Error code | Description |
---|---|
MTAPI_ERR_TASK_INVALID | Argument is not a valid task handle. |
MTAPI_TIMEOUT | Timeout was reached. |
MTAPI_ERR_PARAMETER | Invalid timeout parameter. |
MTAPI_ERR_TASK_CANCELLED | The task has been canceled because of mtapi_task_cancel() was called before the task was executed or the error code was set to MTAPI_ERR_TASK_CANCELLED by mtapi_context_status_set() in the action function. |
MTAPI_ERR_WAIT_PENDING | mtapi_task_wait() had already been called for the same task and the first wait call is still pending. |
MTAPI_ERR_ACTION_CANCELLED | Action execution was canceled by the action function (mtapi_context_status_set()). |
MTAPI_ERR_ACTION_FAILED | Error set by action function (mtapi_context_status_set()). |
MTAPI_ERR_ACTION_DELETED | All actions associated with the task have been deleted before the execution of the task was started or the error code has been set in the action function to MTAPI_ERR_ACTION_DELETED by mtapi_context_status_set(). |
MTAPI_ERR_ARG_SIZE | The size of the arguments expected by action differs from arguments size of the caller. |
MTAPI_ERR_RESULT_SIZE | The size of the result buffer expected by action differs from result buffer size of the caller. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[in] | task | Task handle |
[in] | timeout | Timeout duration in milliseconds |
[out] | status | Pointer to error code, may be MTAPI_NULL |