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 <br...@clisp.org> 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. +@item +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. +@item +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. +@item +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
