Embedded Multicore Building Blocks V1.0.0
|
Task attributes. More...
#include <mtapi.h>
Public Types | |
typedef struct mtapi_task_attributes_struct | mtapi_task_attributes_t |
Task attributes type. More... | |
Public Member Functions | |
void | mtapi_taskattr_init (mtapi_task_attributes_t *attributes, mtapi_status_t *status) |
This function initializes a task attributes object. More... | |
void | mtapi_taskattr_set (mtapi_task_attributes_t *attributes, const mtapi_uint_t attribute_num, const void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status) |
This function sets task attribute values in a task attributes object. More... | |
Public Attributes | |
mtapi_boolean_t | is_detached |
stores MTAPI_TASK_DETACHED More... | |
mtapi_uint_t | num_instances |
stores MTAPI_TASK_INSTANCES More... | |
mtapi_uint_t | priority |
stores MTAPI_TASK_PRIORITY More... | |
mtapi_affinity_t | affinity |
stores MTAPI_TASK_AFFINITY More... | |
void * | user_data |
stores MTAPI_TASK_USER_DATA More... | |
mtapi_task_complete_function_t | complete_func |
stores MTAPI_TASK_COMPLETE_FUNCTION More... | |
mtapi_uint_t | problem_size |
stores MTAPI_TASK_PROBLEM_SIZE More... | |
Task attributes.
typedef struct mtapi_task_attributes_struct mtapi_task_attributes_t |
Task attributes type.
void mtapi_taskattr_init | ( | mtapi_task_attributes_t * | attributes, |
mtapi_status_t * | status | ||
) |
This function initializes a task attributes object.
A task attributes object is a container of task attributes. It is an optional argument passed to mtapi_task_start() or mtapi_task_enqueue() to specify non-default task attributes when starting a task.
To set task attributes to non-default values, the application must allocate a task attributes object of type mtapi_task_attributes_t
and initialize it with a call to mtapi_taskattr_init(). The application may call mtapi_taskattr_set() to specify attribute values. Calls to mtapi_taskattr_init() have no effect on task attributes after the task has started. The mtapi_task_attributes_t
object may safely be deleted by the application after the task has started.
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 attributes parameter. |
MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. |
[out] | attributes | Pointer to attributes |
[out] | status | Pointer to error code, may be MTAPI_NULL |
void mtapi_taskattr_set | ( | mtapi_task_attributes_t * | attributes, |
const mtapi_uint_t | attribute_num, | ||
const void * | attribute, | ||
const mtapi_size_t | attribute_size, | ||
mtapi_status_t * | status | ||
) |
This function sets task attribute values in a task attributes object.
A task attributes object is a container of task attributes, optionally passed to mtapi_task_start() or mtapi_task_enqueue() to specify non-default task attributes when starting a task.
attributes is a pointer to a task attributes object that was previously initialized with a call to mtapi_taskattr_init(). Calls to mtapi_taskattr_set() have no effect on task attributes after the task has been created. The task attributes object may safely be deleted by the application after the task has started.
See the table below for a list of predefined attribute numbers and the sizes of the attribute values. The application must set attribute_size to the exact size in bytes of the attribute value. Additional attributes may be defined by the implementation.
MTAPI-defined task attributes:
Attribute num | Description | Data Type | Default |
---|---|---|---|
MTAPI_TASK_DETACHED | Indicates if this is a detached task. A detached task is deleted by MTAPI runtime after execution. The task handle of detached tasks must not be used, i.e., it is not possible to wait for completion of dedicated detached tasks. But it is possible to add detached tasks to a group and wait for completion of the group. | mtapi_boolean_t | MTAPI_FALSE |
MTAPI_TASK_INSTANCES | Indicates how many parallel instances of task shall be started by MTAPI. The default case is that each task is executed exactly once. Setting this value to n, the corresponding action code will be executed n times, in parallel, if the underlying hardware allows it. (see chapter 4.1.7 Multi-Instance Tasks, page 107) | mtapi_uint_t | 1 |
MTAPI_TASK_PRIORITY | Indicates the prority this task should be run at. Priorities range from zero to one minus the maximum number of priorities specified at the call to mtapi_initialize(). | mtapi_uint_t | 0 (default priority) |
MTAPI_TASK_AFFINITY | Indicates the affinity of this task. Affinities are manipulated by the matpi_affinity_init() and mtapi_affinity_set() calls. | mtapi_affinity_t | all workers |
MTAPI_TASK_USER_DATA | Provides a pointer to some data required by the user during scheduling (e.g. in a MTAPI plugin). | void* | MTAPI_NULL |
MTAPI_TASK_COMPLETE_FUNCTION | Pointer to a function being called when the task finishes. | mtapi_task_complete_function_t | MTAPI_NULL |
On success, *status
is set to MTAPI_SUCCESS
. On error, *status
is set to the appropriate error defined below.
Error code | Description |
---|---|
MTAPI_ERR_ATTR_READONLY | Attribute cannot be modified. |
MTAPI_ERR_PARAMETER | Invalid attribute parameter. |
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,out] | attributes | Pointer to attributes |
[in] | attribute_num | Attribute id |
[in] | attribute | Pointer to attribute value |
[in] | attribute_size | Size of attribute value. may be 0, attribute is interpreted as value in that case |
[out] | status | Pointer to error code, may be MTAPI_NULL |
mtapi_boolean_t mtapi_task_attributes_struct::is_detached |
stores MTAPI_TASK_DETACHED
mtapi_uint_t mtapi_task_attributes_struct::num_instances |
stores MTAPI_TASK_INSTANCES
mtapi_uint_t mtapi_task_attributes_struct::priority |
stores MTAPI_TASK_PRIORITY
mtapi_affinity_t mtapi_task_attributes_struct::affinity |
stores MTAPI_TASK_AFFINITY
void* mtapi_task_attributes_struct::user_data |
stores MTAPI_TASK_USER_DATA
mtapi_task_complete_function_t mtapi_task_attributes_struct::complete_func |
stores MTAPI_TASK_COMPLETE_FUNCTION
mtapi_uint_t mtapi_task_attributes_struct::problem_size |
stores MTAPI_TASK_PROBLEM_SIZE