diff options
Diffstat (limited to 'upstream/archlinux/man3p/pthread_cond_destroy.3p')
| -rw-r--r-- | upstream/archlinux/man3p/pthread_cond_destroy.3p | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/pthread_cond_destroy.3p b/upstream/archlinux/man3p/pthread_cond_destroy.3p new file mode 100644 index 00000000..50bf6560 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_cond_destroy.3p @@ -0,0 +1,228 @@ +'\" et +.TH PTHREAD_COND_DESTROY "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_destroy, +pthread_cond_init +\(em destroy and initialize condition variables +.SH SYNOPSIS +.LP +.nf +#include <pthread.h> +.P +int pthread_cond_destroy(pthread_cond_t *\fIcond\fP); +int pthread_cond_init(pthread_cond_t *restrict \fIcond\fP, + const pthread_condattr_t *restrict \fIattr\fP); +pthread_cond_t \fIcond\fP = PTHREAD_COND_INITIALIZER; +.fi +.SH DESCRIPTION +The +\fIpthread_cond_destroy\fR() +function shall destroy the given condition variable specified by +.IR cond ; +the object becomes, in effect, uninitialized. An implementation may +cause +\fIpthread_cond_destroy\fR() +to set the object referenced by +.IR cond +to an invalid value. A destroyed condition variable object can be +reinitialized using +\fIpthread_cond_init\fR(); +the results of otherwise referencing the object after it has been +destroyed are undefined. +.P +It shall be safe to destroy an initialized condition variable upon which +no threads are currently blocked. Attempting to destroy a condition +variable upon which other threads are currently blocked results in +undefined behavior. +.P +The +\fIpthread_cond_init\fR() +function shall initialize the condition variable referenced by +.IR cond +with attributes referenced by +.IR attr . +If +.IR attr +is NULL, the default condition variable attributes shall be used; the +effect is the same as passing the address of a default condition +variable attributes object. Upon successful initialization, the state +of the condition variable shall become initialized. +.P +See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. +.P +Attempting to initialize an already initialized condition variable +results in undefined behavior. +.P +In cases where default condition variable attributes are appropriate, +the macro PTHREAD_COND_INITIALIZER can be used to initialize condition +variables. The effect shall be equivalent to dynamic initialization by +a call to +\fIpthread_cond_init\fR() +with parameter +.IR attr +specified as NULL, except that no error checks are performed. +.P +The behavior is undefined if the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +does not refer to an initialized condition variable. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_cond_init\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_cond_destroy\fR() +and +\fIpthread_cond_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_cond_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources (other than memory) to +initialize another condition variable. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the condition variable. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +A condition variable can be destroyed immediately after all the threads +that are blocked on it are awakened. For example, consider the +following code: +.sp +.RS 4 +.nf + +struct list { + pthread_mutex_t lm; + ... +} +.P +struct elt { + key k; + int busy; + pthread_cond_t notbusy; + ... +} +.P +/* Find a list element and reserve it. */ +struct elt * +list_find(struct list *lp, key k) +{ + struct elt *ep; +.P + pthread_mutex_lock(&lp->lm); + while ((ep = find_elt(l, k) != NULL) && ep->busy) + pthread_cond_wait(&ep->notbusy, &lp->lm); + if (ep != NULL) + ep->busy = 1; + pthread_mutex_unlock(&lp->lm); + return(ep); +} +.P +delete_elt(struct list *lp, struct elt *ep) +{ + pthread_mutex_lock(&lp->lm); + assert(ep->busy); + ... remove ep from list ... + ep->busy = 0; /* Paranoid. */ +(A) pthread_cond_broadcast(&ep->notbusy); + pthread_mutex_unlock(&lp->lm); +(B) pthread_cond_destroy(&ep->notbusy); + free(ep); +} +.fi +.P +.RE +.P +In this example, the condition variable and its list element may be +freed (line B) immediately after all threads waiting for it are +awakened (line A), since the mutex and the code ensure that no other +thread can touch the element to be deleted. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +does not refer to an initialized condition variable, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +or +\fIpthread_cond_init\fR() +refers to a condition variable that is in use (for example, in a +\fIpthread_cond_wait\fR() +call) by another thread, or detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_init\fR() +refers to an already initialized condition variable, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_cond_init\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See also +.IR "\fIpthread_mutex_destroy\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_broadcast\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.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 . |