Condition variables are used in conjunction with mutexes to wait for conditions
to occur.
Condition variables are created with
cv_init (,);
where
Fa cvp
is a pointer to space for a
Vt struct cv ,
and
Fa desc
is a pointer to a null-terminated character string that describes the condition
variable.
Condition variables are destroyed with
cv_destroy (.);
Threads wait on condition variables by calling
cv_wait (,);
cv_wait_sig (,);
cv_wait_unlock (,);
cv_timedwait (,);
or
cv_timedwait_sig (.);
Threads unblock waiters by calling
cv_signal ();
to unblock one waiter, or
cv_broadcast ();
or
cv_broadcastpri ();
to unblock all waiters.
In addition to waking waiters,
cv_broadcastpri ();
ensures that all of the waiters have a priority of at least
Fa pri
by raising the priority of any threads that do not.
cv_wmesg ();
returns the description string of
Fa cvp ,
as set by the initial call to
cv_init (.);
The
Fa lock
argument is a pointer to either a
mutex(9),
rwlock(9),
or
sx(9)
lock.
A
mutex(9)
argument must be initialized with
MTX_DEF
and not
MTX_SPIN
A thread must hold
Fa lock
before calling
cv_wait (,);
cv_wait_sig (,);
cv_wait_unlock (,);
cv_timedwait (,);
or
cv_timedwait_sig (.);
When a thread waits on a condition,
Fa lock
is atomically released before the thread is blocked, then reacquired
before the function call returns.
The
cv_wait_unlock ();
function does not reacquire the lock before returning.
All waiters must pass the same
Fa lock
in conjunction with
Fa cvp .
When
cv_wait (,);
cv_wait_sig (,);
cv_wait_unlock (,);
cv_timedwait (,);
and
cv_timedwait_sig ();
unblock, their calling threads are made runnable.
cv_timedwait ();
and
cv_timedwait_sig ();
wait for at most
Fa timo
/
HZ
seconds before being unblocked and returning
Er EWOULDBLOCK ;
otherwise, they return 0.
cv_wait_sig ();
and
cv_timedwait_sig ();
return prematurely with a value of
Er EINTR
or
Er ERESTART
if a signal is caught, or 0 if signaled via
cv_signal ();
or
cv_broadcast (.);
RETURN VALUES
If successful,
cv_wait_sig (,);
cv_timedwait (,);
and
cv_timedwait_sig ();
return 0.
Otherwise, a non-zero error code is returned.
cv_wmesg ();
returns the description string that was passed to
cv_init (.);
ERRORS
cv_wait_sig ();
and
cv_timedwait_sig ();
will fail if:
Bq Er EINTR
A signal was caught and the system call should be interrupted.
Bq Er ERESTART
A signal was caught and the system call should be restarted.
cv_timedwait ();
and
cv_timedwait_sig ();
will fail if:
