diff mbox

[API-NEXT,PATCHv2,06/11] api: queue: ordered queue additional APIs

Message ID 1440461669-18578-7-git-send-email-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer Aug. 25, 2015, 12:14 a.m. UTC
Add the following APIs for ordered queues:
odp_queue_enq_sustain()
odp_queue_enq_multi_sustain()

These are used to enqueue events without resolving order when operating
in an ordered context.

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
 include/odp/api/queue.h | 64 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
diff mbox

Patch

diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h
index ce04eb4..554d9f1 100644
--- a/include/odp/api/queue.h
+++ b/include/odp/api/queue.h
@@ -156,10 +156,38 @@  void *odp_queue_context(odp_queue_t queue);
  *
  * @retval 0 on success
  * @retval <0 on failure
+ *
+ * @note When operating in an ordered context a successful call to
+ * odp_queue_enq() resolves order. This means that further calls to ODP APIs
+ * that oeprate on ordered contexts will no longer provide ordered semantics.
  */
 int odp_queue_enq(odp_queue_t queue, odp_event_t ev);
 
 /**
+ * Queue enqueue without order resolution
+ *
+ * Enqueue the 'ev' on 'queue'. On failure the event is not consumed, the caller
+ * has to take care of it. On success, order is not resolved.
+ *
+ * @param queue   Queue handle
+ * @param ev      Event handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ *
+ * @note When operating in an ordered context this call differs from
+ * odp_queue_enq() in that it does not resolve order, meaning that the caller
+ * is still running in an ordered context. This means that the caller may
+ * continue to make calls to ODP APIs that operate on ordered contexts. A
+ * typical use for odp_queue_enq_sustain() is to insert an event into an
+ * ordered flow without resolving order. This permits, for example, an
+ * application to divide a packet into multiple segments for MTU or other
+ * purposes and have the segments preserve the relative order of the
+ * originating packet.
+ */
+int odp_queue_enq_sustain(odp_queue_t queue, odp_event_t ev);
+
+/**
  * Enqueue multiple events to a queue
  *
  * Enqueue the events from 'events[]' on 'queue'. A successful call returns the
@@ -173,10 +201,46 @@  int odp_queue_enq(odp_queue_t queue, odp_event_t ev);
  *
  * @return Number of events actually enqueued (0 ... num)
  * @retval <0 on failure
+ *
+ * @note When operating in an ordered context, all events passed to
+ * odp_queue_enq_multi() are added to the target queue as a block in context
+ * order. Upon successful enqueue, the ordered context is considered resolved,
+ * meaning that further ODP APIs that operate in an ordered context should not
+ * be made. If they are called, they will not provide ordered semantics.  For
+ * example, following this call a call to odp_schedule_release_ordered() is a
+ * no-op since the caller is no longer running in an ordered
+ * context. Similarly, a call to odp_schedule_order_lock() will do nothing,
+ * and further enqueue calls will be unordered since the caller no longer
+ * holds and ordered context.
  */
 int odp_queue_enq_multi(odp_queue_t queue, const odp_event_t events[], int num);
 
 /**
+ * Enqueue multiple events to a queue without order resolution
+ *
+ * Enqueue the events from 'events[]' on 'queue'. 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 consumed, and the caller
+ * has to take care of them.
+ *
+ * @param queue   Queue handle
+ * @param[in] events Array of event handles
+ * @param num     Number of event handles to enqueue
+ *
+ * @return Number of events actually enqueued (0 ... num)
+ * @retval <0 on failure
+ *
+ * @note When operating in an ordered context, all events passed to
+ * odp_queue_enq_multi_sustain() are added to the target queue as a block in
+ * context order. Upon successful enqueue, the ordered context is not
+ * resolved, meaning that further ODP API calls that operate in an ordered
+ * context may be made and these will continue to be part of the current
+ * ordered context.
+ */
+int odp_queue_enq_multi_sustain(odp_queue_t queue,
+				const odp_event_t events[], int num);
+
+/**
  * Queue dequeue
  *
  * Dequeues next event from head of the queue. Cannot be used for