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

Message ID 1417616254-31760-4-git-send-email-ola.liljedahl@linaro.org
State New
Headers show

Commit Message

Ola Liljedahl Dec. 3, 2014, 2:17 p.m.
Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
---
Update doxygen comments, renaming of function params.

 platform/linux-generic/include/api/odp_rwlock.h | 46 ++++++++++++++-----------
 1 file changed, 25 insertions(+), 21 deletions(-)

Comments

Mike Holmes Dec. 3, 2014, 10:19 p.m. | #1
On 3 December 2014 at 09:17, Ola Liljedahl <ola.liljedahl@linaro.org> wrote:

> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
> ---
> Update doxygen comments, renaming of function params.
>
>  platform/linux-generic/include/api/odp_rwlock.h | 46
> ++++++++++++++-----------
>  1 file changed, 25 insertions(+), 21 deletions(-)
>
> diff --git a/platform/linux-generic/include/api/odp_rwlock.h
> b/platform/linux-generic/include/api/odp_rwlock.h
> index 59cf9cc..f3b2f71 100644
> --- a/platform/linux-generic/include/api/odp_rwlock.h
> +++ b/platform/linux-generic/include/api/odp_rwlock.h
> @@ -19,56 +19,60 @@
>  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[out] p_rwlck Pointer to a reader/writer lock
>

Is this also an "in" ?


>   */
> -void odp_rwlock_init(odp_rwlock_t *rwlock);
> +void odp_rwlock_init(odp_rwlock_t *p_rwlck);
>
>  /**
> - * Aquire a read lock.
> + * Aquire read permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to a RW Lock.
> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>   */
> -void odp_rwlock_read_lock(odp_rwlock_t *rwlock);
> +void odp_rwlock_read_lock(odp_rwlock_t *p_rwlck);
>
>  /**
> - * Release a read lock.
> + * Release read permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to the RW Lock.
> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>   */
> -void odp_rwlock_read_unlock(odp_rwlock_t *rwlock);
> +void odp_rwlock_read_unlock(odp_rwlock_t *p_rwlck);
>
>  /**
> - * Aquire a write lock.
> + * Aquire write permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to a RW Lock.
> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>   */
> -void odp_rwlock_write_lock(odp_rwlock_t *rwlock);
> +void odp_rwlock_write_lock(odp_rwlock_t *p_rwlck);
>
>  /**
> - * Release a write lock.
> + * Release write permission on a reader/writer lock.
>   *
> - * @param rwlock pointer to a RW Lock.
> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>   */
> -void odp_rwlock_write_unlock(odp_rwlock_t *rwlock);
> +void odp_rwlock_write_unlock(odp_rwlock_t *p_rwlck);
>
>  /**
>   * @}
> --
> 1.9.1
>
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp
>
Ola Liljedahl Dec. 3, 2014, 10:59 p.m. | #2
On 3 December 2014 at 23:19, Mike Holmes <mike.holmes@linaro.org> wrote:
>
>
> On 3 December 2014 at 09:17, Ola Liljedahl <ola.liljedahl@linaro.org> wrote:
>>
>> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
>> ---
>> Update doxygen comments, renaming of function params.
>>
>>  platform/linux-generic/include/api/odp_rwlock.h | 46
>> ++++++++++++++-----------
>>  1 file changed, 25 insertions(+), 21 deletions(-)
>>
>> diff --git a/platform/linux-generic/include/api/odp_rwlock.h
>> b/platform/linux-generic/include/api/odp_rwlock.h
>> index 59cf9cc..f3b2f71 100644
>> --- a/platform/linux-generic/include/api/odp_rwlock.h
>> +++ b/platform/linux-generic/include/api/odp_rwlock.h
>> @@ -19,56 +19,60 @@
>>  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[out] p_rwlck Pointer to a reader/writer lock
>
>
> Is this also an "in" ?
Not in my definition of [in] and [out] parameters. The content of
*p_rwlock is not read (and is thus irrelevant) by the init function.
The content of *p_rwlock is only written. Therefor p_rwlck is an [out]
parameter.

>
>>
>>   */
>> -void odp_rwlock_init(odp_rwlock_t *rwlock);
>> +void odp_rwlock_init(odp_rwlock_t *p_rwlck);
>>
>>  /**
>> - * Aquire a read lock.
>> + * Aquire read permission on a reader/writer lock.
>>   *
>> - * @param rwlock pointer to a RW Lock.
>> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>>   */
>> -void odp_rwlock_read_lock(odp_rwlock_t *rwlock);
>> +void odp_rwlock_read_lock(odp_rwlock_t *p_rwlck);
>>
>>  /**
>> - * Release a read lock.
>> + * Release read permission on a reader/writer lock.
>>   *
>> - * @param rwlock pointer to the RW Lock.
>> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>>   */
>> -void odp_rwlock_read_unlock(odp_rwlock_t *rwlock);
>> +void odp_rwlock_read_unlock(odp_rwlock_t *p_rwlck);
>>
>>  /**
>> - * Aquire a write lock.
>> + * Aquire write permission on a reader/writer lock.
>>   *
>> - * @param rwlock pointer to a RW Lock.
>> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>>   */
>> -void odp_rwlock_write_lock(odp_rwlock_t *rwlock);
>> +void odp_rwlock_write_lock(odp_rwlock_t *p_rwlck);
>>
>>  /**
>> - * Release a write lock.
>> + * Release write permission on a reader/writer lock.
>>   *
>> - * @param rwlock pointer to a RW Lock.
>> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
>>   */
>> -void odp_rwlock_write_unlock(odp_rwlock_t *rwlock);
>> +void odp_rwlock_write_unlock(odp_rwlock_t *p_rwlck);
>>
>>  /**
>>   * @}
>> --
>> 1.9.1
>>
>>
>> _______________________________________________
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> http://lists.linaro.org/mailman/listinfo/lng-odp
>
>
>
>
> --
> Mike Holmes
> Linaro  Sr Technical Manager
> LNG - ODP
Mike Holmes Dec. 4, 2014, 1:28 a.m. | #3
On 3 December 2014 at 17:59, Ola Liljedahl <ola.liljedahl@linaro.org> wrote:

> On 3 December 2014 at 23:19, Mike Holmes <mike.holmes@linaro.org> wrote:
> >
> >
> > On 3 December 2014 at 09:17, Ola Liljedahl <ola.liljedahl@linaro.org>
> wrote:
> >>
> >> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
> >> ---
> >> Update doxygen comments, renaming of function params.
> >>
> >>  platform/linux-generic/include/api/odp_rwlock.h | 46
> >> ++++++++++++++-----------
> >>  1 file changed, 25 insertions(+), 21 deletions(-)
> >>
> >> diff --git a/platform/linux-generic/include/api/odp_rwlock.h
> >> b/platform/linux-generic/include/api/odp_rwlock.h
> >> index 59cf9cc..f3b2f71 100644
> >> --- a/platform/linux-generic/include/api/odp_rwlock.h
> >> +++ b/platform/linux-generic/include/api/odp_rwlock.h
> >> @@ -19,56 +19,60 @@
> >>  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[out] p_rwlck Pointer to a reader/writer lock
> >
> >
> > Is this also an "in" ?
> Not in my definition of [in] and [out] parameters. The content of
> *p_rwlock is not read (and is thus irrelevant) by the init function.
> The content of *p_rwlock is only written. Therefor p_rwlck is an [out]
> parameter.
>
> Ok - I agree


> >
> >>
> >>   */
> >> -void odp_rwlock_init(odp_rwlock_t *rwlock);
> >> +void odp_rwlock_init(odp_rwlock_t *p_rwlck);
> >>
> >>  /**
> >> - * Aquire a read lock.
> >> + * Aquire read permission on a reader/writer lock.
> >>   *
> >> - * @param rwlock pointer to a RW Lock.
> >> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
> >>   */
> >> -void odp_rwlock_read_lock(odp_rwlock_t *rwlock);
> >> +void odp_rwlock_read_lock(odp_rwlock_t *p_rwlck);
> >>
> >>  /**
> >> - * Release a read lock.
> >> + * Release read permission on a reader/writer lock.
> >>   *
> >> - * @param rwlock pointer to the RW Lock.
> >> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
> >>   */
> >> -void odp_rwlock_read_unlock(odp_rwlock_t *rwlock);
> >> +void odp_rwlock_read_unlock(odp_rwlock_t *p_rwlck);
> >>
> >>  /**
> >> - * Aquire a write lock.
> >> + * Aquire write permission on a reader/writer lock.
> >>   *
> >> - * @param rwlock pointer to a RW Lock.
> >> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
> >>   */
> >> -void odp_rwlock_write_lock(odp_rwlock_t *rwlock);
> >> +void odp_rwlock_write_lock(odp_rwlock_t *p_rwlck);
> >>
> >>  /**
> >> - * Release a write lock.
> >> + * Release write permission on a reader/writer lock.
> >>   *
> >> - * @param rwlock pointer to a RW Lock.
> >> + * @param[in,out] p_rwlck Pointer to a reader/writer lock
> >>   */
> >> -void odp_rwlock_write_unlock(odp_rwlock_t *rwlock);
> >> +void odp_rwlock_write_unlock(odp_rwlock_t *p_rwlck);
> >>
> >>  /**
> >>   * @}
> >> --
> >> 1.9.1
> >>
> >>
> >> _______________________________________________
> >> lng-odp mailing list
> >> lng-odp@lists.linaro.org
> >> http://lists.linaro.org/mailman/listinfo/lng-odp
> >
> >
> >
> >
> > --
> > Mike Holmes
> > Linaro  Sr Technical Manager
> > LNG - ODP
>

Patch

diff --git a/platform/linux-generic/include/api/odp_rwlock.h b/platform/linux-generic/include/api/odp_rwlock.h
index 59cf9cc..f3b2f71 100644
--- a/platform/linux-generic/include/api/odp_rwlock.h
+++ b/platform/linux-generic/include/api/odp_rwlock.h
@@ -19,56 +19,60 @@ 
 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[out] p_rwlck Pointer to a reader/writer lock
  */
-void odp_rwlock_init(odp_rwlock_t *rwlock);
+void odp_rwlock_init(odp_rwlock_t *p_rwlck);
 
 /**
- * Aquire a read lock.
+ * Aquire read permission on a reader/writer lock.
  *
- * @param rwlock pointer to a RW Lock.
+ * @param[in,out] p_rwlck Pointer to a reader/writer lock
  */
-void odp_rwlock_read_lock(odp_rwlock_t *rwlock);
+void odp_rwlock_read_lock(odp_rwlock_t *p_rwlck);
 
 /**
- * Release a read lock.
+ * Release read permission on a reader/writer lock.
  *
- * @param rwlock pointer to the RW Lock.
+ * @param[in,out] p_rwlck Pointer to a reader/writer lock
  */
-void odp_rwlock_read_unlock(odp_rwlock_t *rwlock);
+void odp_rwlock_read_unlock(odp_rwlock_t *p_rwlck);
 
 /**
- * Aquire a write lock.
+ * Aquire write permission on a reader/writer lock.
  *
- * @param rwlock pointer to a RW Lock.
+ * @param[in,out] p_rwlck Pointer to a reader/writer lock
  */
-void odp_rwlock_write_lock(odp_rwlock_t *rwlock);
+void odp_rwlock_write_lock(odp_rwlock_t *p_rwlck);
 
 /**
- * Release a write lock.
+ * Release write permission on a reader/writer lock.
  *
- * @param rwlock pointer to a RW Lock.
+ * @param[in,out] p_rwlck Pointer to a reader/writer lock
  */
-void odp_rwlock_write_unlock(odp_rwlock_t *rwlock);
+void odp_rwlock_write_unlock(odp_rwlock_t *p_rwlck);
 
 /**
  * @}