man/man3/pthread_cond_init.3: CAVEATS: Add a note regarding real-time usage

The "old" implementation led to priority inversion and was more or less
easy to trigger.  It seems that after the rewrite the issue disappeared
especially since the old workaround does not apply anymore.

Add a note mentioning the old problem and why the issue is not gone
since the rewrite in glibc 2.25 but harder to trigger.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Cc: André Almeida <andrealmeid@igalia.com>
Cc: Darren Hart <dvhart@infradead.org>
Cc: Davidlohr Bueso <dave@stgolabs.net>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: Juri Lelli <juri.lelli@redhat.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Valentin Schneider <vschneid@redhat.com>
Cc: Waiman Long <longman@redhat.com>
Message-ID: <20250915141305.906440-6-bigeasy@linutronix.de>
[alx: wfix, srcfix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man3/pthread_cond_init.3 b/man/man3/pthread_cond_init.3
index 0045e7ecee0751e764c32187a45bc58726c64802..88600b3a5b2e70e95199d3d848f9579f15b233fc 100644 (file)
--- a/man/man3/pthread_cond_init.3
+++ b/man/man3/pthread_cond_init.3
@@ -115,6 +115,7 @@ if all threads always acquire the mutex before signaling the condition,
 this guarantees that the condition cannot be signaled (and thus ignored)
 between the time a thread locks the mutex
 and the time it waits on the condition variable.
+See CAVEATS below.
 .P
 .BR pthread_cond_timedwait ()
 atomically unlocks
@@ -240,6 +241,29 @@ Some threads are currently waiting on
 .BR gettimeofday (2),
 .BR nanosleep (2).
 .
+.SH CAVEATS
+The implementation of the provided functions until
+glibc 2.25 used an internal data lock.
+This lock did not support priority-inheritance and
+was subject to unbounded priority inversion,
+visible on a real-time system.
+.P
+After the rewrite of the implementation in glibc 2.25
+the usage of internal lock changed.
+The internal lock is always acquired by
+the signaling functions
+.BR pthread_cond_signal ()
+and
+.BR pthread_cond_broadcast ().
+The waiting function acquires the lock
+if the waiting process was interrupted.
+The interruption can be caused for instance
+by a specified timeout,
+and denoted by the error value
+.BR ETIMEDOUTA ,
+or by a received signal,
+which is denoted by the error value
+.BR EINTR .
 .
 .SH EXAMPLE
 Consider two shared variables