| Message ID | 1417707535-7632-6-git-send-email-ola.liljedahl@linaro.org |
|---|---|
| State | Accepted |
| Commit | a7f3e4e686af3da6e48287b32121306d4da06d59 |
| Headers | show |
On Thu, Dec 4, 2014 at 9:38 AM, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > (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 > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
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); /** * @}
Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> --- (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(-)