diff mbox

[PATCHv2,3/6] api:odp_rwlock.h: Update doxygen comments, renaming of function params

Message ID 1417707535-7632-4-git-send-email-ola.liljedahl@linaro.org
State Accepted
Commit 8cb7ea111d1c6a47200b7780d651868bd927e197
Headers show

Commit Message

Ola Liljedahl Dec. 4, 2014, 3:38 p.m. UTC 
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.

 platform/linux-generic/include/api/odp_rwlock.h | 36 ++++++++++++++-----------
 1 file changed, 20 insertions(+), 16 deletions(-)

Comments

Bill Fischofer Dec. 4, 2014, 4:28 p.m. UTC | #1 
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.
>
>  platform/linux-generic/include/api/odp_rwlock.h | 36
> ++++++++++++++-----------
>  1 file changed, 20 insertions(+), 16 deletions(-)
>
> diff --git a/platform/linux-generic/include/api/odp_rwlock.h
> b/platform/linux-generic/include/api/odp_rwlock.h
> index 59cf9cc..1295e31 100644
> --- a/platform/linux-generic/include/api/odp_rwlock.h
> +++ b/platform/linux-generic/include/api/odp_rwlock.h
> @@ -19,54 +19,58 @@
>  extern "C" {
>  #endif
>
> -/** @defgroup odp_synchronizers ODP SYNCROIZERS
> - *  Operations to a read/write lock.
> +/** @defgroup odp_synchronizers ODP SYNCRONIZERS
> + *  Operations on reader/writer locks.
> + *  A reader/writer lock allows multiple simultaneous readers but only one
> + *  writer at a time.
> + *  A thread that wants write access will have to wait until there are no
> + *  threads that want read access. This casues a risk for starvation.
>   *  @{
>   */
>
>  /**
>   * The odp_rwlock_t type.
> - * write lock count is -1,
> - * read lock count > 0
>   */
>  typedef struct {
> -       odp_atomic_u32_t cnt; /**< -1 Write lock,
> -                               > 0 for Read lock. */
> +       odp_atomic_u32_t cnt; /**< @private lock count
> +                               0 lock not taken
> +                               -1 write lock taken
> +                               >0 read lock(s) taken */
>  } odp_rwlock_t;
>
>
>  /**
> - * Initialize the rwlock to an unlocked state.
> + * Initialize a reader/writer lock.
>   *
> - * @param rwlock pointer to the RW Lock.
> + * @param rwlock Pointer to a reader/writer lock
>   */
>  void odp_rwlock_init(odp_rwlock_t *rwlock);
>
>  /**
> - * Aquire a read lock.
> + * Acquire read permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to a RW Lock.
> + * @param rwlock Pointer to a reader/writer lock
>   */
>  void odp_rwlock_read_lock(odp_rwlock_t *rwlock);
>
>  /**
> - * Release a read lock.
> + * Release read permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to the RW Lock.
> + * @param rwlock Pointer to a reader/writer lock
>   */
>  void odp_rwlock_read_unlock(odp_rwlock_t *rwlock);
>
>  /**
> - * Aquire a write lock.
> + * Acquire write permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to a RW Lock.
> + * @param rwlock Pointer to a reader/writer lock
>   */
>  void odp_rwlock_write_lock(odp_rwlock_t *rwlock);
>
>  /**
> - * Release a write lock.
> + * Release write permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to a RW Lock.
> + * @param rwlock Pointer to a reader/writer lock
>   */
>  void odp_rwlock_write_unlock(odp_rwlock_t *rwlock);
>
> --
> 1.9.1
>
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp
>
diff mbox

Patch

diff --git a/platform/linux-generic/include/api/odp_rwlock.h b/platform/linux-generic/include/api/odp_rwlock.h
index 59cf9cc..1295e31 100644
--- a/platform/linux-generic/include/api/odp_rwlock.h
+++ b/platform/linux-generic/include/api/odp_rwlock.h
@@ -19,54 +19,58 @@ 
 extern "C" {
 #endif
 
-/** @defgroup odp_synchronizers ODP SYNCROIZERS
- *  Operations to a read/write lock.
+/** @defgroup odp_synchronizers ODP SYNCRONIZERS
+ *  Operations on reader/writer locks.
+ *  A reader/writer lock allows multiple simultaneous readers but only one
+ *  writer at a time.
+ *  A thread that wants write access will have to wait until there are no
+ *  threads that want read access. This casues a risk for starvation.
  *  @{
  */
 
 /**
  * The odp_rwlock_t type.
- * write lock count is -1,
- * read lock count > 0
  */
 typedef struct {
-	odp_atomic_u32_t cnt; /**< -1 Write lock,
-				> 0 for Read lock. */
+	odp_atomic_u32_t cnt; /**< @private lock count
+				0 lock not taken
+				-1 write lock taken
+				>0 read lock(s) taken */
 } odp_rwlock_t;
 
 
 /**
- * Initialize the rwlock to an unlocked state.
+ * Initialize a reader/writer lock.
  *
- * @param rwlock pointer to the RW Lock.
+ * @param rwlock Pointer to a reader/writer lock
  */
 void odp_rwlock_init(odp_rwlock_t *rwlock);
 
 /**
- * Aquire a read lock.
+ * Acquire read permission on a reader/writer lock.
  *
- * @param rwlock pointer to a RW Lock.
+ * @param rwlock Pointer to a reader/writer lock
  */
 void odp_rwlock_read_lock(odp_rwlock_t *rwlock);
 
 /**
- * Release a read lock.
+ * Release read permission on a reader/writer lock.
  *
- * @param rwlock pointer to the RW Lock.
+ * @param rwlock Pointer to a reader/writer lock
  */
 void odp_rwlock_read_unlock(odp_rwlock_t *rwlock);
 
 /**
- * Aquire a write lock.
+ * Acquire write permission on a reader/writer lock.
  *
- * @param rwlock pointer to a RW Lock.
+ * @param rwlock Pointer to a reader/writer lock
  */
 void odp_rwlock_write_lock(odp_rwlock_t *rwlock);
 
 /**
- * Release a write lock.
+ * Release write permission on a reader/writer lock.
  *
- * @param rwlock pointer to a RW Lock.
+ * @param rwlock Pointer to a reader/writer lock
  */
 void odp_rwlock_write_unlock(odp_rwlock_t *rwlock);