When does pthread_cond_wait() return?
Neither the man page (Last change: 23 Mar 2005 ) nor the Solaris 10 Multithreaded Programming Guide clearly says when exactly pthread_cond_wait() returns. The latter says: "The ... routine always returns with the mutex locked and owned by the calling thread, ... This function blocks until the condition is signaled. The function atomically releases the associated mutex lock before blocking, and atomically acquires the mutex again before returning." At first, I thought, if there is no error, the function returns 0 AND THEN the calling thread blocks itself until signaled. But then if it "returns with the mutex locked", then there would be an infinite wait. So the only reasonable explanation is that, assumed no error, the function returns (with a value 0) only after the condition variable is signalled. In other words, assumed no error, the function does not return if the con var is not signaled. That is, the function blocks the calling thread until it returns; once the function returns, the calling thread is no longer blocked. Is my understanding correct? I wish the Sun documentation would be clearer - it can talk about what happens after the function returns all it wants but it misses the important thing which is: at what time the function returns! Now it seems the reader has to read between the lines and guess.
[1337 byte] By [
minglai] at [2007-11-26 10:30:21]
# 1
It's a standard function. You can try other man pages if you think Sun's version
is confusing. Here is one:
http://www.opengroup.org/pubs/online/7908799/xsh/pthread_cond_wait.html
The basic idea behind the function is to block until the CV is signalled.
It is a common problem with man pages on all UNIX systems, that they
do not have any sort of basic introductory paragraphs at the top where
such information would be most useful.
Technical books are much better for that sort of introduction. So perhaps a
basic book on threads or pthreads or POSIX pthreads would be a good way
to come up to speed on all the pthreads routines.
--chris
# 2
First thing first, is my understanding correct?
I did read a couple of textbooks and they all neglect to explain when this function returns. To be fair, the man page on my Linux system is no better than the Solaris one. I think the timing of return is as important and basic as the return values, etc and this info should really be in the man page; it is not something that is just optional in an introductory paragraph.
http://www.opengroup.org/pubs/online/7908799/xsh/pthread_cond_wait.html
does not say when the function returns either. (Well, it does say "Upon successful completion, a value of zero is returned" but does not say when the function "completes".) Perhaps all those book authors use all these man pages and Unix Spec as references in writing their books - if the man pages etc are silent on a particular point, the authors just play safe and look the other way rather than saying something wrong. As an aside, I feel that there are few good books on pthread programming that offer any insight at all.
# 3
IMHO, man page is perfectly clear: function returns after condition was signalled AND it (function)
acquired mutex.
Yes, this function blocks calling thread until it returns, this is what this function for :-)
Note that it must to release mutex before waiting for condition to avoid deadlock.
# 4
Do you mind pointing out where in the man page that it is perfectly clearly said that the function returns after the condition was signalled and it (function) acquired the mutex?
Contrary to the man pages, the POSIX standard and the many technical books and tutorials on pthread with respect to the return timing of this blocking function, the materials on the Message Passing Interface (MPI), as an example, is much better. For example, regarding MPI_Send(), the MPI Standard (http://www.mpi-forum.org/docs/mpi-11-html/node40.html#Node40) clearly says "The send call described in Section "Blocking send" is blocking: it does not return until the message data and envelope have been safely stored away so that the sender is free to access and overwrite the send buffer. ... A blocking send can complete as soon as the message was buffered, ..." A technical book "MPI - The Complete Reference, Vol 1, 2 ed) says about MPI_Receive(): "That version of receive is blocking. It returns only after the receive buffer contains the newly received message. A receive could complete before the matching send has completed ..." (page 49) This is the kind of explanation that I would call "clear." The timing of the function return, or when it completes, is critical and it warrants a clear and precise explanation.
# 5
I jus read the first 4 paragraphs of the man page
on my desktop (Nevada build 41) and nowhere does
it say that the function returns after the condition variable
is signalled. I'm with minglai on this one.
Feel free to file a bug using bugs.opensolaris.org.
It always helps if you suggest a good wording in your bug report.
--chris
# 6
man -s 5 condition perhaps? ;-)
# 7
My version (SunOS 5.10 Last change: 20 Jul 1998) of the man page of 'condition' has the following:
Condition Wait
The condition wait interface allows a thread to wait for a
condition and atomically release the associated mutex that
it needs to hold to check the condition. The thread waits
for another thread to make the condition true and that
thread's resulting call to signal and wakeup the waiting
thread.
It does not say when wait() returns. Yes, the threads waits by caling wait() ... but it does not say whether it waits inside the wait() function or outside the function. It is conceivable that the thread calls wait() and wait() returns successsfully indicating that now the thread is waiting, and then the waiting thread is waken up by a signal().
# 8
> it does not say whether it waits inside the wait() function or outside the function
I fail to understand how a thread can wait outside of the function; functions do something and then return control to their callers, not the other way around. I mean, function can't return and then do what it's supposed to (starting a thread is a bit different, though, but even in this case pthread_create(), for example, creates a thread and then returns; later, the other function passed as pthread_create() parameter starts to do its job).
If a thread would wait outside of the function wait(), then another questions presents itself: where does it wait? Right on the next instruction? If so, then there's no visible difference for the app, because the app wouldn't know that wait() has returned.
# 9
I think you guys are going down a rat hole here. There is no way to *prove*
something is poorly written. It's a matter of opinion. And each person
is entitled to their own opinion. In my opinion an novice user should be able to read
the first two paragraphs of any man page and get something useful out of it.
(Perhaps the useful bit is: read XYZ manual to get an overview, then come back here)
Others might think I am holding our man pages to too high a standard.
# 10
I agree that the man pages should be more adept at pointing to resources outside of the
man pages themselves. Back in SunOS4 days, this was possible because Sun published
a lot of programming instructional material in the separate manuals. Since then, Sun has
largely ceased publishing that kind of tutorial material, and one must turn instead to other
sources.
In the case of networking routines, I believe the man pages should say something along
the lines of "you don't stand a chance of using these routines properly unless you pick up
a copy of Stevens, Fenner, and Rudoff, UNIX Network Programming, Volume 1, 3rd ed.,
and read it thoroughly". In the case of pthreads routines, the man pages should say
"you really need to pick up a copy of Kleiman, Shah, and Smaalders, Programming with
Threads, or an equivalent text, to understand how to use multi-threading routines".
The only trouble with the latter statement is that this book, like the others I know of
on C/C++ threading, was written in the 90's and is getting a little out of date (no
coverage of recent additions to pthreads like pthread_rwlock_rdlock() and related
routines, for instance).
