Embedded Multicore Building Blocks V1.0.0
Classes | Functions

Queues for controlling the scheduling policy of tasks. More...

Classes

struct  mtapi_queue_attributes_struct
 Queue attributes. More...
 
struct  mtapi_queue_hndl_struct
 Queue handle. More...
 

Functions

mtapi_queue_hndl_t mtapi_queue_create (const mtapi_queue_id_t queue_id, const mtapi_job_hndl_t job, const mtapi_queue_attributes_t *attributes, mtapi_status_t *status)
 This function creates a software queue object and associates it with the specified job. More...
 
void mtapi_queue_set_attribute (const mtapi_queue_hndl_t queue, const mtapi_uint_t attribute_num, const void *attribute, const mtapi_size_t attribute_size, mtapi_status_t *status)
 Changes the attribute value that corresponds to the given attribute_num for the specified queue. More...
 
void mtapi_queue_get_attribute (const mtapi_queue_hndl_t queue, 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 the specified queue. More...
 
mtapi_queue_hndl_t mtapi_queue_get (const mtapi_queue_id_t queue_id, const mtapi_domain_t domain_id, mtapi_status_t *status)
 This function converts a domain-wide queue_id into a node-local queue handle. More...
 
void mtapi_queue_delete (const mtapi_queue_hndl_t queue, const mtapi_timeout_t timeout, mtapi_status_t *status)
 This function deletes the specified software queue. More...
 
void mtapi_queue_disable (const mtapi_queue_hndl_t queue, const mtapi_timeout_t timeout, mtapi_status_t *status)
 This function disables the specified queue in such a way that it can be resumed later. More...
 
void mtapi_queue_enable (const mtapi_queue_hndl_t queue, mtapi_status_t *status)
 This function may be called from any node with a valid queue handle to re-enable a queue previously disabled with mtapi_queue_disable(). More...
 

Detailed Description

Queues for controlling the scheduling policy of tasks.

The default scheduling policy for queues is ordered task execution. Tasks that have to be executed sequentially are enqueued into the same queue. In this case every queue is associated with exactly one action. Tasks started via different queues can be executed in parallel. This is needed for packet processing applications, for example: each stream is processed by one queue. This ensures sequential processing of packets belonging to the same stream. Different streams are processed in parallel.

Queues were made explicit in MTAPI. This allows mapping of queues onto hardware queues, if available. One MTAPI queue is associated with one action, or for purposes of load balancing, with actions implementing the same job on different nodes.

Function Documentation

mtapi_queue_hndl_t mtapi_queue_create ( const mtapi_queue_id_t  queue_id,
const mtapi_job_hndl_t  job,
const mtapi_queue_attributes_t attributes,
mtapi_status_t *  status 
)

This function creates a software queue object and associates it with the specified job.

A job is associated with one or more actions that provide the executable implementation of the job. Hardware queues are considered to be pre-existent and do not need to be created.

queue_id is an identifier of implementation-defined type that must be supplied by the application. If queue_id is set to MTAPI_QUEUE_ID_NONE, the queue will be accessible only on the node on which it was created by using the returned queue handle. Otherwise the application may supply a queue_id by which the queue can be referenced domain-wide using mtapi_queue_get() to convert the id into a handle. The minimum and maximum values for queue_id may be derived from MTAPI_MIN_USER_QUEUE_ID and MTAPI_MAX_USER_QUEUE_ID.

job is a handle to a job obtained by a previous call to mtapi_job_get(). If attributes is MTAPI_NULL, the queue will be created with default attribute values. Otherwise attributes must point to a queue attributes object previously prepared using mtapi_queueattr_init() and mtapi_queueattr_set().

There is an implementation-defined maximum number of queues permitted.

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

On success, a queue handle is returned and *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below. In the case where the queue already exists, *status will be set to MTAPI_QUEUE_EXISTS and the handle returned will not be a valid handle.

Error code Description
MTAPI_ERR_QUEUE_INVALID The queue_id is not a valid queue id.
MTAPI_ERR_QUEUE_EXISTS This queue is already created.
MTAPI_ERR_QUEUE_LIMIT Exceeded maximum number of queues allowed.
MTAPI_ERR_NODE_NOTINIT The calling node is not initialized.
MTAPI_ERR_PARAMETER Invalid attributes parameter.
MTAPI_ERR_JOB_INVALID The associated job is not valid.
See also
mtapi_queue_get(), mtapi_job_get(), mtapi_queueattr_init(), mtapi_queueattr_set()
Returns
Handle to newly created queue, invalid handle on error
Concurrency
Thread-safe
Parameters
[in]queue_idQueue id
[in]jobJob handle
[in]attributesPointer to attributes
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_queue_set_attribute ( const mtapi_queue_hndl_t  queue,
const mtapi_uint_t  attribute_num,
const void *  attribute,
const mtapi_size_t  attribute_size,
mtapi_status_t *  status 
)

Changes the attribute value that corresponds to the given attribute_num for the specified queue.

See mtapi_queueattr_set() 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.

On success, *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below and the attribute value is undefined.

Error code Description
MTAPI_ERR_PARAMETER Invalid attribute parameter.
MTAPI_ERR_QUEUE_INVALID Argument is not a valid queue 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_queueattr_set()
Concurrency
Not thread-safe
Parameters
[in]queueQueue handle
[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
void mtapi_queue_get_attribute ( const mtapi_queue_hndl_t  queue,
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 the specified queue.

attribute must point to a location in memory sufficiently large to hold the returned attribute value. See mtapi_queueattr_set() 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.

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 queue that no longer exists, an MTAPI_ERR_QUEUE_INVALID error will be returned.

Error code Description
MTAPI_ERR_PARAMETER Invalid attribute parameter.
MTAPI_ERR_QUEUE_INVALID Argument is not a valid queue 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_queueattr_set()
Concurrency
Thread-safe and wait-free
Parameters
[in]queueQueue 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
mtapi_queue_hndl_t mtapi_queue_get ( const mtapi_queue_id_t  queue_id,
const mtapi_domain_t  domain_id,
mtapi_status_t *  status 
)

This function converts a domain-wide queue_id into a node-local queue handle.

queue_id must match the queue_id that was associated with a software queue that was created with mtapi_queue_create(), or it must be a valid predefined queue identifier known a priori to the runtime and application (e.g., to reference a hardware queue. The minimum and maximum values for queue_id may be derived from MTAPI_MIN_USER_QUEUE_ID and MTAPI_MAX_USER_QUEUE_ID.

On success, the queue handle is returned and *status is set to MTAPI_SUCCESS. On error, *status is set to the appropriate error defined below. If this function is called on a queue that no longer exists, an MTAPI_ERR_QUEUE_INVALID error will be returned.

Error code Description
MTAPI_ERR_QUEUE_INVALID The queue_id parameter does not refer to a valid queue or it is set to MTAPI_QUEUE_ID_ANY.
MTAPI_ERR_NODE_NOTINIT The node/domain is not initialized.
MTAPI_ERR_DOMAIN_NOTSHARED This resource cannot be shared by this domain.
See also
mtapi_queue_create()
Returns
Handle to preexisting queue with given queue_id, invalid handle on error
Concurrency
Thread-safe
Parameters
[in]queue_idQueue id
[in]domain_idDomain id
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_queue_delete ( const mtapi_queue_hndl_t  queue,
const mtapi_timeout_t  timeout,
mtapi_status_t *  status 
)

This function deletes the specified software queue.

Hardware queues are perpetual and cannot be deleted.

queue must be a valid handle to an existing queue.

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 deletes the queue 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.

This function can be called from any node that has a valid queue handle. Tasks previously enqueued in a queue that has been deleted may still be executed depending on their internal state:

  • If mtapi_queue_delete() is called on a queue that is currently executing an action, the task state of the corresponding task will be set to MTAPI_TASK_CANCELLED and execution will continue. To accomplish this, the action function must poll the task state with mtapi_context_taskstate_get(). A call to mtapi_task_wait() on the task executing this code will return the status set by mtapi_context_status_set(), or MTAPI_SUCCESS if not explicitly set.
  • Tasks that are enqueued and waiting for execution by the MTAPI runtime environment when mtapi_queue_delete() is called will not be executed any more. A call to mtapi_task_wait() will return the status MTAPI_ERR_QUEUE_DELETED.
  • Tasks that are enqueued after deletion of the queue will return a status of MTAPI_ERR_QUEUE_INVALID.

If this function is called on a queue that no longer exists, an MTAPI_ERR_QUEUE_INVALID status will be returned. A call to mtapi_queue_get() on a deleted queue will return MTAPI_ERR_QUEUE_INVALID as well, as long as no new queue has been created for the same queue ID.

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

Error code Description
MTAPI_ERR_QUEUE_INVALID Argument is not a valid queue handle.
MTAPI_ERR_NODE_NOTINIT The calling node is not initialized.
MTAPI_TIMEOUT Timeout was reached.
See also
mtapi_context_taskstate_get(), mtapi_context_status_set(), mtapi_task_wait(), mtapi_queue_get()
Concurrency
Thread-safe
Parameters
[in]queueQueue handle
[in]timeoutTimeout duration in milliseconds
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_queue_disable ( const mtapi_queue_hndl_t  queue,
const mtapi_timeout_t  timeout,
mtapi_status_t *  status 
)

This function disables the specified queue in such a way that it can be resumed later.

This is needed to perform certain maintenance tasks. It can be called by any node that has a valid queue handle.

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 deletes the queue 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.

Tasks previously enqueued in a queue that has been disabled may still be executed depending on their internal state:

  • If mtapi_queue_disable() is called on a queue that is currently executing an action, the task state of the corresponding task will be set to MTAPI_TASK_CANCELLED and execution will continue. To accomplish this, the action function must poll the task state by calling mtapi_context_taskstate_get(). A call to mtapi_task_wait() on the task executing this code will return the status set by mtapi_context_status_set(), or MTAPI_SUCCESS if not explicitly set.
  • Tasks that are enqueued and waiting for execution by the MTAPI runtime environment when mtapi_queue_disable() is called will not be executed anymore. They will be held in anticipation the queue is enabled again if the MTAPI_QUEUE_RETAIN attribute is set to MTAPI_TRUE. A call to mtapi_task_wait() will return the status MTAPI_ERR_QUEUE_DISABLED.
  • Tasks that are enqueued after the queue had been disabled will return MTAPI_ERR_QUEUE_DISABLED if the MTAPI_QUEUE_RETAIN attribute is set to MTAPI_FALSE.

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

Error code Description
MTAPI_ERR_QUEUE_INVALID Argument is not a valid queue handle.
MTAPI_ERR_NODE_NOTINIT The calling node is not initialized.
MTAPI_TIMEOUT Timeout was reached.
See also
mtapi_context_taskstate_get(), mtapi_context_status_set(), mtapi_task_wait()
Concurrency
Thread-safe
Parameters
[in]queueQueue handle
[in]timeoutTimeout duration in milliseconds
[out]statusPointer to error code, may be MTAPI_NULL
void mtapi_queue_enable ( const mtapi_queue_hndl_t  queue,
mtapi_status_t *  status 
)

This function may be called from any node with a valid queue handle to re-enable a queue previously disabled with mtapi_queue_disable().

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

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