unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

CV_CREATE(3L)                                                    CV_CREATE(3L)



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

SYNOPSIS
       #include <&lt;lwp/lwp.h>&gt;

       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 condi-
       tion variable must always be used within a monitor) is released  atomi-
       cally  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  notifi-
       cation  occurs,  the waiting thread will queue to reacquire the monitor
       it gave up.  It is possible to have different condition variables oper-
       ating  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  vari-
       able  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 asso-
       ciated  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 sched-
       uling priority on the condition.

       cv_notify() awakens at most one thread blocked on the  condition  vari-
       able  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_wait-
       ers()  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_enu-
       merate()  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  vari-
       ables 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 vari-
       able.

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 pos-
                           sessing 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  pos-
                           sessing 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  vari-
                           able.

       LE_NOTOWNED         Attempt  to  broadcast condition without possessing
                           the correct monitor lock.

SEE ALSO
       mon_create(3L)



                                21 January 1990                  CV_CREATE(3L)