Merged!
Maxim.
On 02/18/2015 06:31 PM, Ola Liljedahl wrote:
On 18 February 2015 at 16:19, Petri Savolainen
<petri.savolai...@linaro.org> wrote:
Improved documentation and definition of atomic and ordered
queue synchronisation.
Signed-off-by: Petri Savolainen <petri.savolai...@linaro.org>
Wording only:
Reviewed-by: Ola Liljedahl <ola.liljed...@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
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
http://lists.linaro.org/mailman/listinfo/lng-odp
