pthread_rwlock_rdlock: add comments regarding glibc behaviour

[Bruno Haible]

Now that the desired POSIX behaviour of pthread_rwlock_rdlock has been
clarified [1], it is no longer disputed that the glibc behaviour of this
function is not POSIX compliant [2].

Therefore it's time to update the gnulib documentation about it.

[1] http://austingroupbugs.net/view.php?id=1111 
[2] https://sourceware.org/bugzilla/show_bug.cgi?id=13701


2018-06-18  Bruno Haible  <address@hidden>

        pthread_rwlock_rdlock: Add comments regarding glibc behaviour.
        * m4/pthread_rwlock_rdlock.m4: Add comment.
        * doc/posix-functions/pthread_rwlock_rdlock.texi: Mention that rwlocks
        are reader-preferring in glibc.
        * doc/posix-functions/pthread_rwlock_tryrdlock.texi: Likwise.
        * doc/posix-functions/pthread_rwlock_timedrdlock.texi: Likewise.

diff --git a/m4/pthread_rwlock_rdlock.m4 b/m4/pthread_rwlock_rdlock.m4
index 9c1d5d0..6812b4f 100644
--- a/m4/pthread_rwlock_rdlock.m4
+++ b/m4/pthread_rwlock_rdlock.m4
@@ -1,4 +1,4 @@
-# pthread_rwlock_rdlock.m4 serial 1
+# pthread_rwlock_rdlock.m4 serial 2
 dnl Copyright (C) 2017-2018 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
@@ -23,12 +23,14 @@ dnl time, a phenomenon called "writer starvation".
 dnl Without such a guarantee, applications have a hard time avoiding writer
 dnl starvation.
 dnl
-dnl POSIX:2008 makes this requirement only for implementations that support TPS
+dnl POSIX:2017 makes this requirement only for implementations that support TPS
 dnl (Thread Priority Scheduling) and only for the scheduling policies 
SCHED_FIFO
 dnl and SCHED_RR, see
 dnl 
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_rdlock.html
-dnl but test verifies the guarantee regardless of TPS and regardless of
+dnl but this test verifies the guarantee regardless of TPS and regardless of
 dnl scheduling policy.
+dnl Glibc currently does not provide this guarantee, see
+dnl https://sourceware.org/bugzilla/show_bug.cgi?id=13701
 AC_DEFUN([gl_PTHREAD_RWLOCK_RDLOCK_PREFER_WRITER],
 [
   AC_REQUIRE([gl_THREADLIB_EARLY])
diff --git a/doc/posix-functions/pthread_rwlock_rdlock.texi 
b/doc/posix-functions/pthread_rwlock_rdlock.texi
index 3759f78..387dabe 100644
--- a/doc/posix-functions/pthread_rwlock_rdlock.texi
+++ b/doc/posix-functions/pthread_rwlock_rdlock.texi
@@ -15,4 +15,13 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 Minix 3.1.8, HP-UX 11, OSF/1 4.0, Solaris 2.6, mingw, MSVC 14, BeOS.
address@hidden
+This function prefers readers to writers (meaning, when this function is
+called on an rwlock that is already taken by one or more readers, and
+another writer is already waiting to take it, this function may return
+successfully immediately) -- a behaviour that may lead to writer starvation --
+on some platforms:
+glibc 2.28.
+As a workaround, you can use the @code(gl_rwlock_t} type from the Gnulib
+module @samp{lock}.
 @end itemize
diff --git a/doc/posix-functions/pthread_rwlock_timedrdlock.texi 
b/doc/posix-functions/pthread_rwlock_timedrdlock.texi
index 07194c1..52cc74a 100644
--- a/doc/posix-functions/pthread_rwlock_timedrdlock.texi
+++ b/doc/posix-functions/pthread_rwlock_timedrdlock.texi
@@ -15,4 +15,11 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 Mac OS X 10.5, FreeBSD 5.2.1, OpenBSD 3.8, Minix 3.1.8, AIX 5.1, HP-UX 11, 
IRIX 6.5, OSF/1 5.1, Solaris 9, Cygwin, mingw, MSVC 14, BeOS.
address@hidden
+This function prefers readers to writers (meaning, when this function is
+called on an rwlock that is already taken by one or more readers, and
+another writer is already waiting to take it, this function may return
+successfully immediately) -- a behaviour that may lead to writer starvation --
+on some platforms:
+glibc 2.28.
 @end itemize
diff --git a/doc/posix-functions/pthread_rwlock_tryrdlock.texi 
b/doc/posix-functions/pthread_rwlock_tryrdlock.texi
index 370a899..b817212 100644
--- a/doc/posix-functions/pthread_rwlock_tryrdlock.texi
+++ b/doc/posix-functions/pthread_rwlock_tryrdlock.texi
@@ -15,4 +15,11 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 Minix 3.1.8, HP-UX 11, OSF/1 4.0, Solaris 2.6, mingw, MSVC 14, BeOS.
address@hidden
+This function prefers readers to writers (meaning, when this function is
+called on an rwlock that is already taken by one or more readers, and
+another writer is already waiting to take it, this function may return
+successfully immediately) -- a behaviour that may lead to writer starvation --
+on some platforms:
+glibc 2.28.
 @end itemize