Clarified that a thread holds synchronization context between
schedule calls. Next schedule call implicitly release the context.
Clafified atomic and ordered context definitions.
Signed-off-by: Petri Savolainen <petri.savolai...@nokia.com>
---
include/odp/api/schedule.h | 18 ++++++++++++++----
include/odp/api/schedule_types.h | 35 +++++++++++++++++++++++++----------
2 files changed, 39 insertions(+), 14 deletions(-)
diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h
index c772754..ca4bc28 100644
--- a/include/odp/api/schedule.h
+++ b/include/odp/api/schedule.h
@@ -65,6 +65,12 @@ uint64_t odp_schedule_wait_time(uint64_t ns);
* for an event according to the wait parameter setting. Returns
* ODP_EVENT_INVALID if reaches end of the wait period.
*
+ * When returns an event, the thread holds the queue synchronization context
+ * (atomic or ordered) until the next odp_schedule() or odp_schedule_multi()
+ * call. The next call implicitly releases the current context and potentially
+ * returns with a new context. User can allow early context release (e.g. see
+ * odp_schedule_release_atomic()) for performance optimization.
+ *
* @param from Output parameter for the source queue (where the event was
* dequeued from). Ignored if NULL.
* @param wait Minimum time to wait for an event. Waits infinitely, if set
to
@@ -74,6 +80,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns);
*
* @return Next highest priority event
* @retval ODP_EVENT_INVALID on timeout and no events available
+ *
+ * @see odp_schedule_multi(), odp_schedule_release_atomic()
*/
odp_event_t odp_schedule(odp_queue_t *from, uint64_t wait);
@@ -120,10 +128,12 @@ void odp_schedule_resume(void);
/**
* Release the current atomic context
*
- * This call is valid only for source queues with atomic synchronisation. It
- * hints the scheduler that the user has completed processing of the critical
- * section (which depends on the atomic synchronisation). The scheduler is now
- * allowed to schedule events from the same queue to some other thread.
+ * This call is valid only for source queues with atomic synchronization. It
+ * hints the scheduler that the user has completed critical section processing
+ * in the current atomic context. The scheduler is now allowed to schedule
+ * events from the same queue to another thread. However, the context may be
+ * still held until the next odp_schedule() or odp_schedule_multi() call - this
+ * call allows but does not force the scheduler to release the context early.
*
* Early atomic context release may increase parallelism and thus system
* performance, but user needs to design carefully the split into critical vs.
diff --git a/include/odp/api/schedule_types.h b/include/odp/api/schedule_types.h
index 724b36c..8d2a8ad 100644
--- a/include/odp/api/schedule_types.h
+++ b/include/odp/api/schedule_types.h
@@ -68,13 +68,14 @@ extern "C" {
*
* Events from an atomic queue can be scheduled only to a single thread at a
* time. The thread is guaranteed to have exclusive (atomic) access to the
- * associated queue context and event ordering is maintained. This enables the
- * user to avoid SW synchronization for those two.
+ * associated queue context, which enables the user to avoid SW
synchronization.
+ * Atomic queue also helps to maintain event ordering since only one thread at
+ * a time is able to process events from a queue.
*
- * The atomic queue is dedicated to the thread until it requests another event
- * from the scheduler (which implicitly releases the queue) or calls
- * odp_schedule_release_atomic(), which allows the scheduler to release the
- * queue immediately.
+ * The atomic queue synchronization context is dedicated to the thread until it
+ * requests another event from the scheduler, which implicitly releases the
+ * context. User may allow the scheduler to release the context earlier than
+ * that by calling odp_schedule_release_atomic().
*/
/**
@@ -82,11 +83,25 @@ extern "C" {
* Ordered queue synchronization
*
* Events from an ordered queue can be scheduled to multiple threads for
- * concurrent processing. The source queue (dequeue) ordering is maintained
when
- * events are enqueued to their destination queue(s) before another schedule
- * call. Events from the same (source) queue appear in their original order
+ * concurrent processing but still maintain the original event order. This
+ * enables the user to achieve high single flow throughput by avoiding
+ * SW syncronization for ordering between threads.
+ *
+ * The source queue (dequeue) ordering is maintained when
+ * events are enqueued to their destination queue(s) within the same ordered
+ * queue synchronization context. A thread holds the context until it
+ * requests another event from the scheduler, which implicitly releases the
+ * context. User may allow the scheduler to release the context earlier than
+ * that by calling odp_schedule_release_ordered().
+ *
+ * Events from the same (source) queue appear in their original order
* when dequeued from a destination queue. The destination queue can have any
- * queue type and synchronization method.
+ * queue type and synchronization method. Event ordering is based on the
+ * received event(s), but also other (newly allocated or stored) events are
+ * ordered when enqueued within the same ordered context. Events not enqueued
+ * (e.g. freed or stored) within the context are considered missing from
+ * reordering and are skipped at this time (but can be ordered again within
+ * another context).
*/
/**
--
2.4.5
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp
