diff mbox

[API-NEXT,PATCHv14,02/13] api: queue: document ordered chain enq support

Message ID 1439139273-22438-3-git-send-email-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer Aug. 9, 2015, 4:54 p.m. UTC
Expand documentation of odp_queue_enq_multi() to describe support for
ordered chains.

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

Patch

diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h
index ce04eb4..5a6dbc0 100644
--- a/include/odp/api/queue.h
+++ b/include/odp/api/queue.h
@@ -173,6 +173,29 @@  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 odp_queue_enq_multi() serves two purposes. First, it allows
+ * multiple events to be enqueued via a single call. In addition, it
+ * permits multiple events to partitipate in ordering. When an event
+ * originating from an ordered queue is followed by one or more events
+ * that did not originate from an ordered queue, then these subsequent
+ * events are "chained" to the ordered event such that they participate
+ * in its ordering. This provides a convenient means for an application
+ * to split a packet into multiple packets and have them retain the
+ * relative order of the original packet.
+ *
+ * @note If multiple events originating from ordered queues are passed
+ * to odp_queue_enq_multi() then they (and their associated chains, if
+ * any) are handled independently. To see this, consider the following
+ * array of events: uo1, uo2, o1, uo3, uo4, o2, o3, uo5.  When this
+ * array is passed to odp_queue_enq_multi() then unordered events uo1 and
+ * uo2 will be added to queue, then ordered event o1 and the chained
+ * events uo3, and uo4, will be added, then ordered event o2, then ordered
+ * event o3 and the chained event uo5 will be added. In all cases,
+ * unordered events that are chained to ordered events inherit the relative
+ * order of their ordered lead event.  Note also that there is no
+ * requirement that the ordered events passed to this routine all originate
+ * from the same ordered queue sine each is treated independently.
  */
 int odp_queue_enq_multi(odp_queue_t queue, const odp_event_t events[], int num);