Similar Synchronization Functions: Condition Variables

• Initializing a condition variable

• Destroying a condition variable

• Waiting for a condition

• Waiting for an absolute time

• Waiting for a time interval

• Unblocking one thread

• Unblocking all threads

Initialize a Condition Variable

Use cond_init(3C) to initialize the condition variable pointed to by cv.

cond_init Syntax

#include <thread.h>

int cond_init(cond_t *cv, int type, int arg);

The type can be one of the following values:

• USYNC_PROCESS. The condition variable can be used to synchronize threads in this process and other processes. arg is ignored.

• USYNC_THREAD The condition variable can be used to synchronize threads in this process only. arg is ignored.

Condition variables can also be initialized by allocation in zeroed memory, in which case a type of USYNC_THREAD is assumed.

Multiple threads must not initialize the same condition variable simultaneously. A condition variable must not be reinitialized while other threads might be using the condition variable.

For POSIX threads, see pthread_condattr_init Syntax .

Condition Variables With Intraprocess Scope

#include <thread.h>

cond_t cv;
int ret;

/* to be used within this process only */
ret = cond_init(cv, USYNC_THREAD, 0); 

Condition Variables With Interprocess Scope

#include <thread.h>

cond_t cv;
int ret;

/* to be used among all processes */
ret = cond_init(&cv, USYNC_PROCESS, 0); 

cond_init Return Values

cond_init() returns 0 if successful. When any of the following conditions is detected, cond_init() fails and returns the corresponding value.

EFAULT

Description: cv points to an illegal address.

EINVAL

Description: type is not a recognized type.

Destroying a Condition Variable

Use cond_destroy(3C) to destroy state that is associated with the condition variable pointed to by cv . The space for storing the condition variable is not freed. For POSIX threads, see pthread_condattr_destroy Syntax.

cond_destroy Syntax

#include <thread.h>

int cond_destroy(cond_t *cv);

cond_destroy Return Values

cond_destroy() returns 0 if successful. When any of the following conditions is detected, cond_destroy() fails and returns the corresponding value.

EFAULT

Description: cv points to an illegal address.

EBUSY

Description: The system detected an attempt to destroy an active condition variable.

Waiting for a Condition

Use cond_wait(3C) to atomically release the mutex pointed to by mp and cause the calling thread to block on the condition variable pointed to by cv. The blocked thread can be awakened by cond_signal(), cond_broadcast() , or when interrupted by delivery of a signal or a fork().

cond_wait() always returns with the mutex locked and owned by the calling thread, even when returning an error.

cond_wait Syntax

#include <thread.h>

int cond_wait(cond_t *cv, mutex_t *mp);

cond_wait Return Values

cond_wait() returns 0 if successful. When any of the following conditions is detected, cond_wait() fails and returns the corresponding value.

EFAULT

Description: cv points to an illegal address.

EINTR

Description: The wait was interrupted by a signal.

Wait for an Absolute Time

cond_timedwait(3C) is very similar to cond_wait(), except that cond_timedwait() does not block past the time of day specified by abstime . For POSIX threads, see pthread_cond_timedwait Syntax.

cond_timedwait Syntax

#include <thread.h>

int cond_timedwait(cond_t *cv, mutex_t *mp, timestruct_t abstime);

cond_timedwait() always returns with the mutex locked and owned by the calling thread, even when returning an error.

The cond_timedwait() function blocks until the condition is signaled or until the time of day specified by the last argument has passed. The timeout is specified as the time of day so the condition can be retested efficiently without recomputing the time-out value.

cond_timedwait Return Values

cond_timedwait() returns 0 if successful. When any of the following conditions is detected, cond_timedwait() fails and returns the corresponding value.

EFAULT

Description: cv points to an illegal address.

ETIME

Description: The time specified by abstime has expired.

EINVAL

Description: abstime is invalid.

Waiting for a Time Interval

cond_reltimedwait(3C) is very similar to cond_timedwait(), except for the value for the third argument. cond_reltimedwait() takes a relative time interval value in its third argument rather than an absolute time of day value. For POSIX threads, see the pthread_cond_reltimedwait_np(3C) man page.

cond_reltimedwait() always returns with the mutex locked and owned by the calling thread even when returning an error. The cond_reltimedwait() function blocks until the condition is signaled or until the time interval specified by the last argument has elapsed.

cond_reltimedwait Syntax

#include <thread.h>

int cond_reltimedwait(cond_t *cv, mutex_t *mp,
    timestruct_t reltime);

cond_reltimedwait Return Values

cond_reltimedwait() returns 0 if successful. When any of the following conditions is detected, cond_reltimedwait() fails and returns the corresponding value.

EFAULT

Description: cv points to an illegal address.

ETIME

Description: The time specified by reltime has expired.

Unblock One Thread

Use cond_signal(3C) to unblock one thread that is blocked on the condition variable pointed to by cv . If no threads are blocked on the condition variable, cond_signal() has no effect.

cond_signal Syntax

#include <thread.h>

int cond_signal(cond_t *cv);

cond_signal Return Values

cond_signal() returns 0 if successful. When the following condition is detected, cond_signal() fails and returns the corresponding value.

EFAULT

Description: cv points to an illegal address.

Unblock All Threads

Use cond_broadcast(3C) to unblock all threads that are blocked on the condition variable pointed to by cv. When no threads are blocked on the condition variable, then cond_broadcast() has no effect.

cond_broadcast Syntax

#include <thread.h>

int cond_broadcast(cond_t *cv);

cond_broadcast Return Values

cond_broadcast() returns 0 if successful. When the following condition is detected, cond_broadcast() fails and returns the corresponding value.

EFAULT

Description: cv points to an illegal address.