NAME
          mutex_alloc, mutex_lock, mutex_unlock, mutex_init,
          mutex_clear, mutex_free, mutex_set_name, mutex_name -
          cthread mutex management

     LIBRARY
          C Threads Library (libcthreads.a)

     SYNOPSIS
          #include <cthread.h>

          RESULT mutex_alloc( mutex_t *mptr, int node);

          void mutex_lock( mutex_t m);

          void mutex_unlock( mutex_t m);

          void mutex_init( mutex_t m);

          void mutex_clear( mutex_t m);

          void mutex_free( mutex_t m);

          void mutex_set_name( mutex_t m, char *name);

          char *mutex_name( mutex_t m);


     PARAMETERS
          mptr   specifies pointer to be filled in with a reference to
                 a mutex variable.

          m      specifies a mutex variable.

          node   the logical processor upon which the mutex variable
                 should be allocated.

          name   a name string to be associated with the mutex vari-
                 able.


     DESCRIPTION
          These functions comprise Cthread's mutex 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.

          mutex_alloc() allocates and initializes a mutex variable
          using memory located on processor <node>. The variable cptr
          points to the new mutex. If the underlying memory model is
          such that the node parameter has no reasonable
          interpretation it is ignored.  The special values N_CURRENT
          and N_ANYWHERE are acceptable values for node and require
          the mutex to be allocated on the current node or on any
          node, respectively.  See cthread_publish() for a possible
          way of making the pointer to the allocated mutex available
          to all processors in a static global variable.  The
          mutex_alloc() macro captures the C source-level name of its
          first argument and uses that string as a default name for
          the allocated mutex variable.

          mutex_lock() attempts to lock the specified mutex.  If the
          mutex is currently unlocked, the calling thread is granted
          the lock and continues.  If the mutex is currently locked,
          the calling thread gives up the processor and wait on the
          specified mutex variable.  Note that there is no scheduler
          involvement, and so no opportunity for other threads to run,
          unless the thread is denied the lock.  This can result in
          starvation for other threads on the same processor.
          cthread_yield() can be useful in preventing this.

          mutex_unlock() unlocks the specified mutex.  There is no
          scheduler involvement and the current thread retains control
          of the processor.

          mutex_init() initializes a mutex variable.  This is used by
          mutex_alloc() and could be used to initialize a variable of
          type struct cth_mutex.

          mutex_clear() is analogous to clear operations defined on
          other synchronization variables.  For mutexes, it is
          equivalent to mutex_unlock()

          mutex_free() releases the memory assocated with a mutex
          variable.  The mutex is cleared before being released.

          mutex_set_name() associates the string name with the speci-
          fied mutex.  This name is used by monitoring and debugging
          tools.  (See cthread_parse_args() for debugging informa-
          tion.)  The string provided is copied into private memory.

          mutex_name() returns returns the name string associated with
          the specified mutex.

     DIAGNOSTICS
          mutex_alloc() returns result T_SUCCEED if the mutex alloca-
          tion is successful.  It returns T_NOMEMORY if there is
          currently insufficient mutex to satisfy the request.

          Attempts to operate upon a mutex that has been previously
          freed will yield unpredictable and probably undesirable
          results.

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

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