Is pthread_cond_signal(3) man page correct?

[David Xu]

On 2011/02/28 05:26, Yuri wrote:
> Forwarding to standards@ and davidxu@ per Garrett Cooper suggestion.
> 
> Also I want to add that I came to this question while observing behavior
> consistent with multiple wakeup on FreeBSD-8.1. The heavily
> multi-threaded code that assumes that only one thread can be woken up by
> one pthread_cond_signal call crashes, and the only reasonable
> explanation so far is that more than one threads are actually being
> woken up.
> 
> Yuri
> 
> 
> On 02/27/2011 12:54, Yuri wrote:
>> On FreeBSD-8.1 this page says:
>> The pthread_cond_signal() function unblocks one thread waiting for the
>> condition variable cond.
>>
>> On Linux it says:
>> The /pthread_cond_signal/() function shall unblock at least one of the
>> threads that are blocked on the specified condition variable /cond/
>> (if any threads are blocked on /cond/).
>>
>> Also HP page
>> (http://docs.hp.com/en/B2355-90130/pthread_cond_signal.3T.html) says:
>> "If there are no threads blocked on /cond/, this function has no
>> effect." And later it says: "It is possible that more than one thread
>> can be unblocked due to a spurious wakeup."
>>
>> This is quite confusing: in case nobody is waiting does it block or
>> not? In case other threads are waiting it's really "any arbitrary
>> number of threads are woken up"? Or on FreeBSD it's strictly 1?
>> Shouldn't this be defined in one and only way by POSIX and all
>> POSIX-compliant systems should work exactly the same.
>>
>> I think man page should be expanded to give more comprehensive
>> explanation.
>>
>> Yuri
>> _______________________________________________
>> freebsd-hackers at freebsd.org mailing list
>> http://lists.freebsd.org/mailman/listinfo/freebsd-hackers
>> To unsubscribe, send any mail to
>> "freebsd-hackers-unsubscribe at freebsd.org"
>>

It is really not important if pthread_cond_signal wake up one thread
or multiple threads in corner case, because POSIX said:
---
When using condition variables there is always a Boolean predicate
involving shared variables associated with each condition wait that is
true if the thread should proceed. Spurious wakeups from the
pthread_cond_timedwait() or pthread_cond_wait() functions may occur.
Since the return from pthread_cond_timedwait() or pthread_cond_wait()
does not imply anything about the value of this predicate, the predicate
should be re-evaluated upon such return.
---

I think in normal case, pthread_cond_signal will wake up one thread,
but other events for example, UNIX signal and fork() may interrupt
a thread sleeping in kernel, and cause pthread_cond_wait to return
to userland, this is called spurious wakeup, and other events, I
can not think of yet, but I believe they exist.

Regards,
David Xu