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_destroy.3p (6738B)


  1. '\" et
  2. .TH PTHREAD_COND_DESTROY "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_destroy,
  12. pthread_cond_init
  13. \(em destroy and initialize condition variables
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_cond_destroy(pthread_cond_t *\fIcond\fP);
  20. int pthread_cond_init(pthread_cond_t *restrict \fIcond\fP,
  21. const pthread_condattr_t *restrict \fIattr\fP);
  22. pthread_cond_t \fIcond\fP = PTHREAD_COND_INITIALIZER;
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIpthread_cond_destroy\fR()
  27. function shall destroy the given condition variable specified by
  28. .IR cond ;
  29. the object becomes, in effect, uninitialized. An implementation may
  30. cause
  31. \fIpthread_cond_destroy\fR()
  32. to set the object referenced by
  33. .IR cond
  34. to an invalid value. A destroyed condition variable object can be
  35. reinitialized using
  36. \fIpthread_cond_init\fR();
  37. the results of otherwise referencing the object after it has been
  38. destroyed are undefined.
  39. .P
  40. It shall be safe to destroy an initialized condition variable upon which
  41. no threads are currently blocked. Attempting to destroy a condition
  42. variable upon which other threads are currently blocked results in
  43. undefined behavior.
  44. .P
  45. The
  46. \fIpthread_cond_init\fR()
  47. function shall initialize the condition variable referenced by
  48. .IR cond
  49. with attributes referenced by
  50. .IR attr .
  51. If
  52. .IR attr
  53. is NULL, the default condition variable attributes shall be used; the
  54. effect is the same as passing the address of a default condition
  55. variable attributes object. Upon successful initialization, the state
  56. of the condition variable shall become initialized.
  57. .P
  58. See
  59. .IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings"
  60. for further requirements.
  61. .P
  62. Attempting to initialize an already initialized condition variable
  63. results in undefined behavior.
  64. .P
  65. In cases where default condition variable attributes are appropriate,
  66. the macro PTHREAD_COND_INITIALIZER can be used to initialize condition
  67. variables. The effect shall be equivalent to dynamic initialization by
  68. a call to
  69. \fIpthread_cond_init\fR()
  70. with parameter
  71. .IR attr
  72. specified as NULL, except that no error checks are performed.
  73. .P
  74. The behavior is undefined if the value specified by the
  75. .IR cond
  76. argument to
  77. \fIpthread_cond_destroy\fR()
  78. does not refer to an initialized condition variable.
  79. .P
  80. The behavior is undefined if the value specified by the
  81. .IR attr
  82. argument to
  83. \fIpthread_cond_init\fR()
  84. does not refer to an initialized condition variable attributes object.
  85. .SH "RETURN VALUE"
  86. If successful, the
  87. \fIpthread_cond_destroy\fR()
  88. and
  89. \fIpthread_cond_init\fR()
  90. functions shall return zero; otherwise, an error number shall be
  91. returned to indicate the error.
  92. .SH ERRORS
  93. The
  94. \fIpthread_cond_init\fR()
  95. function shall fail if:
  96. .TP
  97. .BR EAGAIN
  98. The system lacked the necessary resources (other than memory) to
  99. initialize another condition variable.
  100. .TP
  101. .BR ENOMEM
  102. Insufficient memory exists to initialize the condition variable.
  103. .P
  104. These functions shall not return an error code of
  105. .BR [EINTR] .
  106. .LP
  107. .IR "The following sections are informative."
  108. .SH EXAMPLES
  109. A condition variable can be destroyed immediately after all the threads
  110. that are blocked on it are awakened. For example, consider the
  111. following code:
  112. .sp
  113. .RS 4
  114. .nf
  115. struct list {
  116. pthread_mutex_t lm;
  117. ...
  118. }
  119. .P
  120. struct elt {
  121. key k;
  122. int busy;
  123. pthread_cond_t notbusy;
  124. ...
  125. }
  126. .P
  127. /* Find a list element and reserve it. */
  128. struct elt *
  129. list_find(struct list *lp, key k)
  130. {
  131. struct elt *ep;
  132. .P
  133. pthread_mutex_lock(&lp->lm);
  134. while ((ep = find_elt(l, k) != NULL) && ep->busy)
  135. pthread_cond_wait(&ep->notbusy, &lp->lm);
  136. if (ep != NULL)
  137. ep->busy = 1;
  138. pthread_mutex_unlock(&lp->lm);
  139. return(ep);
  140. }
  141. .P
  142. delete_elt(struct list *lp, struct elt *ep)
  143. {
  144. pthread_mutex_lock(&lp->lm);
  145. assert(ep->busy);
  146. ... remove ep from list ...
  147. ep->busy = 0; /* Paranoid. */
  148. (A) pthread_cond_broadcast(&ep->notbusy);
  149. pthread_mutex_unlock(&lp->lm);
  150. (B) pthread_cond_destroy(&ep->notbusy);
  151. free(ep);
  152. }
  153. .fi
  154. .P
  155. .RE
  156. .P
  157. In this example, the condition variable and its list element may be
  158. freed (line B) immediately after all threads waiting for it are
  159. awakened (line A), since the mutex and the code ensure that no other
  160. thread can touch the element to be deleted.
  161. .SH "APPLICATION USAGE"
  162. None.
  163. .SH RATIONALE
  164. If an implementation detects that the value specified by the
  165. .IR cond
  166. argument to
  167. \fIpthread_cond_destroy\fR()
  168. does not refer to an initialized condition variable, it is
  169. recommended that the function should fail and report an
  170. .BR [EINVAL]
  171. error.
  172. .P
  173. If an implementation detects that the value specified by the
  174. .IR cond
  175. argument to
  176. \fIpthread_cond_destroy\fR()
  177. or
  178. \fIpthread_cond_init\fR()
  179. refers to a condition variable that is in use (for example, in a
  180. \fIpthread_cond_wait\fR()
  181. call) by another thread, or detects that the value specified by the
  182. .IR cond
  183. argument to
  184. \fIpthread_cond_init\fR()
  185. refers to an already initialized condition variable, it is recommended
  186. that the function should fail and report an
  187. .BR [EBUSY]
  188. error.
  189. .P
  190. If an implementation detects that the value specified by the
  191. .IR attr
  192. argument to
  193. \fIpthread_cond_init\fR()
  194. does not refer to an initialized condition variable attributes object,
  195. it is recommended that the function should fail and report an
  196. .BR [EINVAL]
  197. error.
  198. .P
  199. See also
  200. .IR "\fIpthread_mutex_destroy\fR\^(\|)".
  201. .SH "FUTURE DIRECTIONS"
  202. None.
  203. .SH "SEE ALSO"
  204. .IR "\fIpthread_cond_broadcast\fR\^(\|)",
  205. .IR "\fIpthread_cond_timedwait\fR\^(\|)",
  206. .IR "\fIpthread_mutex_destroy\fR\^(\|)"
  207. .P
  208. The Base Definitions volume of POSIX.1\(hy2017,
  209. .IR "\fB<pthread.h>\fP"
  210. .\"
  211. .SH COPYRIGHT
  212. Portions of this text are reprinted and reproduced in electronic form
  213. from IEEE Std 1003.1-2017, Standard for Information Technology
  214. -- Portable Operating System Interface (POSIX), The Open Group Base
  215. Specifications Issue 7, 2018 Edition,
  216. Copyright (C) 2018 by the Institute of
  217. Electrical and Electronics Engineers, Inc and The Open Group.
  218. In the event of any discrepancy between this version and the original IEEE and
  219. The Open Group Standard, the original IEEE and The Open Group Standard
  220. is the referee document. The original Standard can be obtained online at
  221. http://www.opengroup.org/unix/online.html .
  222. .PP
  223. Any typographical or formatting errors that appear
  224. in this page are most likely
  225. to have been introduced during the conversion of the source files to
  226. man page format. To report such errors, see
  227. https://www.kernel.org/doc/man-pages/reporting_bugs.html .