summary refs log tree commit diff
path: root/linuxthreads/man/pthread_cond_init.man
diff options
context:
space:
mode:
Diffstat (limited to 'linuxthreads/man/pthread_cond_init.man')
-rw-r--r--linuxthreads/man/pthread_cond_init.man234
1 files changed, 0 insertions, 234 deletions
diff --git a/linuxthreads/man/pthread_cond_init.man b/linuxthreads/man/pthread_cond_init.man
deleted file mode 100644
index 4913062fd2..0000000000
--- a/linuxthreads/man/pthread_cond_init.man
+++ /dev/null
@@ -1,234 +0,0 @@
-.TH PTHREAD_COND 3 LinuxThreads
-
-.XREF pthread_cond_signal
-.XREF pthread_cond_broadcast
-.XREF pthread_cond_wait
-.XREF pthread_cond_timedwait
-.XREF pthread_cond_destroy
-
-.SH NAME
-pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait \- operations on conditions
-
-.SH 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);
-
-.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.
-
-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!. The LinuxThreads implementation supports no
-attributes for conditions, hence the |cond_attr| parameter is actually
-ignored.
-
-Variables of type !pthread_cond_t! can also be initialized
-statically, using the constant !PTHREAD_COND_INITIALIZER!.
-
-!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 signaled. The thread execution is suspended and does not consume
-any CPU time until the condition variable is signaled. 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
-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.
-
-!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 signaled 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): an |abstime| of 0
-corresponds to 00:00:00 GMT, January 1, 1970.
-
-!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!. In the LinuxThreads
-implementation, no resources are associated with condition variables,
-thus !pthread_cond_destroy! actually does nothing except checking that
-the condition has no waiting threads.
-
-.SH 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.
-
-.SH "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.
-
-.SH "RETURN VALUE"
-
-All condition variable functions return 0 on success and a non-zero
-error code on error.
-
-.SH ERRORS
-
-!pthread_cond_init!, !pthread_cond_signal!, !pthread_cond_broadcast!,
-and !pthread_cond_wait! never return an error code.
-
-The !pthread_cond_timedwait! function returns the following error codes
-on error:
-.RS
-.TP
-!ETIMEDOUT!
-the condition variable was not signaled until the timeout specified by
-|abstime|
-
-.TP
-!EINTR!
-!pthread_cond_timedwait! was interrupted by a signal
-.RE
-
-The !pthread_cond_destroy! function returns the following error code
-on error:
-.RS
-.TP
-!EBUSY!
-some threads are currently waiting on |cond|.
-.RE
-
-.SH AUTHOR
-Xavier Leroy <Xavier.Leroy@inria.fr>
-
-.SH "SEE ALSO"
-!pthread_condattr_init!(3),
-!pthread_mutex_lock!(3),
-!pthread_mutex_unlock!(3),
-!gettimeofday!(2),
-!nanosleep!(2).
-
-.SH 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|.
-
-.RS
-.ft 3
-.nf
-.sp
-int x,y;
-pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
-pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
-.ft
-.LP
-.RE
-.fi
-
-Waiting until |x| is greater than |y| is performed as follows:
-
-.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
-.LP
-.RE
-.fi
-
-Modifications on |x| and |y| that may cause |x| to become greater than
-|y| should signal the condition if needed:
-
-.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
-.LP
-.RE
-.fi
-
-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!. In doubt, use
-!pthread_cond_broadcast!.
-
-To wait for |x| to becomes greater than |y| with a timeout of 5
-seconds, do:
-
-.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
-.LP
-.RE
-.fi