[glib/rw-lock-docs] gthread: Clarify priority handling in GRWLock

[Philip Withnall <pwithnall src gnome org>]

commit 321b9d3b79b8bc25bbd68063c738c2a21cf86e28
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Oct 5 11:19:28 2018 +0100

    gthread: Clarify priority handling in GRWLock
    
    As we use pthread_rwlock_*() to implement GRWLock (on Unix), the
    priority of readers vs writers when trying to acquire a lock already
    held by one reader with a writer queued, is unspecified. i.e. We don’t
    explicitly prioritise the pending readers to acquire the lock (and block
    the writer), or vice-versa.
    
    Whatever our implementation on other platforms, we must document the
    priority as unspecified, as that’s what happens on Unix and is the
    least restrictive API guarantee we can make.
    
    Prompted by https://stackoverflow.com/q/52661672/2931197.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/gthread.c | 4 ++++
 1 file changed, 4 insertions(+)
---
diff --git a/glib/gthread.c b/glib/gthread.c
index 5debfa6ae..a36b37861 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -320,6 +320,10 @@
  * simultaneous read-only access (by holding the 'reader' lock via
  * g_rw_lock_reader_lock()).
  *
+ * It is unspecified whether readers or writers have priority in acquiring the
+ * lock when a reader already holds the lock and a writer is queued to acquire
+ * it.
+ *
  * Here is an example for an array with access functions:
  * |[<!-- language="C" --> 
  *   GRWLock lock;