pthread_cond_broadcast.3p (8118B)
- '\" et
- .TH PTHREAD_COND_BROADCAST "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- pthread_cond_broadcast,
- pthread_cond_signal
- \(em broadcast or signal a condition
- .SH SYNOPSIS
- .LP
- .nf
- #include <pthread.h>
- .P
- int pthread_cond_broadcast(pthread_cond_t *\fIcond\fP);
- int pthread_cond_signal(pthread_cond_t *\fIcond\fP);
- .fi
- .SH DESCRIPTION
- These functions shall unblock threads blocked on a condition variable.
- .P
- The
- \fIpthread_cond_broadcast\fR()
- function shall unblock all threads currently blocked on the specified
- condition variable
- .IR cond .
- .P
- The
- \fIpthread_cond_signal\fR()
- function shall unblock at least one of the threads that are blocked
- on the specified condition variable
- .IR cond
- (if any threads are blocked on
- .IR cond ).
- .P
- If more than one thread is blocked on a condition variable, the
- scheduling policy shall determine the order in which threads are
- unblocked. When each thread unblocked as a result of a
- \fIpthread_cond_broadcast\fR()
- or
- \fIpthread_cond_signal\fR()
- returns from its call to
- \fIpthread_cond_wait\fR()
- or
- \fIpthread_cond_timedwait\fR(),
- the thread shall own the mutex with which it called
- \fIpthread_cond_wait\fR()
- or
- \fIpthread_cond_timedwait\fR().
- The thread(s) that are unblocked shall contend for the mutex according
- to the scheduling policy (if applicable), and as if each had called
- \fIpthread_mutex_lock\fR().
- .P
- The
- \fIpthread_cond_broadcast\fR()
- or
- \fIpthread_cond_signal\fR()
- functions may be called by a thread whether or not it currently owns
- the mutex that threads calling
- \fIpthread_cond_wait\fR()
- or
- \fIpthread_cond_timedwait\fR()
- have associated with the condition variable during their waits;
- however, if predictable scheduling behavior is required, then that
- mutex shall be locked by the thread calling
- \fIpthread_cond_broadcast\fR()
- or
- \fIpthread_cond_signal\fR().
- .P
- The
- \fIpthread_cond_broadcast\fR()
- and
- \fIpthread_cond_signal\fR()
- functions shall have no effect if there are no threads currently
- blocked on
- .IR cond .
- .P
- The behavior is undefined if the value specified by the
- .IR cond
- argument to
- \fIpthread_cond_broadcast\fR()
- or
- \fIpthread_cond_signal\fR()
- does not refer to an initialized condition variable.
- .SH "RETURN VALUE"
- If successful, the
- \fIpthread_cond_broadcast\fR()
- and
- \fIpthread_cond_signal\fR()
- functions shall return zero; otherwise, an error number shall be
- returned to indicate the error.
- .SH ERRORS
- These functions shall not return an error code of
- .BR [EINTR] .
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- The
- \fIpthread_cond_broadcast\fR()
- function is used whenever the shared-variable state has been changed in
- a way that more than one thread can proceed with its task. Consider a
- single producer/multiple consumer problem, where the producer can
- insert multiple items on a list that is accessed one item at a time by
- the consumers. By calling the
- \fIpthread_cond_broadcast\fR()
- function, the producer would notify all consumers that might be
- waiting, and thereby the application would receive more throughput on a
- multi-processor. In addition,
- \fIpthread_cond_broadcast\fR()
- makes it easier to implement a read-write lock. The
- \fIpthread_cond_broadcast\fR()
- function is needed in order to wake up all waiting readers when a
- writer releases its lock. Finally, the two-phase commit algorithm can
- use this broadcast function to notify all clients of an impending
- transaction commit.
- .P
- It is not safe to use the
- \fIpthread_cond_signal\fR()
- function in a signal handler that is invoked asynchronously. Even if
- it were safe, there would still be a race between the test of the
- Boolean
- \fIpthread_cond_wait\fR()
- that could not be efficiently eliminated.
- .P
- Mutexes and condition variables are thus not suitable for releasing a
- waiting thread by signaling from code running in a signal handler.
- .SH RATIONALE
- If an implementation detects that the value specified by the
- .IR cond
- argument to
- \fIpthread_cond_broadcast\fR()
- or
- \fIpthread_cond_signal\fR()
- does not refer to an initialized condition variable, it is recommended
- that the function should fail and report an
- .BR [EINVAL]
- error.
- .SS "Multiple Awakenings by Condition Signal"
- .P
- On a multi-processor, it may be impossible for an implementation of
- \fIpthread_cond_signal\fR()
- to avoid the unblocking of more than one thread blocked on a condition
- variable. For example, consider the following partial implementation
- of
- \fIpthread_cond_wait\fR()
- and
- \fIpthread_cond_signal\fR(),
- executed by two threads in the order given. One thread is trying to
- wait on the condition variable, another is concurrently executing
- \fIpthread_cond_signal\fR(),
- while a third thread is already waiting.
- .sp
- .RS 4
- .nf
- pthread_cond_wait(mutex, cond):
- value = cond->value; /* 1 */
- pthread_mutex_unlock(mutex); /* 2 */
- pthread_mutex_lock(cond->mutex); /* 10 */
- if (value == cond->value) { /* 11 */
- me->next_cond = cond->waiter;
- cond->waiter = me;
- pthread_mutex_unlock(cond->mutex);
- unable_to_run(me);
- } else
- pthread_mutex_unlock(cond->mutex); /* 12 */
- pthread_mutex_lock(mutex); /* 13 */
- .P
- pthread_cond_signal(cond):
- pthread_mutex_lock(cond->mutex); /* 3 */
- cond->value++; /* 4 */
- if (cond->waiter) { /* 5 */
- sleeper = cond->waiter; /* 6 */
- cond->waiter = sleeper->next_cond; /* 7 */
- able_to_run(sleeper); /* 8 */
- }
- pthread_mutex_unlock(cond->mutex); /* 9 */
- .fi
- .P
- .RE
- .P
- The effect is that more than one thread can return from its call to
- \fIpthread_cond_wait\fR()
- or
- \fIpthread_cond_timedwait\fR()
- as a result of one call to
- \fIpthread_cond_signal\fR().
- This effect is called ``spurious wakeup''.
- Note that the situation is self-correcting in that the number of
- threads that are so awakened is finite; for example, the next thread to
- call
- \fIpthread_cond_wait\fR()
- after the sequence of events above blocks.
- .P
- While this problem could be resolved, the loss of efficiency for a
- fringe condition that occurs only rarely is unacceptable, especially
- given that one has to check the predicate associated with a condition
- variable anyway. Correcting this problem would unnecessarily reduce
- the degree of concurrency in this basic building block for all
- higher-level synchronization operations.
- .P
- An added benefit of allowing spurious wakeups is that applications are
- forced to code a predicate-testing-loop around the condition wait.
- This also makes the application tolerate superfluous condition
- broadcasts or signals on the same condition variable that may be coded
- in some other part of the application. The resulting applications are
- thus more robust. Therefore, POSIX.1\(hy2008 explicitly documents that
- spurious wakeups may occur.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIpthread_cond_destroy\fR\^(\|)",
- .IR "\fIpthread_cond_timedwait\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 4.12" ", " "Memory Synchronization",
- .IR "\fB<pthread.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .