@@ -174,6 +174,42 @@ void odp_schedule_release_atomic(void);
int odp_schedule_release_ordered(odp_event_t ev);
/**
+ * Ordered event lock
+ *
+ * While odp_schedule_order_sync() permits code to be serialized once per
+ * event, odp_schedule_order_lock() provides 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
+ *
+ * Releases 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
@@ -189,6 +225,11 @@ int odp_schedule_release_ordered(odp_event_t ev);
*
* @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 +377,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);
-
-/**
* @}
*/
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- include/odp/api/schedule.h | 78 ++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 37 deletions(-)