Embedded Multicore Building Blocks V1.0.0
Public Types | Public Member Functions | Public Attributes | List of all members
mtapi_task_attributes_struct Struct Reference

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

Detailed Description

Task attributes.

Member Typedef Documentation

Task attributes type.

Member Function Documentation

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.
See also
mtapi_task_start(), mtapi_task_enqueue(), mtapi_taskattr_set()
Concurrency
Not thread-safe
Parameters
[out]attributesPointer to attributes
[out]statusPointer 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.
See also
mtapi_task_start(), mtapi_task_enqueue(), mtapi_taskattr_init()
Concurrency
Not thread-safe
Parameters
[in,out]attributesPointer to attributes
[in]attribute_numAttribute id
[in]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

Member Data Documentation

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