pthread_cond_signal(3T)           SDK R4.11          pthread_cond_signal(3T)


NAME
       pthread_cond_signal pthread_cond_broadcast - unblock one or more
       threads waiting on a condition

SYNOPSIS
       #include <pthread.h>

       int pthread_cond_signal(pthread_cond_t *cond);

       int pthread_cond_broadcast(pthread_cond_t *cond);

   where:
       cond   A pointer to a condition variable

DESCRIPTION
       These two functions unblock threads blocked on the condition variable
       pointed to by cond.

       The pthread_cond_signal() call unblocks at least one of the threads
       that are blocked on the condition variable pointed to by cond (if any
       threads are blocked on the condition variable).

       The pthread_cond_broadcast() call unblocks all threads currently
       blocked on the condition variable pointed to by cond.

       If more than one thread is blocked on a condition, the scheduling
       policy determines the order in which threads are unblocked.  In
       general, the highest priority thread is unblocked first.

       When each thread unblocked as a result of a pthread_cond_signal() or
       pthread_cond_broadcast() returns from its call to pthread_cond_wait()
       or pthread_cond_timedwait(), the thread owns the mutex with which it
       called pthread_cond_wait() or pthread_cond_timedwait().  Any
       unblocked thread contends for the mutex according to its scheduling
       policy and as if it had implicitly called pthread_mutex_lock().  That
       is, it does not atomically re-obtain the mutex in the same way that
       pthread_cond_wait() atomically releases the mutex.

       The pthread_cond_signal() and pthread_cond_broadcast() functions have
       no effect if there are no threads currently blocked on cond.  That
       is, the wakeup is not remembered for subsequent waiters.

DIAGNOSTICS
   Returns
       If successful, these functions return 0.  Otherwise they return -1
       and set errno to indicate the error.

   Errors
       For each of the following conditions, pthread_cond_signal() and
       pthread_cond_broadcast() return -1 and set errno to the corresponding
       value:

       [EINVAL]  The value specified by cond is invalid.  This occurs when
                 DG/UX detects that the condition variable pointed to by
                 cond has not been properly initialized or has been
                 corrupted.

SEE ALSO
       pthread_cond_init(3T), pthread_cond_timedwait(3T),
       pthread_cond_wait(3T).

NOTES
       Typically, a thread satisifies some predicate before calling one of
       these functions.  In fact, it is crucial that the predicate be
       satisified before unblocking threads that wish to re-check the
       predicate.  Satisfying the predicate after unblocking threads may
       lead to threads waking up and going back to sleep before the
       predicate is actually satisfied; in this case, a wake up could be
       missed.

       It is not necessary to hold a mutex when calling
       pthread_cond_signal() or pthread_cond_broadcast().  In fact, it is
       typically better not to hold the mutex in order to avoid an immediate
       priority preemption while the mutex is still held.  This could lead
       to unnecessary context switching.  However, it is typically correct
       to evaluate the decision to perform the unblock call while holding
       the mutex.

       Because pthread_cond_signal() awakens at least one thread, an
       application should take care in not assuming that only one will be
       awakened.  This, combined with other reasons discussed in
       pthread_cond_wait(3T), dictate that waiters should always re-check
       their predicates when they return from their call to
       pthread_cond_wait() or pthread_cond_timedwait().

       Because an unblocked thread does not atomically reobtain the mutex,
       it should not assume that it will be the first thread to obtain it.
       Another thread could obtain the mutex first, and then, for example,
       take the resource for which the unblocked thread was signaled.  This
       is another reason why each thread should re-check its predicate.  A
       call to pthread_cond_signal() or pthread_cond_broadcast() should be
       taken to mean "wake up and try again" instead of "wake up, you have
       succeeded."

       Calls to pthread_cond_signal() and pthread_cond_broadcast() are
       memory synchronization points.  That is, the caller is guaranteed to
       have completed any memory references at the time one of these
       functions begins execution.

       Calls to pthread_cond_signal() and pthread_cond_broadcast() are
       async-safe, that is, they can be safely called out of signal handlers
       executed asynchronously by the calling thread.  The only other
       standard Pthread function that is async-safe is
       pthread_mutex_trylock().


Licensed material--property of copyright holder(s)