1 CONDITION(5)          Standards, Environments, and Macros         CONDITION(5)
   2 
   3 
   4 
   5 NAME
   6        condition - concepts related to condition variables
   7 
   8 DESCRIPTION
   9        Occasionally, a thread running within a mutex needs to wait for an
  10        event,  in which case it blocks or sleeps. When a thread is waiting for
  11        another thread to communicate its disposition, it uses a condition
  12        variable in conjunction with a mutex. Although a mutex is exclusive and
  13        the code it protects is sharable (at certain moments), condition
  14        variables enable the synchronization of differing events that share a
  15        mutex, but not necessarily data. Several condition variables may be
  16        used by threads to signal each other  when a task is complete, which
  17        then allows the next waiting thread to take  ownership of the mutex.
  18 
  19 
  20        A condition variable enables threads to atomically block and test the
  21        condition under the protection of a  mutual exclusion lock (mutex)
  22        until the condition is satisfied. If the condition is false, a thread
  23        blocks on a condition variable and atomically releases the mutex that
  24        is waiting for the condition to change.  If another thread changes the
  25        condition, it may wake up waiting threads by signaling the associated
  26        condition variable. The waiting threads, upon awakening, reacquire the
  27        mutex and re-evaluate the condition.
  28 
  29    Initialize
  30        Condition variables and mutexes should be global. Condition variables
  31        that are allocated in writable memory can synchronize threads among
  32        processes if they are shared by the cooperating processes (see mmap(2))
  33        and are initialized for this purpose.
  34 
  35 
  36        The scope of a condition variable is either intra-process or inter-
  37        process.  This is dependent upon whether the argument is passed
  38        implicitly or explicitly to the initialization  of that condition
  39        variable. A condition variable does not need to be explicitly
  40        initialized. A condition variable is initialized with all zeros, by
  41        default, and its scope is set  to within the calling process. For
  42        inter-process synchronization, a condition variable must be initialized
  43        once, and only once, before use.
  44 
  45 
  46        A condition variable must not be simultaneously initialized by multiple
  47        threads or re-initialized while in use by other threads.
  48 
  49 
  50        Condition variables attributes may be set to the default or customized
  51        at initialization.  POSIX threads even allow the default values to be
  52        customized.  Establishing these attributes varies depending upon
  53        whether POSIX or Solaris threads are used. Similar to the distinctions
  54        between POSIX and Solaris thread creation, POSIX condition variables
  55        implement the default, intra-process, unless an attribute object is
  56        modified for inter-process prior to the initialization of the condition
  57        variable. Solaris condition variables also implement as the default,
  58        intra-process; however, they set this attribute according to the
  59        argument, type, passed to their initialization function.
  60 
  61    Condition Wait
  62        The condition wait interface allows a thread to wait for a condition
  63        and atomically release the associated mutex that it needs to hold to
  64        check the condition. The thread waits for another thread to make the
  65        condition true and that thread's resulting call to signal and wakeup
  66        the waiting thread.
  67 
  68    Condition Signaling
  69        A condition signal allows a thread to unblock the next thread waiting
  70        on the condition variable, whereas, a condition broadcast allows a
  71        thread to unblock all threads waiting on the  condition variable.
  72 
  73    Destroy
  74        The condition destroy functions destroy any state, but not the space,
  75        associated with the condition variable.
  76 
  77 ATTRIBUTES
  78        See attributes(5) for descriptions of the following attributes:
  79 
  80 
  81 
  82 
  83        +---------------+-----------------+
  84        |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
  85        +---------------+-----------------+
  86        |MT-Level       | MT-Safe         |
  87        +---------------+-----------------+
  88 
  89 SEE ALSO
  90        fork(2), mmap(2), setitimer(2), shmop(2), cond_broadcast(3C),
  91        cond_destroy(3C), cond_init(3C), cond_signal(3C), cond_timedwait(3C),
  92        cond_wait(3C), pthread_cond_broadcast(3C), pthread_cond_destroy(3C),
  93        pthread_cond_init(3C), pthread_cond_signal(3C),
  94        pthread_cond_timedwait(3C), pthread_cond_wait(3C),
  95        pthread_condattr_init(3C), signal(3C), attributes(5), mutex(5),
  96        standards(5)
  97 
  98 NOTES
  99        If more than one thread is blocked on a condition variable, the order
 100        in which threads are unblocked is determined by the scheduling policy.
 101 
 102 
 103        USYNC_THREAD does not support multiple mappings to the same logical
 104        synch object. If you need to mmap() a synch object to different
 105        locations within the same address space, then the synch object should
 106        be initialized as a shared object USYNC_PROCESS for Solaris, and
 107        PTHREAD_PROCESS_PRIVATE for POSIX.
 108 
 109 
 110 
 111                                  May 16, 2020                     CONDITION(5)