diff options
Diffstat (limited to 'man3/pthread_cond_init.3')
| -rw-r--r-- | man3/pthread_cond_init.3 | 264 |
1 files changed, 0 insertions, 264 deletions
diff --git a/man3/pthread_cond_init.3 b/man3/pthread_cond_init.3 deleted file mode 100644 index 8472d2eb5..000000000 --- a/man3/pthread_cond_init.3 +++ /dev/null @@ -1,264 +0,0 @@ -.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> -.\" Copyright 2023, Alejandro Colomar <alx@kernel.org> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH pthread_cond_init 3 (date) "Linux man-pages (unreleased)" -. -. -.SH NAME -pthread_cond_init, -pthread_cond_signal, -pthread_cond_broadcast, -pthread_cond_wait, -pthread_cond_timedwait, -pthread_cond_destroy -\- -operations on conditions -. -. -.SH SYNOPSIS -.B #include <pthread.h> -.P -.BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;" -.P -.BI "int pthread_cond_init(pthread_cond_t *" cond ", pthread_condattr_t *" cond_attr ");" -.BI "int pthread_cond_signal(pthread_cond_t *" cond ");" -.BI "int pthread_cond_broadcast(pthread_cond_t *" cond ");" -.BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ");" -.BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ", const struct timespec *" abstime ");" -.BI "int pthread_cond_destroy(pthread_cond_t *" cond ");" -. -. -.SH DESCRIPTION -A condition (short for ``condition variable'') -is a synchronization device that allows threads -to suspend execution and relinquish the processors -until some predicate on shared data is satisfied. -The basic operations on conditions are: -signal the condition (when the predicate becomes true), -and wait for the condition, -suspending the thread execution until another thread signals the condition. -.P -A condition variable must always be associated with a mutex, -to avoid the race condition where -a thread prepares to wait on a condition variable -and another thread signals the condition -just before the first thread actually waits on it. -.P -\fBpthread_cond_init\fP initializes the condition variable \fIcond\fP, -using the condition attributes specified in \fIcond_attr\fP, -or default attributes if \fIcond_attr\fP is \fBNULL\fP. -The LinuxThreads implementation supports no attributes for conditions, -hence the \fIcond_attr\fP parameter is actually ignored. -.P -Variables of type \fBpthread_cond_t\fP can also be initialized statically, -using the constant \fBPTHREAD_COND_INITIALIZER\fP. -.P -\fBpthread_cond_signal\fP restarts one of the threads that -are waiting on the condition variable \fIcond\fP. -If no threads are waiting on \fIcond\fP, -nothing happens. -If several threads are waiting on \fIcond\fP, -exactly one is restarted, -but it is not specified which. -.P -\fBpthread_cond_broadcast\fP restarts all the threads that -are waiting on the condition variable \fIcond\fP. -Nothing happens if no threads are waiting on \fIcond\fP. -.P -\fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP -(as per \fBpthread_unlock_mutex\fP) -and waits for the condition variable \fIcond\fP to be signaled. -The thread execution is suspended and does not consume any CPU time -until the condition variable is signaled. -The \fImutex\fP must be locked by the calling thread -on entrance to \fBpthread_cond_wait\fP. -Before returning to the calling thread, -\fBpthread_cond_wait\fP re-acquires \fImutex\fP -(as per \fBpthread_lock_mutex\fP). -.P -Unlocking the mutex and suspending on the condition variable is done atomically. -Thus, -if all threads always acquire the mutex before signaling the condition, -this guarantees that the condition cannot be signaled (and thus ignored) -between the time a thread locks the mutex -and the time it waits on the condition variable. -.P -\fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP -and waits on \fIcond\fP, -as \fBpthread_cond_wait\fP does, -but it also bounds the duration of the wait. -If \fIcond\fP has not been signaled -within the amount of time specified by \fIabstime\fP, -the mutex \fImutex\fP is re-acquired -and \fBpthread_cond_timedwait\fP returns the error \fBETIMEDOUT\fP. -The \fIabstime\fP parameter specifies an absolute time, -with the same origin as \fBtime\fP(2) and \fBgettimeofday\fP(2): -an \fIabstime\fP of 0 -corresponds to 00:00:00 GMT, January 1, 1970. -.P -\fBpthread_cond_destroy\fP destroys a condition variable, -freeing the resources it might hold. -No threads must be waiting on the condition variable -on entrance to \fBpthread_cond_destroy\fP. -In the LinuxThreads implementation, -no resources are associated with condition variables, -thus \fBpthread_cond_destroy\fP actually does nothing -except checking that the condition has no waiting threads. -. -. -.SH CANCELLATION -\fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP -are cancelation points. -If a thread is cancelled while suspended in one of these functions, -the thread immediately resumes execution, -then locks again the \fImutex\fP -argument to \fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP, -and finally executes the cancelation. -Consequently, -cleanup handlers are assured that \fImutex\fP is locked -when they are called. -. -. -.SH "ASYNC-SIGNAL SAFETY" -The condition functions are not async-signal safe, -and should not be called from a signal handler. -In particular, -calling \fBpthread_cond_signal\fP or \fBpthread_cond_broadcast\fP -from a signal handler -may deadlock the calling thread. -. -. -.SH "RETURN VALUE" -All condition variable functions return 0 on success -and a non-zero error code on error. -. -. -.SH ERRORS -\fBpthread_cond_init\fP, -\fBpthread_cond_signal\fP, -\fBpthread_cond_broadcast\fP, -and \fBpthread_cond_wait\fP -never return an error code. -.P -The \fBpthread_cond_timedwait\fP function returns -the following error codes on error: -.RS -.TP -\fBETIMEDOUT\fP -The condition variable was not signaled -until the timeout specified by \fIabstime\fP. -.TP -\fBEINTR\fP -\fBpthread_cond_timedwait\fP was interrupted by a signal. -.RE -.P -The \fBpthread_cond_destroy\fP function returns -the following error code on error: -.RS -.TP -\fBEBUSY\fP -Some threads are currently waiting on \fIcond\fP. -.RE -. -. -.SH "SEE ALSO" -\fBpthread_condattr_init\fP(3), -\fBpthread_mutex_lock\fP(3), -\fBpthread_mutex_unlock\fP(3), -\fBgettimeofday\fP(2), -\fBnanosleep\fP(2). -. -. -.SH EXAMPLE -Consider two shared variables \fIx\fP and \fIy\fP, -protected by the mutex \fImut\fP, -and a condition variable \fIcond\fP -that is to be signaled -whenever \fIx\fP becomes greater than \fIy\fP. -.P -.RS -.ft 3 -.nf -.sp -int x,y; -pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; -pthread_cond_t cond = PTHREAD_COND_INITIALIZER; -.ft -.P -.RE -.fi -.P -Waiting until \fIx\fP is greater than \fIy\fP is performed as follows: -.P -.RS -.ft 3 -.nf -.sp -pthread_mutex_lock(&mut); -while (x <= y) { - pthread_cond_wait(&cond, &mut); -} -/* operate on x and y */ -pthread_mutex_unlock(&mut); -.ft -.P -.RE -.fi -.P -Modifications on \fIx\fP and \fIy\fP -that may cause \fIx\fP to become greater than \fIy\fP -should signal the condition if needed: -.P -.RS -.ft 3 -.nf -.sp -pthread_mutex_lock(&mut); -/* modify x and y */ -if (x > y) pthread_cond_broadcast(&cond); -pthread_mutex_unlock(&mut); -.ft -.P -.RE -.fi -.P -If it can be proved that at most one waiting thread needs to be waken up -(for instance, -if there are only two threads communicating through \fIx\fP and \fIy\fP), -\fBpthread_cond_signal\fP can be used as -a slightly more efficient alternative to \fBpthread_cond_broadcast\fP. -In doubt, -use \fBpthread_cond_broadcast\fP. -.P -To wait for \fIx\fP to become greater than \fIy\fP -with a timeout of 5 seconds, -do: -.P -.RS -.ft 3 -.nf -.sp -struct timeval now; -struct timespec timeout; -int retcode; -\& -pthread_mutex_lock(&mut); -gettimeofday(&now); -timeout.tv_sec = now.tv_sec + 5; -timeout.tv_nsec = now.tv_usec * 1000; -retcode = 0; -while (x <= y && retcode != ETIMEDOUT) { - retcode = pthread_cond_timedwait(&cond, &mut, &timeout); -} -if (retcode == ETIMEDOUT) { - /* timeout occurred */ -} else { - /* operate on x and y */ -} -pthread_mutex_unlock(&mut); -.ft -.P -.RE -.fi |