API Reference Manual
1.47.0
|
Queues for event passing and scheduling.
Data Structures | |
struct | odp_queue_capability_t |
Queue capabilities. More... | |
struct | odp_queue_param_t |
ODP Queue parameters. More... | |
struct | odp_queue_info_t |
Queue information Retrieve information about a queue with odp_queue_info() More... | |
struct | odp_aggr_enq_param_t |
Event aggregator enqueuing parameters. More... | |
struct | odp_aggr_enq_profile_t |
Event aggregator enqueuing profile. More... | |
Macros | |
#define | ODP_QUEUE_INVALID ((odp_queue_t)0) |
Invalid queue. | |
#define | ODP_QUEUE_NAME_LEN 32 |
Maximum queue name length, including the null character. | |
Typedefs | |
typedef _odp_abi_queue_t * | odp_queue_t |
ODP queue. | |
typedef enum odp_queue_type_t | odp_queue_type_t |
Queue type. | |
typedef enum odp_queue_op_mode_t | odp_queue_op_mode_t |
Queue operation mode. | |
typedef enum odp_nonblocking_t | odp_nonblocking_t |
Non-blocking level. More... | |
typedef enum odp_queue_order_t | odp_queue_order_t |
Original event order maintenance options. More... | |
typedef struct odp_queue_capability_t | odp_queue_capability_t |
Queue capabilities. | |
typedef struct odp_queue_param_t | odp_queue_param_t |
ODP Queue parameters. | |
typedef struct odp_queue_info_t | odp_queue_info_t |
Queue information Retrieve information about a queue with odp_queue_info() | |
typedef struct odp_aggr_enq_param_t | odp_aggr_enq_param_t |
Event aggregator enqueuing parameters. | |
typedef struct odp_aggr_enq_profile_t | odp_aggr_enq_profile_t |
Event aggregator enqueuing profile. More... | |
Enumerations | |
enum | odp_queue_type_t { ODP_QUEUE_TYPE_PLAIN = 0 , ODP_QUEUE_TYPE_SCHED , ODP_QUEUE_TYPE_AGGR } |
Queue type. More... | |
enum | odp_queue_op_mode_t { ODP_QUEUE_OP_MT = 0 , ODP_QUEUE_OP_MT_UNSAFE , ODP_QUEUE_OP_DISABLED } |
Queue operation mode. More... | |
enum | odp_nonblocking_t { ODP_BLOCKING = 0 , ODP_NONBLOCKING_LF , ODP_NONBLOCKING_WF } |
Non-blocking level. More... | |
enum | odp_queue_order_t { ODP_QUEUE_ORDER_KEEP = 0 , ODP_QUEUE_ORDER_IGNORE } |
Original event order maintenance options. More... | |
Functions | |
odp_queue_t | odp_queue_create (const char *name, const odp_queue_param_t *param) |
Queue create. More... | |
int | odp_queue_create_multi (const char *name[], const odp_queue_param_t param[], odp_bool_t share_param, odp_queue_t queue[], int num) |
Create multiple queues. More... | |
int | odp_queue_destroy (odp_queue_t queue) |
Destroy ODP queue. More... | |
int | odp_queue_destroy_multi (odp_queue_t queue[], int num) |
Destroy multiple queues. More... | |
odp_queue_t | odp_queue_lookup (const char *name) |
Find a queue by name. More... | |
int | odp_queue_capability (odp_queue_capability_t *capa) |
Query queue capabilities. More... | |
int | odp_queue_context_set (odp_queue_t queue, void *context, uint32_t len) |
Set queue context. More... | |
void * | odp_queue_context (odp_queue_t queue) |
Get queue context. More... | |
odp_queue_t | odp_queue_aggr (odp_queue_t queue, uint32_t aggr_index) |
Get a queue handle of an event aggregator associated with a queue. More... | |
int | odp_queue_enq (odp_queue_t queue, odp_event_t ev) |
Enqueue an event to a queue. More... | |
int | odp_queue_enq_multi (odp_queue_t queue, const odp_event_t events[], int num) |
Enqueue multiple events to a queue. More... | |
int | odp_queue_enq_aggr (odp_queue_t queue, odp_event_t ev, const odp_aggr_enq_param_t *param) |
Enqueue an event with event aggregation hints. More... | |
void | odp_aggr_enq_param_init (odp_aggr_enq_param_t *param) |
Initialize aggregator enqueue parameters to their default values. More... | |
odp_event_t | odp_queue_deq (odp_queue_t queue) |
Dequeue an event from a queue. More... | |
int | odp_queue_deq_multi (odp_queue_t queue, odp_event_t events[], int num) |
Dequeue multiple events from a queue. More... | |
odp_queue_type_t | odp_queue_type (odp_queue_t queue) |
Queue type. More... | |
odp_schedule_sync_t | odp_queue_sched_type (odp_queue_t queue) |
Queue schedule type. More... | |
odp_schedule_prio_t | odp_queue_sched_prio (odp_queue_t queue) |
Queue priority. More... | |
odp_schedule_group_t | odp_queue_sched_group (odp_queue_t queue) |
Queue group. More... | |
uint32_t | odp_queue_lock_count (odp_queue_t queue) |
Queue lock count. More... | |
uint64_t | odp_queue_to_u64 (odp_queue_t hdl) |
Get printable value for an odp_queue_t. More... | |
void | odp_queue_param_init (odp_queue_param_t *param) |
Initialize queue params. More... | |
int | odp_queue_info (odp_queue_t queue, odp_queue_info_t *info) |
Retrieve information about a queue. More... | |
void | odp_queue_print (odp_queue_t queue) |
Print queue info. More... | |
void | odp_queue_print_all (void) |
Print debug info about all queues. More... | |
typedef enum odp_nonblocking_t odp_nonblocking_t |
Non-blocking level.
A non-blocking level defines implementation guarantees for application progress when multiple threads operate on the same resource (e.g. a queue) simultaneously. The first level (ODP_BLOCKING) does not have any block freedom guarantees, but a suspending thread may block the other threads for the entire time it remains suspended (infinitely if crashed). On the contrary, actual non-blocking levels provide guarantees of progress:
ODP_NONBLOCKING_LF: A non-blocking and lock-free implementation guarantees that at least one of the threads successfully completes its operations, regardless of what other threads do. Application progress is guaranteed, but individual threads may starve while trying to execute their operations on the shared resource.
ODP_NONBLOCKING_WF: A non-blocking and wait-free implementation guarantees application progress with starvation freedom. All threads are guaranteed to complete their operations in a bounded number of steps, regardless of what other threads do.
Non-blocking levels are listed from the weakest to the strongest guarantee of block freedom. Performance of a non-blocking implementation may be lower than the blocking one. Non-blocking guarantees are important e.g. for real-time applications when real-time and non real-time threads share a resource.
typedef enum odp_queue_order_t odp_queue_order_t |
Original event order maintenance options.
Options to keep or ignore the original event order of a source queue. This option is relevant for (plain or parallel scheduled) queues that are destinations for events enqueued while holding an ordered queue synchronization context. By default, an ordered context maintains original event order regardless of the destination queue type. Event re-ordering may cause extra synchronization effort for implementation and a long delay before application can receive a re-ordered event from the destination queue. This is wasteful and in some cases the extra delay is not acceptable for those destination queues that do not need to maintain the original event order. Application can use ODP_QUEUE_ORDER_IGNORE option to prevent implementation from performing unnecessary event re-ordering and negative side-effects of that.
typedef struct odp_aggr_enq_profile_t odp_aggr_enq_profile_t |
Event aggregator enqueuing profile.
This profile affects how enqueuing to an event aggregator is done. Depending on the event being enqueued and the profile chosen, start-of-vector, end-of-vector or other similar hints may be passed to the aggregator along with the event.
enum odp_queue_type_t |
Queue type.
Definition at line 45 of file api/spec/queue_types.h.
enum odp_queue_op_mode_t |
Queue operation mode.
Definition at line 73 of file api/spec/queue_types.h.
enum odp_nonblocking_t |
Non-blocking level.
A non-blocking level defines implementation guarantees for application progress when multiple threads operate on the same resource (e.g. a queue) simultaneously. The first level (ODP_BLOCKING) does not have any block freedom guarantees, but a suspending thread may block the other threads for the entire time it remains suspended (infinitely if crashed). On the contrary, actual non-blocking levels provide guarantees of progress:
ODP_NONBLOCKING_LF: A non-blocking and lock-free implementation guarantees that at least one of the threads successfully completes its operations, regardless of what other threads do. Application progress is guaranteed, but individual threads may starve while trying to execute their operations on the shared resource.
ODP_NONBLOCKING_WF: A non-blocking and wait-free implementation guarantees application progress with starvation freedom. All threads are guaranteed to complete their operations in a bounded number of steps, regardless of what other threads do.
Non-blocking levels are listed from the weakest to the strongest guarantee of block freedom. Performance of a non-blocking implementation may be lower than the blocking one. Non-blocking guarantees are important e.g. for real-time applications when real-time and non real-time threads share a resource.
Definition at line 129 of file api/spec/queue_types.h.
enum odp_queue_order_t |
Original event order maintenance options.
Options to keep or ignore the original event order of a source queue. This option is relevant for (plain or parallel scheduled) queues that are destinations for events enqueued while holding an ordered queue synchronization context. By default, an ordered context maintains original event order regardless of the destination queue type. Event re-ordering may cause extra synchronization effort for implementation and a long delay before application can receive a re-ordered event from the destination queue. This is wasteful and in some cases the extra delay is not acceptable for those destination queues that do not need to maintain the original event order. Application can use ODP_QUEUE_ORDER_IGNORE option to prevent implementation from performing unnecessary event re-ordering and negative side-effects of that.
Definition at line 165 of file api/spec/queue_types.h.
odp_queue_t odp_queue_create | ( | const char * | name, |
const odp_queue_param_t * | param | ||
) |
Queue create.
Create a queue according to the queue parameters. The use of queue name is optional. Unique names are not required. However, odp_queue_lookup() returns only a single matching queue. Use odp_queue_param_init() to initialize parameters into their default values. Default values are also used when 'param' pointer is NULL.
name | Name of the queue or NULL. Maximum string length is ODP_QUEUE_NAME_LEN, including the null character. |
param | Queue parameters. Uses defaults if NULL. |
ODP_QUEUE_INVALID | on failure |
int odp_queue_create_multi | ( | const char * | name[], |
const odp_queue_param_t | param[], | ||
odp_bool_t | share_param, | ||
odp_queue_t | queue[], | ||
int | num | ||
) |
Create multiple queues.
Otherwise like odp_queue_create(), but creates multiple queues with a single call. The output queue handles are written in the same order as input parameters. A single odp_queue_create_multi() call is equivalent to calling odp_queue_create() 'num' times in row.
If 'share_param' value is false, 'param' array must contain 'num' elements. If the value is true, only a single element is required and it's used as queue parameters for all created queues. If 'name' array is not NULL, the array must contain 'num' elements.
name | Array of queue name pointers or NULL. NULL is also valid queue name pointer value. | |
param | Array of queue parameters | |
share_param | If true, use same parameters ('param[0]') for all queues. | |
[out] | queue | Array of queue handles for output |
num | Number of queues to create |
<0 | on failure |
int odp_queue_destroy | ( | odp_queue_t | queue | ) |
Destroy ODP queue.
Destroys ODP queue. The queue must be empty and detached from other ODP API (crypto, pktio, classifier, timer, etc). Application must ensure that no other operations on this queue are invoked in parallel. Otherwise behavior is undefined.
queue | Queue handle |
0 | on success |
<0 | on failure |
int odp_queue_destroy_multi | ( | odp_queue_t | queue[], |
int | num | ||
) |
Destroy multiple queues.
Otherwise like odp_queue_destroy(), but destroys multiple queues with a single call.
queue | Array of queue handles |
num | Number of queues to destroy |
Number | of queues actually destroyed (1 ... num) |
<0 | on failure |
odp_queue_t odp_queue_lookup | ( | const char * | name | ) |
Find a queue by name.
name | Queue name |
ODP_QUEUE_INVALID | on failure |
int odp_queue_capability | ( | odp_queue_capability_t * | capa | ) |
Query queue capabilities.
Outputs queue capabilities on success.
[out] | capa | Pointer to capability structure for output |
0 | on success |
<0 | on failure |
int odp_queue_context_set | ( | odp_queue_t | queue, |
void * | context, | ||
uint32_t | len | ||
) |
Set queue context.
It is the responsibility of the user to ensure that the queue context is stored in a location accessible by all threads that attempt to access it.
queue | Queue handle |
context | Address to the queue context |
len | Queue context data length in bytes |
0 | on success |
<0 | on failure |
void* odp_queue_context | ( | odp_queue_t | queue | ) |
Get queue context.
Returns previously stored queue context pointer. The context pointer may be set with odp_queue_context_set() or during queue creation (see odp_queue_param_t). The pointer value is set to NULL by default.
queue | Queue handle |
NULL | on failure |
odp_queue_t odp_queue_aggr | ( | odp_queue_t | queue, |
uint32_t | aggr_index | ||
) |
Get a queue handle of an event aggregator associated with a queue.
Returns a queue handle that can be used to refer to an event aggregator associated with this queue. Unless otherwise noted, the returned queue handle can be used in all contexts where queue handles are used. In particular, the queue handle can be used in odp_queue_enq() to enqueue events through an event aggregator to the underlying queue. Similarly, the queue handle can be given as a destination queue or a completion queues to various ODP APIs (such as packet I/O, classifier, crypto, IPsec) to have the generated events enqueued by ODP through the event aggregator. If event aggregation is not supported by a particular event source, passing an aggregator queue handle has the same effect as passing the handle of the underlying queue, i.e. aggregation does not occur.
This function does not create a new queue but merely returns a reference to an aggregator queue which has the same lifetime as the underlying queue. The underlying queue must not be destroyed as long as any of its aggregators is in use. The aggregator queue gets destroyed when the underlying queue gets destroyed. An aggregator queue handle must not be passed to odp_queue_destroy().
An aggregator queue has the same enq_mode as the underlying queue.
The returned queue handle cannot be used for dequeuing events. It must not be passed to odp_queue_deq() or similar. When an event that has passed through an aggregator is dequeued by the scheduler, the indicated source queue is the underlying queue, not the aggregator queue.
Aggregator queues do not have queue contexts. An application must not call odp_queue_context_set() or odp_queue_context().
'aggr_index' refers to the aggregator configured with the same index in odp_queue_param_t::aggr.
If 'aggr_index' is greater than odp_queue_param_t::num_aggr, ODP_QUEUE_INVALID is returned.
queue | Queue handle |
aggr_index | Index of the event aggregator |
ODP_QUEUE_INVALID | on failure |
int odp_queue_enq | ( | odp_queue_t | queue, |
odp_event_t | ev | ||
) |
Enqueue an event to a queue.
Enqueues the event into the queue. The caller loses ownership of the event on a successful call. The event is not enqueued on failure, and the caller maintains ownership of it.
When successful, this function acts as a release memory barrier between the sender (the calling thread) and the receiver of the event. The receiver sees correctly the memory stores done by the sender before it enqueued the event.
queue | Queue handle |
ev | Event handle |
0 | on success |
<0 | on failure |
int odp_queue_enq_multi | ( | odp_queue_t | queue, |
const odp_event_t | events[], | ||
int | num | ||
) |
Enqueue multiple events to a queue.
Like odp_queue_enq(), but enqueues multiple events into the queue. Events are stored into the queue in the order they are in the array. A successful call returns the actual number of events enqueued. If return value is less than 'num', the remaining events at the end of events[] are not enqueued, and the caller maintains ownership of those.
queue | Queue handle |
events | Array of event handles |
num | Number of events to enqueue |
<0 | on failure |
int odp_queue_enq_aggr | ( | odp_queue_t | queue, |
odp_event_t | ev, | ||
const odp_aggr_enq_param_t * | param | ||
) |
Enqueue an event with event aggregation hints.
Similar to odp_queue_enq() but passes an aggregation hint to the queue if the queue is an event aggregator. If the queue is not an event aggregator, works the same way as odp_queue_enq().
Queuing to an event aggregator can be done using the normal enqueueing functions if an aggregation hint is not needed.
Use odp_aggr_enq_param_init() to initialize param.
queue | Queue handle |
ev | Event handle |
param | Aggregation hint parameters |
0 | on success |
<0 | on failure |
void odp_aggr_enq_param_init | ( | odp_aggr_enq_param_t * | param | ) |
Initialize aggregator enqueue parameters to their default values.
Initialize all fields of the parameter structure to their default values
[out] | param | Aggregation hint parameters |
odp_event_t odp_queue_deq | ( | odp_queue_t | queue | ) |
Dequeue an event from a queue.
Returns the next event from head of the queue, or ODP_EVENT_INVALID when the queue is empty. Cannot be used for ODP_QUEUE_TYPE_SCHED type queues (use odp_schedule() instead).
When successful, this function acts as an acquire memory barrier between the sender and the receiver (the calling thread) of the event. The receiver sees correctly the memory stores done by the sender before it enqueued the event.
queue | Queue handle |
ODP_EVENT_INVALID | on failure, or when the queue is empty |
int odp_queue_deq_multi | ( | odp_queue_t | queue, |
odp_event_t | events[], | ||
int | num | ||
) |
Dequeue multiple events from a queue.
Like odp_queue_deq(), but dequeues multiple events from head of the queue. Cannot be used for ODP_QUEUE_TYPE_SCHED type queues (use odp_schedule_multi() instead). A successful call returns the actual number of events dequeued.
queue | Queue handle | |
[out] | events | Array of event handles for output |
num | Maximum number of events to dequeue |
<0 | on failure |
odp_queue_type_t odp_queue_type | ( | odp_queue_t | queue | ) |
odp_schedule_sync_t odp_queue_sched_type | ( | odp_queue_t | queue | ) |
Queue schedule type.
queue | Queue handle |
odp_schedule_prio_t odp_queue_sched_prio | ( | odp_queue_t | queue | ) |
Queue priority.
queue | Queue handle |
odp_schedule_group_t odp_queue_sched_group | ( | odp_queue_t | queue | ) |
Queue group.
queue | Queue handle |
uint32_t odp_queue_lock_count | ( | odp_queue_t | queue | ) |
Queue lock count.
Return number of ordered locks associated with this ordered queue. Lock count is defined in odp_schedule_param_t.
queue | Queue handle |
0 | Specified queue is not ordered or no ordered lock associated with the ordered queue. |
uint64_t odp_queue_to_u64 | ( | odp_queue_t | hdl | ) |
Get printable value for an odp_queue_t.
hdl | odp_queue_t handle to be printed |
void odp_queue_param_init | ( | odp_queue_param_t * | param | ) |
Initialize queue params.
Initialize an odp_queue_param_t to its default values for all fields. Also the schedule parameters are set to defaults, although the default queue type is ODP_QUEUE_TYPE_PLAIN.
param | Address of the odp_queue_param_t to be initialized |
int odp_queue_info | ( | odp_queue_t | queue, |
odp_queue_info_t * | info | ||
) |
Retrieve information about a queue.
Invalid queue handles or handles to free/destroyed queues leads to undefined behaviour. Not intended for fast path use.
queue | Queue handle | |
[out] | info | Queue info pointer for output |
0 | Success |
<0 | Failure. Info could not be retrieved. |
void odp_queue_print | ( | odp_queue_t | queue | ) |
Print queue info.
Print implementation defined information about the specified queue to the ODP log. The information is intended to be used for debugging.
queue | Queue handle |
void odp_queue_print_all | ( | void | ) |
Print debug info about all queues.
Print implementation defined information about all created queues to the ODP log. The information is intended to be used for debugging.