Improved documentation and definition of atomic and ordered queue synchronisation.
Signed-off-by: Petri Savolainen <[email protected]> --- This is the ordered queue definition (in patch format) promised in the call yesterday. --- include/odp/api/queue.h | 21 +++++++++++++++++++-- include/odp/api/schedule.h | 15 ++++++++++++--- 2 files changed, 31 insertions(+), 5 deletions(-) diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h index 9519edf..1d67a3c 100644 --- a/include/odp/api/queue.h +++ b/include/odp/api/queue.h @@ -108,12 +108,29 @@ extern "C" { /** * @def ODP_SCHED_SYNC_ATOMIC - * Atomic queue + * Atomic queue synchronisation + * + * Events from an atomic queue can be scheduled only to a single thread at a + * time. This quarantees atomic access to the queue context and maintains event + * ordering, which helps the user to avoid SW locking. + * + * The atomic queue is dedicated to the thread until it requests another event + * from the scheduler (implicitly requests to release the current queue) or + * calls odp_schedule_release_atomic(), which hints the scheduler to release the + * queue early. */ /** * @def ODP_SCHED_SYNC_ORDERED - * Ordered queue + * Ordered queue synchronisation + * + * Events from an ordered queue can be scheduled to multiple threads for + * parallel processing. The original enqueue order of the source queue 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 when dequeued from a destination queue. The destination + * queue type (POLL/SCHED) or synchronisation (NONE/ATOMIC/ORDERED) is not + * limited. */ /** diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h index 5c08357..378ca19 100644 --- a/include/odp/api/schedule.h +++ b/include/odp/api/schedule.h @@ -93,9 +93,9 @@ int odp_schedule_multi(odp_queue_t *from, uint64_t wait, odp_event_t events[], * Pause scheduling * * Pause global scheduling for this thread. After this call, all schedule calls - * will return only locally reserved buffers (if any). User can exit the + * will return only locally reserved events (if any). User can exit the * schedule loop only after the schedule function indicates that there's no more - * buffers (no more locally reserved buffers). + * events (no more locally reserved events). * * Must be used with odp_schedule() and odp_schedule_multi() before exiting (or * stalling) the schedule loop. @@ -111,7 +111,16 @@ void odp_schedule_pause(void); void odp_schedule_resume(void); /** - * Release currently hold atomic context + * 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 another event(s) from the same queue to another thread. + * + * Early atomic context release may increase parallelism and thus system + * performance, but user needs to design carefully the split into critical vs. + * non-critical sections. */ void odp_schedule_release_atomic(void); -- 2.3.0 _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
