[glib: 1/2] GRWLock: Tweak doc to make things a bit clearer
- From: Philip Withnall <pwithnall src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib: 1/2] GRWLock: Tweak doc to make things a bit clearer
- Date: Mon, 1 Mar 2021 11:43:56 +0000 (UTC)
commit ddb2b5fe54350986bca39f4d1f5ee7566beefadd
Author: Olivier Brunel <jjk jjacky com>
Date: Sat Feb 27 20:28:28 2021 +0100
GRWLock: Tweak doc to make things a bit clearer
The doc used different phrasing for the same thing, e.g. "if any thread"
vs "any other thread."
Also make it clear that trying to take a write lock while already having
a lock, or trying to take a read lock while having a write lock, is
undefined.
glib/gthread-posix.c | 26 ++++++++++++++++++--------
1 file changed, 18 insertions(+), 8 deletions(-)
---
diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c
index 2ec50f774..3d69767e6 100644
--- a/glib/gthread-posix.c
+++ b/glib/gthread-posix.c
@@ -537,10 +537,13 @@ g_rw_lock_clear (GRWLock *rw_lock)
* g_rw_lock_writer_lock:
* @rw_lock: a #GRWLock
*
- * Obtain a write lock on @rw_lock. If any thread already holds
+ * Obtain a write lock on @rw_lock. If another thread currently holds
* a read or write lock on @rw_lock, the current thread will block
* until all other threads have dropped their locks on @rw_lock.
*
+ * Calling g_rw_lock_writer_lock() while the current thread already
+ * owns a read or write lock on @rw_lock leads to undefined behaviour.
+ *
* Since: 2.32
*/
void
@@ -556,8 +559,9 @@ g_rw_lock_writer_lock (GRWLock *rw_lock)
* g_rw_lock_writer_trylock:
* @rw_lock: a #GRWLock
*
- * Tries to obtain a write lock on @rw_lock. If any other thread holds
- * a read or write lock on @rw_lock, it immediately returns %FALSE.
+ * Tries to obtain a write lock on @rw_lock. If another thread
+ * currently holds a read or write lock on @rw_lock, it immediately
+ * returns %FALSE.
* Otherwise it locks @rw_lock and returns %TRUE.
*
* Returns: %TRUE if @rw_lock could be locked
@@ -595,13 +599,19 @@ g_rw_lock_writer_unlock (GRWLock *rw_lock)
* @rw_lock: a #GRWLock
*
* Obtain a read lock on @rw_lock. If another thread currently holds
- * the write lock on @rw_lock, the current thread will block. If another thread
- * does not hold the write lock, but is waiting for it, it is implementation
- * defined whether the reader or writer will block. Read locks can be taken
+ * the write lock on @rw_lock, the current thread will block until the
+ * write lock was (held and) released. If another thread does not hold
+ * the write lock, but is waiting for it, it is implementation defined
+ * whether the reader or writer will block. Read locks can be taken
* recursively.
*
- * It is implementation-defined how many threads are allowed to
- * hold read locks on the same lock simultaneously. If the limit is hit,
+ * Calling g_rw_lock_reader_lock() while the current thread already
+ * owns a write lock leads to undefined behaviour. Read locks however
+ * can be taken recursively, in which case you need to make sure to
+ * call g_rw_lock_reader_unlock() the same amount of times.
+ *
+ * It is implementation-defined how many read locks are allowed to be
+ * held on the same lock simultaneously. If the limit is hit,
* or if a deadlock is detected, a critical warning will be emitted.
*
* Since: 2.32
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]