NAME
          condition_alloc, condition_wait, condition_signal,
          condition_broadcast, condition_init, condition_clear,
          condition_free, condition_set_name, condition_name - cthread
          condition management

     LIBRARY
          C Threads Library (libcthreads.a)

     SYNOPSIS
          #include <cthread.h>

          RESULT condition_alloc( condition_t *cptr, int node);

          void condition_wait( condition_t c, mutex_t m);

          RESULT condition_signal( condition_t cond);

          void condition_broadcast( condition_t cond);

          void condition_init( condition_t cond);

          void condition_clear( condition_t cond);

          void condition_free( condition_t cond);

          void condition_set_name( condition_t cond, char *name);

          char *condition_name( condition_t cond);


     PARAMETERS
          cptr   specifies pointer to be filled in with a reference to
                 a condition variable.

          cond   specifies a condition variable.

          node   the logical processor upon which the condition vari-
                 able should be allocated.

          name   a name string to be associated with the condition
                 variable.


     DESCRIPTION
          These functions comprise Cthread's condition management rou-
          tines.  Almost all of the routines above are actually CPP
          macros instead of pure functions.  The purpose of the macros
          is simply to collect application level information such as
          the file and line number where the function is used.

          condition_alloc() allocates and initializes a condition
          variable on logical processor <node>. The variable cptr
          points to the new condition.  If the underlying memory model
          is such that the node parameter has no reasonable interpre-
          tation it is ignored.  The special values N_CURRENT and
          N_ANYWHERE are acceptable values for node and require the
          condition to be allocated on the current node or on any
          node, respectively.  See cthread_publish() for a possible
          way of making a pointer to the allocated condition available
          to all processors in a static global variable.

          The condition_alloc() macro captures the C source-level name
          of its first argument and uses that string as a default name
          for the allocated condition variable.  For example, "busy"
          is the default name given to the condition created by:
               result = condition_alloc(&busy, N_CURRENT);

          condition_wait() unlocks the specified mutex and causes the
          current thread to give up the processor and wait on the
          specified condition variable. When the thread is awakened
          with condition_signal() or condition_broadcast(), it returns
          to the run queue and attempts to relock the mutex.
          condition_wait() returns when the lock is achieved.  Note
          that the mutex m should be locked when this function is
          called.

          condition_signal() wakes up a thread that is waiting on the
          specified condition structure.  If no threads are waiting on
          the condition, this call has no effect.  If more than one
          thread is waiting, the first to queue itself will be wakened
          (placed on the run queue).  This function returns T_SUCCEED
          if a thread was awakened and T_NO_THREAD_QUEUED if no thread
          was waiting upon the condition.

          condition_broadcast() wakes up all threads that are waiting
          on the specified condition variable.  If no threads are
          waiting on the condition, this call has no effect.

          condition_init() initializes a condition variable.  This is
          used by condition_alloc() and could be used to initialize a
          variable of type struct condition.

          condition_clear() is analogous to clear operations defined
          on other synchronization variables.  For conditions, it is
          equivalent to condition_broadcast.

          condition_free() releases the memory assocated with a condi-
          tion variable.  The condition is cleared before being
          released.

          condition_set_name() associates the string name with the
          specified condition.  This name is used by monitoring and
          debugging tools.  (See cthread_parse_args() for debugging
          information.)  The string provided is copied into private
          memory().

          condition_name() returns returns the name string associated
          with the specified condition.

     DIAGNOSTICS
          condition_alloc() returns result T_SUCCEED if the condition
          allocation is successful.  It returns T_NOMEMORY if there is
          currently insufficient condition to satisfy the request.

          condition_signal() returns T_SUCCEED if a thread was awak-
          ened and T_NO_THREAD_QUEUED if no thread was waiting upon
          the condition.


     SEE ALSO
          cthread_intro(3), cthread_publish(3), cthread_parse_args(3),
          mutex_lock(3)

     AUTHOR
          Cthreads was written and maintained by many people.
          This man page written by Greg Eisenhauer.