Embedded Multicore Building Blocks V1.0.0
Classes | Functions
Task Groups

Facilities for synchronizing on groups of tasks. More...

Classes

struct  mtapi_group_attributes_struct
 Group attributes. More...
 
struct  mtapi_group_hndl_struct
 Group handle. More...
 

Functions

mtapi_group_hndl_t mtapi_group_create (const mtapi_group_id_t group_id, const mtapi_group_attributes_t *attributes, mtapi_status_t *status)
 This function creates a task group and returns a handle to the group. More...
 
void mtapi_group_set_attribute (const mtapi_group_hndl_t group, const mtapi_uint_t attribute_num, void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status)
 Changes the value of the attribute that corresponds to the given attribute_num for the specified task group. More...
 
void mtapi_group_get_attribute (const mtapi_group_hndl_t group, const mtapi_uint_t attribute_num, void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status)
 Returns the attribute value that corresponds to the given attribute_num for this task group. More...
 
void mtapi_group_wait_all (const mtapi_group_hndl_t group, const mtapi_timeout_t timeout, mtapi_status_t *status)
 This function waits for the completion of a task group. More...
 
void mtapi_group_wait_any (const mtapi_group_hndl_t group, void **result, const mtapi_timeout_t timeout, mtapi_status_t *status)
 This function waits for the completion of any task in a task group. More...
 
void mtapi_group_delete (const mtapi_group_hndl_t group, mtapi_status_t *status)
 This function deletes a task group. More...
 

Detailed Description

Facilities for synchronizing on groups of tasks.

This concept is similar to barrier synchronization of threads. MTAPI specifies a minimal task group feature set in order to allow small and efficient implementations.

Function Documentation

mtapi_group_hndl_t mtapi_group_create ( const mtapi_group_id_t  group_id,
const mtapi_group_attributes_t attributes,
mtapi_status_t *  status 
)

This function creates a task group and returns a handle to the group.

After a group is created, a task may be associated with a group when the task is started with mtapi_task_start() or mtapi_task_enqueue().

group_id is an optional ID provided by the application for debugging purposes. If not needed, it can be set to MTAPI_GROUP_ID_NONE. The underlying type of mtapi_group_id_t is implementation-defined. The minimum and maximum values for group_id may be derived from MTAPI_MIN_USER_GROUP_ID and MTAPI_MAX_USER_GROUP_ID.

If attributes is MTAPI_NULL, the group will be created with default attribute values. Otherwise attributes must point to a group attributes object previously prepared using mtapi_groupattr_init() and mtapi_groupattr_set().

On success, a group 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_GROUP_LIMIT Exceeded maximum number of groups allowed.
MTAPI_ERR_NODE_NOTINIT The calling node is not initialized.
MTAPI_ERR_PARAMETER Invalid attributes parameter.
See also
mtapi_task_start(), mtapi_task_enqueue(), mtapi_groupattr_init(), mtapi_groupattr_set()
Returns
Handle to newly created group, invalid handle on error
Concurrency
Thread-safe
Dynamic memory allocation
This function allocates a new queue for tracking completion of the tasks belonging to the group.
Parameters
[in]group_idGroup id
[in]attributesPointer to attributes
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_group_set_attribute ( const mtapi_group_hndl_t  group,
const mtapi_uint_t  attribute_num,
void *  attribute,
const mtapi_size_t  attribute_size,
mtapi_status_t *  status 
)

Changes the value of the attribute that corresponds to the given attribute_num for the specified task group.

attribute must point to the attribute value, and attribute_size must be set to the exact size of the attribute value. See mtapi_groupattr_set() for a list of predefined attribute numbers and the sizes of their values.

On success, *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below.

Error code Description
MTAPI_ERR_PARAMETER Invalid attribute parameter.
MTAPI_ERR_GROUP_INVALID Argument is not a valid group 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_groupattr_set()
Concurrency
Not thread-safe
Parameters
[in]groupGroup handle
[in]attribute_numAttribute id
[out]attributePointer to attribute value
[in]attribute_sizeSize of attribute value. may be 0, attribute is interpreted as value in that case
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_group_get_attribute ( const mtapi_group_hndl_t  group,
const mtapi_uint_t  attribute_num,
void *  attribute,
const mtapi_size_t  attribute_size,
mtapi_status_t *  status 
)

Returns the attribute value that corresponds to the given attribute_num for this task group.

attribute must point to the location where the attribute value is to be returned, and attribute_size must be set to the exact size of the attribute value. See mtapi_groupattr_set() for a list of predefined attribute numbers and the sizes of their values.

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 *attribute is undefined. If this function is called on a group that no longer exists, an MTAPI_ERR_GROUP_INVALID error code will be returned.

Error code Description
MTAPI_ERR_PARAMETER Invalid attribute parameter.
MTAPI_ERR_GROUP_INVALID Argument is not a valid group 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_groupattr_set()
Concurrency
Thread-safe and wait-free
Parameters
[in]groupGroup 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_group_wait_all ( const mtapi_group_hndl_t  group,
const mtapi_timeout_t  timeout,
mtapi_status_t *  status 
)

This function waits for the completion of a task group.

Tasks may be associated with groups when the tasks are started. Each task is associated with one or more actions. This function returns when all the associated action functions have completed or canceled. The group handle becomes invalid if this function returns MTAPI_SUCCESS.

timeout determines how long the function should wait for tasks already started in the group 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.

To obtain results from a task, the application should call mtapi_group_wait_any() instead.

During execution, an action function may optionally call mtapi_context_status_set() to set a task status that will be returned in this function in *status. If multiple action functions set different task status values, it is implementation-defined which of those is returned in mtapi_group_wait_all(). The following task status values may be set by an action function: MTAPI_ERR_TASK_CANCELLED, MTAPI_ERR_ACTION_CANCELLED, MTAPI_ERR_ACTION_FAILED, and MTAPI_ERR_ACTION_DELETED.

On success, *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below.

Error code Description
MTAPI_TIMEOUT Timeout was reached.
MTAPI_ERR_GROUP_INVALID Argument is not a valid task handle.
MTAPI_ERR_WAIT_PENDING mtapi_group_wait_all() had already been called for the same group and the first wait call is still pending.
MTAPI_ERR_PARAMETER Invalid timeout parameter.
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.
MTAPI_GROUP_COMPLETED Group completed, i.e., there are no more task to wait for in the group.
MTAPI_ERR_TASK_CANCELLED At least one 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_ACTION_CANCELLED The action execution of at least one task was canceled by the action function (mtapi_context_status_set()).
MTAPI_ERR_ACTION_FAILED Error set by at least one 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().
See also
mtapi_group_wait_any(), mtapi_context_status_set(), mtapi_task_cancel()
Concurrency
Thread-safe
Parameters
[in]groupGroup handle
[in]timeoutTimeout duration in milliseconds
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_group_wait_any ( const mtapi_group_hndl_t  group,
void **  result,
const mtapi_timeout_t  timeout,
mtapi_status_t *  status 
)

This function waits for the completion of any task in a task group.

Tasks may be associated with groups when the tasks are started. Each task is associated with one or more actions. This function returns when any of the associated action functions have completed or have been canceled.

The group handle does not become invalid if this function returns MTAPI_SUCCESS. The group handle becomes invalid if this function returns MTAPI_GROUP_COMPLETED.

group must be a valid group handle obtained by a previous call to mtapi_group_create().

Action functions may pass results that will be available in *result after mtapi_group_wait_any() returns. If the results are not needed, result may be set to MTAPI_NULL. Otherwise, result must point to an area in memory of sufficient size to hold the array of results from the completed task(s). The size of the result buffer is given in the argument result_buffer_size that the runtime passes to an action function upon invocation.

timeout determines how long the function should wait for a task in the group 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.

During execution, an action function may optionally call mtapi_context_status_set() to set a task status that will be returned in this function in *status. The following task status values may be set by an action function: MTAPI_ERR_TASK_CANCELLED, MTAPI_ERR_ACTION_CANCELLED, MTAPI_ERR_ACTION_FAILED, and MTAPI_ERR_ACTION_DELETED.

On success, *status is either set to MTAPI_SUCCESS if one of the tasks in the group completed or to MTAPI_GROUP_COMPLETED if all tasks of the group have completed and successfully waited for. On error, *status is set to the appropriate error defined below.

Error code Description
MTAPI_TIMEOUT Timeout was reached.
MTAPI_ERR_GROUP_INVALID Argument is not a valid task handle.
MTAPI_ERR_PARAMETER Invalid timeout parameter.
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.
MTAPI_GROUP_COMPLETED Group completed, i.e., there are no more tasks to wait for in the group.
MTAPI_ERR_TASK_CANCELLED The task has been canceled because 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 code.
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 code to MTAPI_ERR_ACTION_DELETED by mtapi_context_status_set().
See also
mtapi_group_create(), mtapi_context_status_set(), mtapi_task_cancel()
Concurrency
Thread-safe
Parameters
[in]groupGroup handle
[out]resultPointer to result buffer supplied at task start
[in]timeoutTimeout duration in milliseconds
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_group_delete ( const mtapi_group_hndl_t  group,
mtapi_status_t *  status 
)

This function deletes a task group.

Deleting a group does not have any influence on tasks belonging to the group. Adding tasks to a group that is already deleted will result in an MTAPI_ERR_GROUP_INVALID error.

On success, *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below.

Error code Description
MTAPI_ERR_GROUP_INVALID Argument is not a valid group handle.
MTAPI_ERR_NODE_NOTINIT The calling node is not initialized.
Concurrency
Thread-safe
Parameters
[in]groupGroup handle
[out]statusPointer to error code, may be MTAPI_NULL