int
pthread_cond_broadcast (
pthread_cond_t *cond);
cond
Condition variable upon which the threads (to be awakened) are waiting.
This routine unblocks all threads waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, so that it might be possible for one or more waiting threads to proceed. The threads that are unblocked shall contend for the mutex according to their respective scheduling policies (if applicable).Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:If only one of the threads waiting on a condition variable may be able to proceed, but any single thread can proceed, then use pthread_cond_signal() instead.
Whether the associated mutex is locked or unlocked, you can still call this routine. However, if predictable scheduling behavior is required, that mutex should then be locked by the thread calling the pthread_cond_broadcast() routine.
If no threads are waiting on the specified condition variable, this routine takes no action. The broadcast does not propagate to the next condition variable wait.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by cond is invalid. |
Destroys a condition variable.
C Binding #include <pthread.h>pthread_cond_destroy(
cond );
Argument Data Type Access cond opaque pthread_cond_t write
int
pthread_cond_destroy (
pthread_cond_t *cond);
cond
Condition variable to be destroyed.
This routine destroys the condition variable specified by cond. This effectively uninitializes the condition variable. Call this routine when a condition variable will no longer be referenced. Destroying a condition variable allows DECthreads to reclaim internal memory associated with the condition variable.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:It is 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 blocked results in unpredictable behavior.
The results of this routine are unpredictable, if the condition variable specified in cond does not exist or is not initialized.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by cond is invalid. |
[EBUSY] |
The object being referenced by
cond is being referenced by another thread that is currently
executing
pthread_cond_wait() or pthread_cond_timedwait() on the condition variable specified in cond. |
Obtains the object name from a condition variable object.
C Binding #include <pthread.h>pthread_cond_getname_np(
cond ,
name ,
len );
Argument Data Type Access cond opaque pthread_cond_t read name char write len opaque size_t read
int
pthread_cond_getname_np (
pthread_cond_t *cond,
char *name,
size_t len);
cond
Address of the condition variable object whose object name is to be obtained.name
Location to store the obtained object name.len
Length in bytes of buffer at the location specified by name.
This routine copies the object name from the condition variable object specified by the cond argument to the buffer at the location specified by the name argument. Before calling this routine, your program must allocate the buffer indicated by name.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The object name is a C language string and provides an identifier that is meaningful to a person debugging a DECthreads-based multithreaded application. The maximum number of characters in the object name is 31.
If the specified condition variable object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by cond is invalid. |
Initializes a condition variable.
C Binding #include <pthread.h>pthread_cond_init(
cond ,
attr );
Argument Data Type Access cond opaque pthread_cond_t write attr opaque pthread_condattr_t read
int
pthread_cond_init (
pthread_cond_t *cond,
const pthread_condattr_t *attr);
cond
Condition variable to be initialized.attr
Condition variable attributes object that defines the characteristics of the condition variable to be initialized.
This routine initializes the condition variable cond with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error, the condition variable is not initialized, and the contents of cond are undefined. Possible return values are as follows:A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to data that is shared among threads; a condition variable allows threads to wait for that data to enter a defined state.
Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread terminates.
Use the DECthreads macro PTHREAD_COND_INITIALIZER to initialize statically allocated condition variables to the default condition variable attributes. To call this macro, enter:
pthread_cond_t condition = PTHREAD_COND_INITIALIZERWhen statically initialized, a condition variable should not also be initialized using pthread_cond_init(). Also, a statically initialized condition variable need not be destroyed using pthread_cond_destroy().
Under certain circumstances it might be impossible to wait upon a statically initialized condition variable when the process virtual address space (or some other memory limit) is nearly exhausted. In such a case pthread_cond_wait() or pthread_cond_timedwait() can return [ENOMEM]. To avoid this possibility, initialize critical condition variables using pthread_cond_init().
Return | Description |
---|---|
0 | Successful completion. |
[EAGAIN] |
The system lacks the necessary resources to initialize another
condition variable, or
The system-imposed limit on the total number of condition variables under execution by a single user is exceeded. |
[EBUSY] | The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable. |
[EINVAL] | The value specified by attr is invalid. |
[ENOMEM] | Insufficient memory exists to initialize the condition variable. |
Changes the object name in a condition variable object.
C Binding #include <pthread.h>pthread_cond_setname_np(
cond ,
name ,
mbz );
Argument Data Type Access cond opaque pthread_cond_t write name char read mbz void read
int
pthread_cond_setname_np (
pthread_cond_t *cond,
const char *name,
void *mbz);
cond
Address of the condition variable object whose object name is to be changed.name
Object name value to copy into the condition variable object.mbz
(Must be zero) Argument for use by DECthreads.
This routine changes the object name in the condition variable object specified by the cond argument to the value specified by the name argument. To set a new condition variable object's object name, call this routine immediately after initializing the condition variable object.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The object name is a C language string and provides an identifier that is meaningful to a person debugging a DECthreads-based multithreaded application. The maximum number of characters in the object name is 31.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by cond is invalid, or the length in characters of name exceeds 31. |
[ENOMEM] | Insufficient memory exists to create a copy of the object name string. |
Wakes at least one thread that is waiting on the specified condition variable.
C Binding #include <pthread.h>pthread_cond_signal(
cond );
Argument Data Type Access cond opaque pthread_cond_t modify
int
pthread_cond_signal (
pthread_cond_t *cond);
cond
Condition variable to be signaled.
This routine unblocks at least one thread waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, thus it might be possible for one of the waiting threads to proceed. In general, only one thread will be released.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:If no threads are waiting on the specified condition variable, this routine takes no action. The signal does not propagate to the next condition variable wait.
This routine should be called when any thread waiting on the specified condition variable might find its predicate true, but only one thread should proceed. If more than one thread can proceed, or if any thread would not be able to proceed, then you must use pthread_cond_broadcast().
The scheduling policy determines which thread is awakened. For policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.
You can call this routine even when the associated mutex is locked. However, if predictable scheduling behavior is required, then that mutex should be locked by the thread calling pthread_cond_signal().
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by cond is invalid. |
Wakes one thread that is waiting on the specified condition variable (called from interrupt level only).
C Binding #include <pthread.h>pthread_cond_signal_int_np(
cond );
Argument Data Type Access cond opaque pthread_cond_t modify
int
pthread_cond_signal_int_np(
pthread_cond_t *cond);
cond
Condition variable to be signaled.
This routine wakes one thread waiting on the specified condition variable. It can only be called from a software interrupt handler routine (such as from a DIGITAL UNIX signal handler or OpenVMS AST). Calling this routine implies that it might be possible for a single waiting thread to proceed.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The scheduling policies of the waiting threads determine which thread is awakened. For policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.
This routine does not cause a thread blocked on a condition variable to resume execution immediately. A thread resumes execution at some time after the interrupt handler routine returns.
You can call this routine regardless of whether the associated mutex is locked (by some other thread). Never lock a mutex from an interrupt handler routine.
Note
This routine allows you to signal a thread from a software interrupt handler. Do not call this routine from noninterrupt code. To signal a thread from the normal noninterrupt level, use pthread_cond_signal().
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by cond is invalid. |
Causes a thread to wait for the specified condition variable to be signaled or broadcasted, such that it will awake after a specified period of time.
C Binding #include <pthread.h>pthread_cond_timedwait(
cond ,
mutex ,
abstime );
Argument Data Type Access cond opaque pthread_cond_t modify mutex opaque pthread_mutex_t modify abstime structure timespec read
int
pthread_cond_timedwait (
pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *abstime);
cond
Condition variable that the calling thread waits on.mutex
Mutex associated with the condition variable specified in cond.abstime
Absolute time at which the wait expires, if the condition has not been signaled or broadcasted. See the pthread_get_expiration_np() routine, which is used to obtain a value for this argument.The abstime argument is specified in Universal Coordinated Time (UTC). In the UTC-based model, time is represented as seconds since the Epoch. The Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1st, 1970 UTC. Seconds since the Epoch is a value interpreted as the number of seconds between a specified time and the Epoch.
This routine causes a thread to wait until one of the following occurs:
- The specified condition variable is signaled or broadcasted.
- The current system clock time is greater than or equal to the time specified by the abstime argument.
This routine is identical to pthread_cond_wait(), except that this routine can return before a condition variable is signaled or broadcasted; specifically, when the specified time expires. For more information, see the pthread_cond_wait() description.
This routine atomically releases the mutex and causes the calling thread to wait on the condition. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the timer expires or when the wait is satisfied as a result of some thread calling pthread_cond_signal() or pthread_cond_broadcast(), the mutex is reacquired before returning to the caller.
If the current time equals or exceeds the expiration time, this routine returns immediately, releasing and reacquiring the mutex. It might cause the calling thread to yield (see the sched_yield() description. Your code should check the return status whenever this routine returns and take the appropriate action. Otherwise, waiting on the condition variable can become a nonblocking loop.
Call this routine after you lock the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex.
Return Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] |
The value specified by
cond,
mutex, or
abstime is invalid, or:
Different mutexes are supplied for concurrent
The mutex was not owned by the calling thread at the time of the call. |
[ETIMEDOUT] | The time specified by abstime expired. |
[ENOMEM] | DECthreads cannot acquire memory needed to block using a statically initialized condition variable. |
Causes a thread to wait for the specified condition variable to be signaled or broadcasted.
C Binding #include <pthread.h>pthread_cond_wait(
cond ,
mutex );
Argument Data Type Access cond opaque pthread_cond_t modify mutex opaque pthread_mutex_t modify
int
pthread_cond_wait (
pthread_cond_t *cond,
pthread_mutex_t *mutex);
cond
Condition variable that the calling thread waits on.mutex
Mutex associated with the condition variable specified in cond.
This routine causes a thread to wait for the specified condition variable to be signaled or broadcasted. Each condition corresponds to one or more Boolean relations, called a predicate, based on shared data. The calling thread waits for the data to reach a particular state for the predicate to become true. However, the return from this routine does not imply anything about the value of the predicate and it should be reevaluated upon return. Condition variables are discussed in Chapter 2 and Chapter 3.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:Call this routine after you have locked the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex.
This routine atomically releases the mutex and causes the calling thread to wait on the condition. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the wait is satisfied as a result of some thread calling pthread_cond_signal() or pthread_cond_broadcast(), the mutex is reacquired before returning to the caller.
A thread that changes the state of storage protected by the mutex in such a way that a predicate associated with a condition variable might now be true, must call either pthread_cond_signal() or pthread_cond_broadcast() for that condition variable. If neither call is made, any thread waiting on the condition variable continues to wait.
This routine might (with low probability) return when the condition variable has not been signaled or broadcasted. When this occurs, the mutex is reacquired before the routine returns. To handle this type of situation, enclose each call to this routine in a loop that checks the predicate. The loop provides documentation of your intent and protects against these spurious wakeups, while also allowing correct behavior even if another thread consumes the desired state before the awakened thread runs.
It is illegal for threads to wait on the same condition variable by specifying different mutexes.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] |
The value specified by
cond or
mutex is invalid, or:
Different mutexes are supplied for concurrent
The mutex was not owned by the calling thread at the time of the call. |
[ENOMEM] | DECthreads cannot acquire memory needed to block using a statically initialized condition variable. |
Creates a thread.
C Binding #include <pthread.h>pthread_create(
thread ,
attr ,
start _routine,
arg );
Argument Data Type Access thread opaque pthread_t write attr opaque pthread_attr_t read start_routine procedure read arg user_arg read