cnd_broadcast, cnd_destroy, cnd_init, cnd_signal, cnd_timedwait and cnd_wait Subroutine

Purpose

The cnd_broadcast subroutine unblocks all the threads that are blocked by using the cond condition variable.

The cnd_destroy subroutine releases all the resources that are used by the cond condition variable.

The cnd_init subroutine creates a cond condition variable.

The cnd_signal subroutine unblocks one of the threads that is blocked by using the condition that is specified by the cond parameter.

The cnd_timedwait subroutine unblocks the condition that is specified by the cond condition variable after a specified time indicated by the ts parameter.

The cnd_wait subroutine blocks the condition that is specified by the cond condition variable until it gets a signal from the cnd_signal or cnd_broadcast subroutines.

Library

Standard C library (libc.a)

Syntax

#include <threads.h>
int cnd_broadcast (cnd_t * cond);

void cnd_destroy (cnd_t * cond);

int cnd_init (cnd_t * cond);

int cnd_signal (cnd_t * cond);

int cnd_timedwait (cnd_t * restrict cond, mtx_t * restrict mtx, const struct timespec * restrict ts);

int cnd_wait (cnd_t * cond, mtx_t * mtx);

Description

The cnd_broadcast subroutine unblocks all the threads that are blocked by using the condition variable specified by the cond parameter during the function call.

If no threads are blocked by using the condition variable specified by the cond parameter during the function call, the function is inactive.

The cnd_destroy subroutine releases all the resources that are used by the condition variable specified by the cond parameter.

The cnd_destroy subroutine requires that threads are not blocked while waiting for the condition variable specified by the cond parameter.

The cnd_init subroutine creates a condition variable. If the subroutine is successful, it sets the variable specified by the cond parameter to a value that uniquely identifies the newly created condition variable.

A thread that calls the cnd_wait subroutine on a newly created condition variable is blocked.

The cnd_signal subroutine unblocks one of the threads that are blocked by using the condition variable specified by the cond parameter during the function call. If threads are not blocked by using the condition variable during the function call, the function is inactive and returns success.

The cnd_timedwait and cnd_wait subroutine automatically unlocks and locks the mutex specified by the mtx parameter and tries to block until the condition variable pointed to by the cond is signaled by a call to the cnd_signal or cnd_broadcast subroutine, or until the TIME_UTC based calendar time is specified by the value of the ts parameter.

When the calling thread is unblocked, it locks the variable specified by the mtx parameter before it returns a value. The cnd_timedwait subroutine requires that the mutex specified by the mtx parameter is locked by the calling thread.

Parameters

Item	Description
cond	Specifies the condition variable to be created or released, depending on the type of the subroutine in which the parameter is referenced.
mtx	Specifies the mutex to be unlocked.
ts	Specifies the maximum time for the condition variable to be blocked.

Return Values

The cnd_broadcast, cnd_signal, and cnd_wait subroutine returns the value of thrd_success on success, and returns the value of thrd_error if the request cannot be processed.

The cnd_destroy subroutine returns no value.

The cnd_init subroutine returns the value of thrd_success on success.

The cnd_init subroutine returns the value of thrd_nomem if memory cannot be allocated for the newly created condition, and returns the value of thrd_error if the request cannot be processed.

The cnd_timedwait subroutine returns the value of thrd_success on success, or returns the value of thrd_timedout if the time specified in the call is reached without acquiring the requested resource, and returns the value of thrd_error if the request cannot be processed.

Files

The threads.h file defines standard macros, data types, and subroutines.