| Message ID | 1424272768-15154-1-git-send-email-petri.savolainen@linaro.org |
|---|---|
| State | Accepted |
| Commit | d4c1162270858fc7b9c0dd836d3176525430f9f0 |
| Headers | show |
On 18 February 2015 at 16:19, Petri Savolainen <petri.savolainen@linaro.org> wrote: > Improved documentation and definition of atomic and ordered > queue synchronisation. > > Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org> Wording only: Reviewed-by: Ola Liljedahl <ola.liljedahl@linaro.org> > > --- > This is the ordered queue definition (in patch format) promised > in the call yesterday. > --- > include/odp/api/queue.h | 25 +++++++++++++++++++++++-- > include/odp/api/schedule.h | 15 ++++++++++++--- > 2 files changed, 35 insertions(+), 5 deletions(-) > > diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h > index 9519edf..6a8b15f 100644 > --- a/include/odp/api/queue.h > +++ b/include/odp/api/queue.h > @@ -104,16 +104,37 @@ extern "C" { > /** > * @def ODP_SCHED_SYNC_NONE > * Queue not synchronised > + * > + * The scheduler does not provide event synchronisation or ordering, only load > + * balancing. Events can be scheduled freely to multiple threads for concurrent > + * processing. > */ > > /** > * @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. 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 synchronisation for those two. > + * > + * 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. > */ > > /** > * @def ODP_SCHED_SYNC_ORDERED > - * Ordered queue > + * Ordered queue synchronisation > + * > + * 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 > + * when dequeued from a destination queue. The destination queue can have any > + * queue type and synchronisation method. > */ > > /** > diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h > index 5c08357..3bf0578 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 pre-scheduled 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). > + * (pre-scheduled) 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 events from the same queue to some other 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 > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
Merged! Maxim. On 02/18/2015 06:31 PM, Ola Liljedahl wrote: > On 18 February 2015 at 16:19, Petri Savolainen > <petri.savolainen@linaro.org> wrote: >> Improved documentation and definition of atomic and ordered >> queue synchronisation. >> >> Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org> > Wording only: > Reviewed-by: Ola Liljedahl <ola.liljedahl@linaro.org> > >> --- >> This is the ordered queue definition (in patch format) promised >> in the call yesterday. >> --- >> include/odp/api/queue.h | 25 +++++++++++++++++++++++-- >> include/odp/api/schedule.h | 15 ++++++++++++--- >> 2 files changed, 35 insertions(+), 5 deletions(-) >> >> diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h >> index 9519edf..6a8b15f 100644 >> --- a/include/odp/api/queue.h >> +++ b/include/odp/api/queue.h >> @@ -104,16 +104,37 @@ extern "C" { >> /** >> * @def ODP_SCHED_SYNC_NONE >> * Queue not synchronised >> + * >> + * The scheduler does not provide event synchronisation or ordering, only load >> + * balancing. Events can be scheduled freely to multiple threads for concurrent >> + * processing. >> */ >> >> /** >> * @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. 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 synchronisation for those two. >> + * >> + * 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. >> */ >> >> /** >> * @def ODP_SCHED_SYNC_ORDERED >> - * Ordered queue >> + * Ordered queue synchronisation >> + * >> + * 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 >> + * when dequeued from a destination queue. The destination queue can have any >> + * queue type and synchronisation method. >> */ >> >> /** >> diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h >> index 5c08357..3bf0578 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 pre-scheduled 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). >> + * (pre-scheduled) 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 events from the same queue to some other 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 >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h index 9519edf..6a8b15f 100644 --- a/include/odp/api/queue.h +++ b/include/odp/api/queue.h @@ -104,16 +104,37 @@ extern "C" { /** * @def ODP_SCHED_SYNC_NONE * Queue not synchronised + * + * The scheduler does not provide event synchronisation or ordering, only load + * balancing. Events can be scheduled freely to multiple threads for concurrent + * processing. */ /** * @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. 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 synchronisation for those two. + * + * 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. */ /** * @def ODP_SCHED_SYNC_ORDERED - * Ordered queue + * Ordered queue synchronisation + * + * 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 + * when dequeued from a destination queue. The destination queue can have any + * queue type and synchronisation method. */ /** diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h index 5c08357..3bf0578 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 pre-scheduled 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). + * (pre-scheduled) 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 events from the same queue to some other 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);
Improved documentation and definition of atomic and ordered queue synchronisation. Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org> --- This is the ordered queue definition (in patch format) promised in the call yesterday. --- include/odp/api/queue.h | 25 +++++++++++++++++++++++-- include/odp/api/schedule.h | 15 ++++++++++++--- 2 files changed, 35 insertions(+), 5 deletions(-)