logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

pthread_cond_broadcast.3p (8118B)


  1. '\" et
  2. .TH PTHREAD_COND_BROADCAST "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pthread_cond_broadcast,
  12. pthread_cond_signal
  13. \(em broadcast or signal a condition
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_cond_broadcast(pthread_cond_t *\fIcond\fP);
  20. int pthread_cond_signal(pthread_cond_t *\fIcond\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. These functions shall unblock threads blocked on a condition variable.
  24. .P
  25. The
  26. \fIpthread_cond_broadcast\fR()
  27. function shall unblock all threads currently blocked on the specified
  28. condition variable
  29. .IR cond .
  30. .P
  31. The
  32. \fIpthread_cond_signal\fR()
  33. function shall unblock at least one of the threads that are blocked
  34. on the specified condition variable
  35. .IR cond
  36. (if any threads are blocked on
  37. .IR cond ).
  38. .P
  39. If more than one thread is blocked on a condition variable, the
  40. scheduling policy shall determine the order in which threads are
  41. unblocked. When each thread unblocked as a result of a
  42. \fIpthread_cond_broadcast\fR()
  43. or
  44. \fIpthread_cond_signal\fR()
  45. returns from its call to
  46. \fIpthread_cond_wait\fR()
  47. or
  48. \fIpthread_cond_timedwait\fR(),
  49. the thread shall own the mutex with which it called
  50. \fIpthread_cond_wait\fR()
  51. or
  52. \fIpthread_cond_timedwait\fR().
  53. The thread(s) that are unblocked shall contend for the mutex according
  54. to the scheduling policy (if applicable), and as if each had called
  55. \fIpthread_mutex_lock\fR().
  56. .P
  57. The
  58. \fIpthread_cond_broadcast\fR()
  59. or
  60. \fIpthread_cond_signal\fR()
  61. functions may be called by a thread whether or not it currently owns
  62. the mutex that threads calling
  63. \fIpthread_cond_wait\fR()
  64. or
  65. \fIpthread_cond_timedwait\fR()
  66. have associated with the condition variable during their waits;
  67. however, if predictable scheduling behavior is required, then that
  68. mutex shall be locked by the thread calling
  69. \fIpthread_cond_broadcast\fR()
  70. or
  71. \fIpthread_cond_signal\fR().
  72. .P
  73. The
  74. \fIpthread_cond_broadcast\fR()
  75. and
  76. \fIpthread_cond_signal\fR()
  77. functions shall have no effect if there are no threads currently
  78. blocked on
  79. .IR cond .
  80. .P
  81. The behavior is undefined if the value specified by the
  82. .IR cond
  83. argument to
  84. \fIpthread_cond_broadcast\fR()
  85. or
  86. \fIpthread_cond_signal\fR()
  87. does not refer to an initialized condition variable.
  88. .SH "RETURN VALUE"
  89. If successful, the
  90. \fIpthread_cond_broadcast\fR()
  91. and
  92. \fIpthread_cond_signal\fR()
  93. functions shall return zero; otherwise, an error number shall be
  94. returned to indicate the error.
  95. .SH ERRORS
  96. These functions shall not return an error code of
  97. .BR [EINTR] .
  98. .LP
  99. .IR "The following sections are informative."
  100. .SH EXAMPLES
  101. None.
  102. .SH "APPLICATION USAGE"
  103. The
  104. \fIpthread_cond_broadcast\fR()
  105. function is used whenever the shared-variable state has been changed in
  106. a way that more than one thread can proceed with its task. Consider a
  107. single producer/multiple consumer problem, where the producer can
  108. insert multiple items on a list that is accessed one item at a time by
  109. the consumers. By calling the
  110. \fIpthread_cond_broadcast\fR()
  111. function, the producer would notify all consumers that might be
  112. waiting, and thereby the application would receive more throughput on a
  113. multi-processor. In addition,
  114. \fIpthread_cond_broadcast\fR()
  115. makes it easier to implement a read-write lock. The
  116. \fIpthread_cond_broadcast\fR()
  117. function is needed in order to wake up all waiting readers when a
  118. writer releases its lock. Finally, the two-phase commit algorithm can
  119. use this broadcast function to notify all clients of an impending
  120. transaction commit.
  121. .P
  122. It is not safe to use the
  123. \fIpthread_cond_signal\fR()
  124. function in a signal handler that is invoked asynchronously. Even if
  125. it were safe, there would still be a race between the test of the
  126. Boolean
  127. \fIpthread_cond_wait\fR()
  128. that could not be efficiently eliminated.
  129. .P
  130. Mutexes and condition variables are thus not suitable for releasing a
  131. waiting thread by signaling from code running in a signal handler.
  132. .SH RATIONALE
  133. If an implementation detects that the value specified by the
  134. .IR cond
  135. argument to
  136. \fIpthread_cond_broadcast\fR()
  137. or
  138. \fIpthread_cond_signal\fR()
  139. does not refer to an initialized condition variable, it is recommended
  140. that the function should fail and report an
  141. .BR [EINVAL]
  142. error.
  143. .SS "Multiple Awakenings by Condition Signal"
  144. .P
  145. On a multi-processor, it may be impossible for an implementation of
  146. \fIpthread_cond_signal\fR()
  147. to avoid the unblocking of more than one thread blocked on a condition
  148. variable. For example, consider the following partial implementation
  149. of
  150. \fIpthread_cond_wait\fR()
  151. and
  152. \fIpthread_cond_signal\fR(),
  153. executed by two threads in the order given. One thread is trying to
  154. wait on the condition variable, another is concurrently executing
  155. \fIpthread_cond_signal\fR(),
  156. while a third thread is already waiting.
  157. .sp
  158. .RS 4
  159. .nf
  160. pthread_cond_wait(mutex, cond):
  161. value = cond->value; /* 1 */
  162. pthread_mutex_unlock(mutex); /* 2 */
  163. pthread_mutex_lock(cond->mutex); /* 10 */
  164. if (value == cond->value) { /* 11 */
  165. me->next_cond = cond->waiter;
  166. cond->waiter = me;
  167. pthread_mutex_unlock(cond->mutex);
  168. unable_to_run(me);
  169. } else
  170. pthread_mutex_unlock(cond->mutex); /* 12 */
  171. pthread_mutex_lock(mutex); /* 13 */
  172. .P
  173. pthread_cond_signal(cond):
  174. pthread_mutex_lock(cond->mutex); /* 3 */
  175. cond->value++; /* 4 */
  176. if (cond->waiter) { /* 5 */
  177. sleeper = cond->waiter; /* 6 */
  178. cond->waiter = sleeper->next_cond; /* 7 */
  179. able_to_run(sleeper); /* 8 */
  180. }
  181. pthread_mutex_unlock(cond->mutex); /* 9 */
  182. .fi
  183. .P
  184. .RE
  185. .P
  186. The effect is that more than one thread can return from its call to
  187. \fIpthread_cond_wait\fR()
  188. or
  189. \fIpthread_cond_timedwait\fR()
  190. as a result of one call to
  191. \fIpthread_cond_signal\fR().
  192. This effect is called ``spurious wakeup''.
  193. Note that the situation is self-correcting in that the number of
  194. threads that are so awakened is finite; for example, the next thread to
  195. call
  196. \fIpthread_cond_wait\fR()
  197. after the sequence of events above blocks.
  198. .P
  199. While this problem could be resolved, the loss of efficiency for a
  200. fringe condition that occurs only rarely is unacceptable, especially
  201. given that one has to check the predicate associated with a condition
  202. variable anyway. Correcting this problem would unnecessarily reduce
  203. the degree of concurrency in this basic building block for all
  204. higher-level synchronization operations.
  205. .P
  206. An added benefit of allowing spurious wakeups is that applications are
  207. forced to code a predicate-testing-loop around the condition wait.
  208. This also makes the application tolerate superfluous condition
  209. broadcasts or signals on the same condition variable that may be coded
  210. in some other part of the application. The resulting applications are
  211. thus more robust. Therefore, POSIX.1\(hy2008 explicitly documents that
  212. spurious wakeups may occur.
  213. .SH "FUTURE DIRECTIONS"
  214. None.
  215. .SH "SEE ALSO"
  216. .IR "\fIpthread_cond_destroy\fR\^(\|)",
  217. .IR "\fIpthread_cond_timedwait\fR\^(\|)"
  218. .P
  219. The Base Definitions volume of POSIX.1\(hy2017,
  220. .IR "Section 4.12" ", " "Memory Synchronization",
  221. .IR "\fB<pthread.h>\fP"
  222. .\"
  223. .SH COPYRIGHT
  224. Portions of this text are reprinted and reproduced in electronic form
  225. from IEEE Std 1003.1-2017, Standard for Information Technology
  226. -- Portable Operating System Interface (POSIX), The Open Group Base
  227. Specifications Issue 7, 2018 Edition,
  228. Copyright (C) 2018 by the Institute of
  229. Electrical and Electronics Engineers, Inc and The Open Group.
  230. In the event of any discrepancy between this version and the original IEEE and
  231. The Open Group Standard, the original IEEE and The Open Group Standard
  232. is the referee document. The original Standard can be obtained online at
  233. http://www.opengroup.org/unix/online.html .
  234. .PP
  235. Any typographical or formatting errors that appear
  236. in this page are most likely
  237. to have been introduced during the conversion of the source files to
  238. man page format. To report such errors, see
  239. https://www.kernel.org/doc/man-pages/reporting_bugs.html .