cv_create, cv_destroy, cv_wait, cv_notify, cv_broadcast, cv_send, cv_enumerate, cv_waiters, SAMECV - manage LWP condition variables

---

SYNOPSIS

#include <lwp/lwp.h>

cv_t cv_create(cv, mid)
cv_t *cv;
mon_t mid;

int cv_destroy(cv)
cv_t cv;

int cv_wait(cv)
cv_t cv;

int cv_notify(cv)
cv_t cv;

int cv_send(cv, tid)
cv_t cv;
lwp_t tid

int cv_broadcast(cv)
cv_t cv;

int cv_enumerate(vec, maxsize)
cv_t vec[];	/* will contain list of all conditions */
int maxsize;	/* maximum size of vec */

int cv_waiters(cv, vec, maxsize)
cv_t cv;		/* condition variable being interrogated */
thread_t vec[];	/* which threads are blocked on cv */
int maxsize;	/* maximum size of vec */

SAMECV(c1, c2)

DESCRIPTION

Condition variables are useful for synchronization within monitors. By waiting on a condition variable, the currently-held monitor (a condition variable must always be used within a monitor) is released atomically and the invoking thread is suspended. When monitors are nested, monitor locks other than the current one are retained by the thread. At some later point, a different thread may awaken the waiting thread by issuing a notification on the condition variable. When the notification occurs, the waiting thread will queue to reacquire the monitor it gave up. It is possible to have different condition variables operating within the same monitor to allow selectivity in waking up threads.

cv_create() creates a new condition variable (returned in cv) which is bound to the monitor specified by mid. It is illegal to access (using cv_wait(), cv_notify(), cv_send() or cv_broadcast()) a condition variable from a monitor other than the one it is bound to. cv_destroy() removes a condition variable.

cv_wait() blocks the current thread and releases the monitor lock associated with the condition (which must also be the monitor lock most recently acquired by the thread). Other monitor locks held by the thread are not affected. The blocked thread is enqueued by its scheduling priority on the condition.

cv_notify() awakens at most one thread blocked on the condition variable and causes the awakened thread to queue for access to the monitor released at the time it waited on the condition. It can be dangerous to use cv_notify() if there is a possibility that the thread being awakened is one of several threads that are waiting on a condition variable and the awakened thread may not be the one intended. In this case, use of cv_broadcast() is recommended.

cv_broadcast() is the same as cv_notify() except that all threads blocked on the condition variable are awakened. cv_notify() and cv_broadcast() do nothing if no thread is waiting on the condition. For both cv_notify() and cv_broadcast(), the currently held monitor must agree with the one bound to the condition by cv_create().

cv_send() is like cv_notify() except that the particular thread tid is awakened. If this thread is not currently blocked on the condition, cv_send() reports an error.

cv_enumerate() lists the ID of all of the condition variables. The value returned is the total number of condition variables. The vector supplied is filled in with the ID's of condition variables. cv_waiters() lists the ID's of the threads blocked on the condition variable cv and returns the number of threads blocked on cv. For both cv_enumerate() and cv_waiters(), maxsize is used to avoid exceeding the capacity of the list vec. If the number of entries to be filled is greater than maxsize, only maxsize entries are filled in vec. It is legal in both of these primitives to specify a maxsize of 0.

SAMECV is a convenient predicate used to compare two condition variables for equality.

RETURN VALUES

cv_create(), cv_destroy(), cv_send(), cv_wait(), cv_notify() and cv_broadcast() return:

0

on success.

-1

on failure and set errno to indicate the error.

cv_enumerate() returns the total number of condition variables.

cv_waiters() returns the number of threads blocked on a condition variable.

ERRORS

cv_destroy() will fail if one or more of the following is true:

LE_INUSE

Attempt to destroy condition variable being waited on by a thread.

LE_NONEXIST

Attempt to destroy non-existent condition variable.

cv_wait() will fail if one or more of the following is true:

LE_NONEXIST

Attempt to wait on non-existent condition variable.

LE_NOTOWNED

Attempt to wait on a condition without possessing the correct monitor lock.

cv_notify() will fail if one or more of the following is true:

LE_NONEXIST

Attempt to notify non-existent condition variable.

LE_NOTOWNED

Attempt to notify condition variable without possessing the correct monitor.

cv_send() will fail if one or more of the following is true:

LE_NONEXIST

Attempt to awaken non-existent condition variable.

LE_NOTOWNED

Attempt to awaken condition variable without possessing the correct monitor lock.

LE_NOWAIT

The specified thread is not currently blocked on the condition.

cv_broadcast() will fail if one or more of the following is true:

LE_NONEXIST

Attempt to broadcast non-existent condition variable.

LE_NOTOWNED

Attempt to broadcast condition without possessing the correct monitor lock.

SEE ALSO

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97