diff mbox

[API-NEXT,PATCHv8,05/13] api: schedule: revised definition of odp_schedule_release_ordered

Message ID 1438815321-12344-6-git-send-email-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer Aug. 5, 2015, 10:55 p.m. UTC
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
 include/odp/api/schedule.h | 38 ++++++++++++++++++++++++--------------
 1 file changed, 24 insertions(+), 14 deletions(-)
diff mbox

Patch

diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h
index bd858b3..f27bf78 100644
--- a/include/odp/api/schedule.h
+++ b/include/odp/api/schedule.h
@@ -147,21 +147,31 @@  void odp_schedule_resume(void);
 void odp_schedule_release_atomic(void);
 
 /**
- * Release the current ordered context
- *
- * This call is valid only for source queues with ordered synchronization. It
- * hints the scheduler that the user has done all enqueues that need to maintain
- * event order in the current ordered context. The scheduler is allowed to
- * release the ordered context of this thread and avoid reordering any following
- * enqueues. 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 ordered context release may increase parallelism and thus system
- * performance, since scheduler may start reordering events sooner than the next
- * schedule call.
+ * Release a specified event in the current ordered context.
+ *
+ * This call tells the scheduler that the current ordered context no longer
+ * needs to be maintained for the specified event. This call is needed if, for
+ * example, the caller will free or otherwise dispose of an event that came
+ * from an ordered queue without enqueuing it to another queue. This call does
+ * not effect the ordering associated with any other event held by the caller.
+ *
+ * Releasing order may increase parallelism and thus system performance, since
+ * the scheduler may start resolving reordered events sooner than the next
+ * odp_queue_enq() call.
+ *
+ * @param ev      The event to be released from the current ordered context.
+ *
+ * @retval 0      Success. Upon return ev behaves as if it originated
+ *                from a parallel rather than an ordered queue.
+ *
+ * @retval <0     Failure. This can occur if the event did not originate
+ *                from an ordered queue (caller error) or the implementation
+ *                is unable to release order at this time. In this case,
+ *                the caller must not dispose of ev without enqueing it
+ *                first to avoid deadlocking other events originating from
+ *                ev's ordered queue.
  */
-void odp_schedule_release_ordered(void);
+int odp_schedule_release_ordered(odp_event_t ev);
 
 /**
  * Prefetch events for next schedule call