Embedded Multicore Building Blocks V1.0.0
Classes | Functions

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

Detailed Description

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.

Function Documentation

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.
See also
mtapi_job_get(), mtapi_taskattr_init(), mtapi_taskattr_set(), mtapi_group_create()
Returns
Handle to newly started task, invalid handle on error
Concurrency
Thread-safe
Parameters
[in]task_idTask id
[in]jobJob handle
[in]argumentsPointer to arguments
[in]arguments_sizeSize of arguments
[out]result_bufferPointer to result buffer
[in]result_sizeSize of one result
[in]attributesPointer to attributes
[in]groupGroup handle, may be MTAPI_GROUP_NONE
[out]statusPointer 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.
See also
mtapi_queue_create(), mtapi_taskattr_init(), mtapi_taskattr_set(), mtapi_group_create()
Returns
Handle to newly enqueued task, invalid handle on error
Concurrency
Thread-safe
Parameters
[in]task_idTask id
[in]queueQueue handle
[in]argumentsPointer to arguments
[in]arguments_sizeSize of arguments
[out]result_bufferPointer to result buffer
[in]result_sizeSize of one result
[in]attributesPointer to task attributes
[in]groupGroup handle, may be MTAPI_GROUP_NONE
[out]statusPointer 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.
See also
mtapi_task_start(), mtapi_task_enqueue(), mtapi_taskattr_set()
Concurrency
Thread-safe and wait-free
Parameters
[in]taskTask handle
[in]attribute_numAttribute id
[out]attributePointer to attribute value
[in]attribute_sizeSize of attribute value
[out]statusPointer 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.
See also
mtapi_task_start(), mtapi_task_enqueue()
Concurrency
Thread-safe and wait-free
Parameters
[in]taskTask handle
[out]statusPointer 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.
See also
mtapi_task_start(), mtapi_task_enqueue(), mtapi_task_wait(), mtapi_task_cancel(), mtapi_context_status_set()
Concurrency
Thread-safe
Parameters
[in]taskTask handle
[in]timeoutTimeout duration in milliseconds
[out]statusPointer to error code, may be MTAPI_NULL