diff mbox

[API-NEXT,PATCHv12,05/13] api: schedule: add odp_schedule_order_lock/unlock

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

Commit Message

Bill Fischofer Aug. 9, 2015, 1:13 p.m. UTC
Additional scheduler APIs:
odp_schedule_order_lock()
odp_schedule_order_unlock()

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
 include/odp/api/schedule.h                         | 81 +++++++++++-----------
 .../include/odp/plat/schedule_types.h              |  2 -
 2 files changed, 42 insertions(+), 41 deletions(-)
diff mbox

Patch

diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h
index 61d3b16..f715144 100644
--- a/include/odp/api/schedule.h
+++ b/include/odp/api/schedule.h
@@ -174,6 +174,41 @@  void odp_schedule_release_atomic(void);
 int odp_schedule_release_ordered(odp_event_t ev);
 
 /**
+ * Ordered event lock
+ *
+ * Provide reusable in-order serialization for scheduled ordered events. Upon
+ * return the caller is in order with respect to other events originating from
+ * the current ordered context and will retain order until a subsequent
+ * odp_schedule_order_unlock() call is made, or until order is resolved for
+ * the event via a call to odp_queue_enq() or odp_schedule_release_ordered().
+ * If the caller holds multiple events, e.g., as received from
+ * odp_schedule_multi(), then the list of events may only be locked in their
+ * received order to avoid deadlock.  That is, if the caller received events
+ * 1, 2, and 3 from odp_schedule_multi(), it is an error to attempt to lock
+ * event 2 before locking and unlocking event 1 or otherwise resolving event
+ * 1's order.
+ *
+ * @param ev   The event whose order is to be locked. This event MUST have
+ *             originated from an ordered queue.
+ */
+void odp_schedule_order_lock(odp_event_t ev);
+
+/**
+ * Ordered event unlock
+ *
+ * Release an ordered lock previously acquired by odp_schedule_order_lock().
+ * It is an error to attempt to release a lock that had not been previously
+ * acquired for the specified event.  Following this call, the thread will
+ * exit the critical section protected by the ordered lock and will resume
+ * parallel execution until the next call to odp_schedule_order_lock() for
+ * that event, or until the event's order is resolved by a call to
+ * odp_queue_enq() or odp_schedule_release_ordered().
+ *
+ * @param ev    The event whose order is to be unlocked.
+ */
+void odp_schedule_order_unlock(odp_event_t ev);
+
+/**
  * Copy order from one event to another
  *
  * This call copies the order associated with an event originating from an
@@ -181,14 +216,19 @@  int odp_schedule_release_ordered(odp_event_t ev);
  * associated ordering at input to the call. If the target is ordered, the
  * prior ordering must first be released by an odp_schedule_release_ordered()
  * call. Successfuly copying an order implicitly sets the order sustain
- * attribute for the src_event as if odp_schedule_order_sustain() were called
- * for it.
+ * attribute for the src_event as if odp_schedule_order_sustain_set() were
+ * called for it.
  *
  * @param src_event Event whose ordering is to be copied
  * @param dst_event Event to receive the same ordering as src_event.
  *
  * @retval 0  Success
  * @retval <0 Failure.  Order not copied.
+ *
+ * @note If multiple events share the same order as a result of
+ * odp_schedule_order_copy(), only one of them should attempt to lock the
+ * order via calls to odp_schedule_order_lock(). Results are undefined if this
+ * restriction is not observed.
  */
 int odp_schedule_order_copy(odp_event_t src_event, odp_event_t dst_event);
 
@@ -336,43 +376,6 @@  int odp_schedule_group_leave(odp_schedule_group_t group,
 int odp_schedule_group_count(odp_schedule_group_t group);
 
 /**
- * Initialize ordered context lock
- *
- * Initialize an ordered queue context lock. The lock can be associated only
- * with ordered queues and used only within an ordered synchronization context.
- *
- * @param queue   Ordered queue
- * @param lock    Ordered context lock
- *
- * @retval 0 on success
- * @retval <0 on failure
- */
-int odp_schedule_olock_init(odp_queue_t queue, odp_schedule_olock_t *lock);
-
-/**
- * Acquire ordered context lock
- *
- * This call is valid only when holding an ordered synchronization context. The
- * lock is used to protect a critical section that is executed within an
- * ordered context. Threads enter the critical section in the order determined
- * by the context (source queue). Lock ordering is automatically skipped for
- * threads that release the context instead of calling the lock.
- *
- * @param lock    Ordered context lock
- */
-void odp_schedule_olock_lock(odp_schedule_olock_t *lock);
-
-/**
- * Release ordered context lock
- *
- * This call is valid only when holding an ordered synchronization context.
- * Release a previously locked ordered context lock.
- *
- * @param lock    Ordered context lock
- */
-void odp_schedule_olock_unlock(odp_schedule_olock_t *lock);
-
-/**
  * @}
  */
 
diff --git a/platform/linux-generic/include/odp/plat/schedule_types.h b/platform/linux-generic/include/odp/plat/schedule_types.h
index 91e62e7..bc25c8c 100644
--- a/platform/linux-generic/include/odp/plat/schedule_types.h
+++ b/platform/linux-generic/include/odp/plat/schedule_types.h
@@ -48,8 +48,6 @@  typedef int odp_schedule_group_t;
 
 #define ODP_SCHED_GROUP_NAME_LEN 32
 
-typedef int odp_schedule_olock_t;
-
 /**
  * @}
  */