Condition variables are used for waiting.  A condition variable suspends the
calling thread (or process) until a particular condition becomes true.
________________________________________________________________________

Basic condition variable operations are:

	- wait
	- signal
	- broadcast

Note:  use of the term "signal" has nothing to do with signal generation,
pending, delivery or handlers.

Of course, there are POSIX functions for these.  They return 0 on success,
some sort of errno on failure.  Link with -lpthread to get POSIX library.

 BKR: show the Makefile.

#include <pthread.h>

int pthread_condattr_init( pthread_condattr_t * attr );

	Initialize a condition variable attributes object attr with the
	default values for all of the attributes defined by the implementation.

	Redundant initialization would be BAD -- undefined behavior.

int pthread_condattr_destroy( pthread_condattr_t * attr );

	Destroys a condition variable attribute variable.

int pthread_condattr_setpshared( pthread_condattr_t * attr, int pshared );

	Sets condition attribute to either:
	PTHREAD_PROCESS_SHARED for multiple processes
	PTHREAD_PROCESS_PRIVATE for use between threads in one process (the default)

int pthread_cond_init( pthread_cond_t * cond, const pthread_condattr_t * attr );

	Initialize a condition variable with the attributes referenced by attr.
	If attr is NULL, the default condition variable attributes are used,
	which has the same effect as passing the address of a default condition
	variable attributes object.

	Of course, you can always initialize a static/global condition variable with:

	pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

int pthread_cond_destroy( pthread_cond_t * cond );

	Destroys destroys the condition variable cond. This includes invalidating
	cond and frees any associated implementation-allocated dynamic resources.

int pthread_cond_wait( pthread_cond_t * cond, pthread_mutex_t * mutex );

	A basic operation AT LAST.

	Atomically unlocks the mutex and waits for the condition to be signalled
	or broadcast.

	Why must this be atomic?

	The calling thread must be the owner of the mutual exclusion lock pointed
	to by mutex before calling pthread_cond_wait, otherwise the behavior is
	unpredictable.

	The calling thread can resume execution when the condition is signaled
	or broadcast, or when interrupted. The logical condition should always
	be checked on return, as a return might not have been caused by a change
	in the condition.  (just 'cause it was signalled, don't necessarily make
	it so).

int pthread_cond_signal( pthread_cond_t * cond );

	Wakes up a single thread, if one exists, waiting on the condition cond,
	even if more than one is waiting.  Which one is generally not predictable.

	No effect if no thread is waiting.

	Curious statement:  Will be more reliable if the associated mutex used
	by waiters is held across the call.  Thus, calling thread (the mutex
	owner) should invoke pthread_cond_signal() BEFORE unlocking the mutex.

int pthread_cond_broadcast( pthread_cond_t * cond );

	Wakes up all waiting threads, waiting on the condition cond.

	No effect if no thread is waiting.

	Curious statement:  Will be more reliable if the associated mutex used
	by waiters is held across the call.  Thus, calling thread (the mutex
	owner) should invoke pthread_cond_broadcast() BEFORE unlocking the mutex.

	QUESTION:  If only one thread can get the mutex, why bother to wake
	up more than one?