Signed-off-by: Ola Liljedahl <[email protected]>
---
(This code contribution is provided under the terms of agreement LES-LTM-21309)
Update and unify doxygen comments and function parameter names.
.../linux-generic/include/api/odp_ticketlock.h | 45 ++++++++++++----------
1 file changed, 25 insertions(+), 20 deletions(-)
diff --git a/platform/linux-generic/include/api/odp_ticketlock.h
b/platform/linux-generic/include/api/odp_ticketlock.h
index 619816e..93a66b7 100644
--- a/platform/linux-generic/include/api/odp_ticketlock.h
+++ b/platform/linux-generic/include/api/odp_ticketlock.h
@@ -23,11 +23,16 @@ extern "C" {
#include <odp_atomic.h>
/** @addtogroup odp_synchronizers
+ * Operations on ticket locks.
+ * Acquiring a ticket lock happens in two phases. First the threads takes a
+ * ticket. Second it waits (spins) until it is its turn.
+ * Ticket locks are believed to be more fair than spin locks.
+ * Ticket locks shall not be used in the presence of preemption.
* @{
*/
/**
- * ODP ticketlock
+ * ODP ticket lock
*/
typedef struct odp_ticketlock_t {
odp_atomic_u32_t next_ticket; /**< @private Next ticket */
@@ -36,47 +41,47 @@ typedef struct odp_ticketlock_t {
/**
- * Init ticketlock
+ * Initialize ticket lock.
*
- * @param ticketlock Ticketlock
+ * @param tklock Pointer to a ticket lock
*/
-void odp_ticketlock_init(odp_ticketlock_t *ticketlock);
+void odp_ticketlock_init(odp_ticketlock_t *tklock);
/**
- * Lock ticketlock
+ * Acquire ticket lock.
*
- * @param ticketlock Ticketlock
+ * @param tklock Pointer to a ticket lock
*/
-void odp_ticketlock_lock(odp_ticketlock_t *ticketlock);
-
+void odp_ticketlock_lock(odp_ticketlock_t *tklock);
/**
- * Try to lock ticketlock
+ * Try to acquire ticket lock.
*
- * @param ticketlock Ticketlock
+ * @param tklock Pointer to a ticket lock
*
- * @return 1 if the lock was taken, otherwise 0.
+ * @retval 1 lock acquired
+ * @retval 0 lock not acquired
*/
-int odp_ticketlock_trylock(odp_ticketlock_t *ticketlock);
-
+int odp_ticketlock_trylock(odp_ticketlock_t *tklock);
/**
- * Unlock ticketlock
+ * Release ticket lock.
*
- * @param ticketlock Ticketlock
+ * @param tklock Pointer to a ticket lock
*/
-void odp_ticketlock_unlock(odp_ticketlock_t *ticketlock);
+void odp_ticketlock_unlock(odp_ticketlock_t *tklock);
/**
- * Test if ticketlock is locked
+ * Check if ticket lock is locked.
*
- * @param ticketlock Ticketlock
+ * @param tklock Pointer to a ticket lock
*
- * @return 1 if the lock is locked, otherwise 0.
+ * @retval 1 the lock is busy (locked)
+ * @retval 0 the lock is available (unlocked)
*/
-int odp_ticketlock_is_locked(odp_ticketlock_t *ticketlock);
+int odp_ticketlock_is_locked(odp_ticketlock_t *tklock);
/**
* @}
--
1.9.1
_______________________________________________
lng-odp mailing list
[email protected]
http://lists.linaro.org/mailman/listinfo/lng-odp
