diff mbox series

[API-NEXT,v2,1/3] api: queue: non-blocking level parameter

Message ID 1512039613-7090-2-git-send-email-odpbot@yandex.ru
State New
Headers show
Series [API-NEXT,v2,1/3] api: queue: non-blocking level parameter | expand

Commit Message

Github ODP bot Nov. 30, 2017, 11 a.m. UTC
From: Petri Savolainen <petri.savolainen@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.savolainen@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: 4cb02e1caccb9179575e95448fd46979e17d0905
 ** Merge commit sha: 2fb581ec76ff776f788da097894cb3f6b63ae23d
 **/
 include/odp/api/spec/queue.h | 63 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
diff mbox series

Patch

diff --git a/include/odp/api/spec/queue.h b/include/odp/api/spec/queue.h
index 73598be06..8069cf08d 100644
--- a/include/odp/api/spec/queue.h
+++ b/include/odp/api/spec/queue.h
@@ -96,6 +96,54 @@  typedef enum odp_queue_op_mode_t {
 
 } odp_queue_op_mode_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_nonblocking_t {
+	/** Blocking implementation. A suspeding thread may block all other
+	 *  threads, i.e. no block freedom guarantees. This is the lowest level.
+	 */
+	ODP_BLOCKING = 0,
+
+	/** Non-blocking and lock-free implementation. Other threads can make
+	 *  progress while a thread is suspended. Starvation freedom is not
+	 *  guaranteed.
+	 */
+	ODP_NONBLOCKING_LF,
+
+	/** Non-blocking and wait-free implementation. Other threads can make
+	 *  progress while a thread is suspended. Starvation freedom is
+	 *  guaranteed.
+	 */
+	ODP_NONBLOCKING_WF
+
+} odp_nonblocking_t;
+
 /**
  * Queue capabilities
  */
@@ -125,6 +173,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_nonblocking_t nonblocking;
+
 	} plain;
 
 	/** Scheduled queue capabilities */
@@ -138,6 +190,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_nonblocking_t nonblocking;
+
 	} sched;
 
 } odp_queue_capability_t;
@@ -178,6 +234,13 @@  typedef struct odp_queue_param_t {
 	  * ODP_QUEUE_TYPE_SCHED. */
 	odp_schedule_param_t sched;
 
+	/** Non-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_nonblocking_t nonblocking;
+
 	/** Queue context pointer
 	  *
 	  * User defined context pointer associated with the queue. The same