From: Petri Savolainen <petri.savolai...@linaro.org> Add queue parameter and capability to indicate queue operation blocking level. This guarantee of non-blocking is important for real-time applications. HW based implementations may be always non-blocking. Where as, SW based implementation need to trade-off between block freedom and performance.
Signed-off-by: Petri Savolainen <petri.savolai...@linaro.org> --- /** Email created from pull request 302 (psavol:next-lockfree-queue) ** https://github.com/Linaro/odp/pull/302 ** Patch: https://github.com/Linaro/odp/pull/302.patch ** Base sha: d4b364849c4abb4c71e0c5260e1a793ebb8dc97d ** Merge commit sha: fc00736d09bd0388db2bde3a9177edfd995eec67 **/ include/odp/api/spec/queue.h | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/include/odp/api/spec/queue.h b/include/odp/api/spec/queue.h index 73598be06..7f2d7cb2e 100644 --- a/include/odp/api/spec/queue.h +++ b/include/odp/api/spec/queue.h @@ -96,6 +96,32 @@ typedef enum odp_queue_op_mode_t { } odp_queue_op_mode_t; +/** + * Blocking level + * + * Blocking level tells how operations behave when one of the threads using + * the same resource suspends. A blocking implementation may block other threads + * using the same resource for the entire time that one of the threads remain + * suspended. On the contrary, a lock-free implementation allows other threads + * to make progress while a thread is suspended. Blocking levels are listed from + * the weakest to the strongest guarantee of block freedom. + * + * Performance of non-blocking operations may be lower than blocking ones, but + * can be used safely e.g. between threads of real-time and non real-time parts + * of an application. + */ +typedef enum odp_blocking_level_t { + /** Operations may block. Other threads may be blocked while a thread + * is suspended. This is the lowest blocking level (no block freedom + * guarantees). */ + ODP_BLOCKING = 0, + + /** Lock-free operation. Other threads can make progress while a thread + * is suspended. */ + ODP_LOCKFREE + +} odp_blocking_level_t; + /** * Queue capabilities */ @@ -125,6 +151,10 @@ typedef struct odp_queue_capability_t { * store all available events. */ uint32_t max_size; + /** The strongest guarantee of block freedom that is supported + * for plain queues. */ + odp_blocking_level_t blocking_level; + } plain; /** Scheduled queue capabilities */ @@ -138,6 +168,10 @@ typedef struct odp_queue_capability_t { * store all available events. */ uint32_t max_size; + /** The strongest guarantee of block freedom that is supported + * for scheduled queues. */ + odp_blocking_level_t blocking_level; + } sched; } odp_queue_capability_t; @@ -178,6 +212,13 @@ typedef struct odp_queue_param_t { * ODP_QUEUE_TYPE_SCHED. */ odp_schedule_param_t sched; + /** Blocking level + * + * Queue implementation must guarantee at least this level of block + * freedom for queue enqueue and dequeue/schedule operations. + * The default value is ODP_BLOCKING. */ + odp_blocking_level_t blocking_level; + /** Queue context pointer * * User defined context pointer associated with the queue. The same