| Message ID | 1417616254-31760-4-git-send-email-ola.liljedahl@linaro.org |
|---|---|
| State | New |
| Headers | show |
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 >
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
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 >
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); /** * @}
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(-)