From 7523c7c4d75652f67cd31cb123e1268790394c8b Mon Sep 17 00:00:00 2001 From: rpj Date: Fri, 6 May 2005 07:27:10 +0000 Subject: '' --- manual/pthread_cond_init.html | 313 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 manual/pthread_cond_init.html (limited to 'manual/pthread_cond_init.html') diff --git a/manual/pthread_cond_init.html b/manual/pthread_cond_init.html new file mode 100644 index 0000000..937e490 --- /dev/null +++ b/manual/pthread_cond_init.html @@ -0,0 +1,313 @@ + + + + + PTHREAD_COND(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, +pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait - +operations on conditions +

+

Synopsis

+

#include <pthread.h> +

+

pthread_cond_t cond = PTHREAD_COND_INITIALIZER; +

+

int pthread_cond_init(pthread_cond_t *cond, +pthread_condattr_t *cond_attr); +

+

int pthread_cond_signal(pthread_cond_t *cond); +

+

int pthread_cond_broadcast(pthread_cond_t *cond); +

+

int pthread_cond_wait(pthread_cond_t *cond, +pthread_mutex_t *mutex); +

+

int pthread_cond_timedwait(pthread_cond_t *cond, +pthread_mutex_t *mutex, const struct timespec +*abstime); +

+

int pthread_cond_destroy(pthread_cond_t *cond); +

+

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. +

+

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. +

+

pthread_cond_init initializes the condition variable cond, +using the condition attributes specified in cond_attr, or +default attributes if cond_attr is NULL. +

+

Variables of type pthread_cond_t can also be initialized +statically, using the constant PTHREAD_COND_INITIALIZER. In +the Pthreads-w32 implementation, an application should still +call pthread_cond_destroy at some point to ensure that any +resources consumed by the condition variable are released.

+

pthread_cond_signal restarts one of the threads that are +waiting on the condition variable cond. If no threads are +waiting on cond, nothing happens. If several threads are +waiting on cond, exactly one is restarted, but it is not +specified which. +

+

pthread_cond_broadcast restarts all the threads that are +waiting on the condition variable cond. Nothing happens if no +threads are waiting on cond. +

+

pthread_cond_wait atomically unlocks the mutex (as +per pthread_unlock_mutex) and waits for the condition variable +cond to be signalled. The thread execution is suspended and +does not consume any CPU time until the condition variable is +signalled. The mutex must be locked by the calling thread on +entrance to pthread_cond_wait. Before returning to the calling +thread, pthread_cond_wait re-acquires mutex (as per +pthread_lock_mutex). +

+

Unlocking the mutex and suspending on the condition variable is +done atomically. Thus, if all threads always acquire the mutex before +signalling the condition, this guarantees that the condition cannot +be signalled (and thus ignored) between the time a thread locks the +mutex and the time it waits on the condition variable. +

+

pthread_cond_timedwait atomically unlocks mutex and +waits on cond, as pthread_cond_wait does, but it also +bounds the duration of the wait. If cond has not been +signalled within the amount of time specified by abstime, the +mutex mutex is re-acquired and pthread_cond_timedwait +returns the error ETIMEDOUT. The abstime parameter +specifies an absolute time, with the same origin as time(2) +and gettimeofday(2). +

+

pthread_cond_destroy destroys a condition variable, freeing +the resources it might hold. No threads must be waiting on the +condition variable on entrance to pthread_cond_destroy.

+

Cancellation

+

pthread_cond_wait and pthread_cond_timedwait are +cancellation points. If a thread is cancelled while suspended in one +of these functions, the thread immediately resumes execution, then +locks again the mutex argument to pthread_cond_wait and +pthread_cond_timedwait, and finally executes the cancellation. +Consequently, cleanup handlers are assured that mutex is +locked when they are called. +

+

Async-signal Safety

+

The condition functions are not async-signal safe, and should not +be called from a signal handler. In particular, calling +pthread_cond_signal or pthread_cond_broadcast from a +signal handler may deadlock the calling thread. +

+

Return Value

+

All condition variable functions return 0 on success and a +non-zero error code on error. +

+

Errors

+

pthread_cond_init, pthread_cond_signal, +pthread_cond_broadcast, and pthread_cond_wait never +return an error code. +

+

The pthread_cond_init function returns the following error +codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+ ENOMEM +
+
+
+There was not enough memory to allocate the condition variable. +
+

The pthread_cond_signal function returns the following +error codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+
+

+The pthread_cond_broadcast function returns the following +error codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+
+

+The pthread_cond_wait function returns the following error +codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+ ENOMEM +
+
+
+There was not enough memory to allocate the statically initialised +condition variable. Statically initialised condition variables are +dynamically allocated by the first thread to wait on them.
+

The pthread_cond_timedwait function returns the following +error codes on error: +

+
+
+
EINVAL +
+
+

+The cond argument is invalid. +

+
+
+
ETIMEDOUT +
+ The condition variable was not signalled before the timeout + specified by abstime +
+ ENOMEM +
+
+
+There was not enough memory to allocate the statically initialised +condition variable. Statically initialised condition variables are +dynamically allocated by the first thread to wait on them. +
+

The pthread_cond_destroy function returns the following +error code on error: +

+
+
+
EINVAL +
+
+

+The cond argument is invalid. +

+
+
+
EBUSY +
+ Some threads are currently waiting on cond. +
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_condattr_init(3) +, pthread_mutex_lock(3) +, pthread_mutex_unlock(3) +, pthread_cancel(3). +

+

Example

+

Consider two shared variables x and y, protected by +the mutex mut, and a condition variable cond that is to +be signaled whenever x becomes greater than y. +

+
int x,y;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
+pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
+Waiting until x is greater than y is performed as +follows: +
+
pthread_mutex_lock(&mut);
+while (x <= y) {
+        pthread_cond_wait(&cond, &mut);
+}
+/* operate on x and y */
+pthread_mutex_unlock(&mut);
+Modifications on x and y that may cause x to +become greater than y should signal the condition if needed: +
+
pthread_mutex_lock(&mut);
+/* modify x and y */
+if (x > y) pthread_cond_broadcast(&cond);
+pthread_mutex_unlock(&mut);
+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 +x and y), pthread_cond_signal can be used as a +slightly more efficient alternative to pthread_cond_broadcast. +If in doubt, use pthread_cond_broadcast. +
+
To wait for x to +become greater than y with a timeout of 5 seconds, do: +
+
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);
+
+
+Table of Contents
+ + + -- cgit v1.2.3