Embedded Multicore Building Blocks V1.0.0
|
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... | |
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.
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. |
[in] | queue_id | Queue id |
[in] | job | Job handle |
[in] | attributes | Pointer to attributes |
[out] | status | Pointer 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. |
[in] | queue | Queue handle |
[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 |
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. |
[in] | queue | Queue handle |
[in] | attribute_num | Attribute id |
[out] | attribute | Pointer to attribute value |
[in] | attribute_size | Size of attribute value |
[out] | status | Pointer 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. |
queue_id
, invalid handle on error [in] | queue_id | Queue id |
[in] | domain_id | Domain id |
[out] | status | Pointer 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:
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.MTAPI_ERR_QUEUE_DELETED
.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. |
[in] | queue | Queue handle |
[in] | timeout | Timeout duration in milliseconds |
[out] | status | Pointer 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:
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.MTAPI_QUEUE_RETAIN
attribute is set to MTAPI_TRUE
. A call to mtapi_task_wait() will return the status MTAPI_ERR_QUEUE_DISABLED
.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. |
[in] | queue | Queue handle |
[in] | timeout | Timeout duration in milliseconds |
[out] | status | Pointer 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. |
[in] | queue | Queue handle |
[out] | status | Pointer to error code, may be MTAPI_NULL |