pthread_cond_signal or pthread_cond_broadcast Subroutine

Purpose

Unblocks one or more threads blocked on a condition.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

int pthread_cond_signal (condition) pthread_cond_t *condition;

int pthread_cond_broadcast (condition) pthread_cond_t *condition;

Description

These subroutines unblock one or more threads blocked on the condition specified by condition. The pthread_cond_signal subroutine unblocks at least one blocked thread, while the pthread_cond_broadcast subroutine unblocks all the blocked threads.

If more than one thread is blocked on a condition variable, the scheduling policy determines the order in which threads are unblocked. When each thread unblocked as a result of a pthread_cond_signal or pthread_cond_broadcast returns from its call to pthread_cond_wait or pthread_cond_timedwait, the thread owns the mutex with which it called pthread_cond_waitor pthread_cond_timedwait. The thread(s) that are unblocked contend for the mutex according to the scheduling policy (if applicable), and as if each had called pthread_mutex_lock.

The pthread_cond_signal or pthread_cond_broadcast functions may be called by a thread whether or not it currently owns the mutex that threads calling pthread_cond_wait or pthread_cond_timedwait have associated with the condition variable during their waits; however, if predictable scheduling behavior is required, then that mutex is locked by the thread calling pthread_cond_signal or pthread_cond_broadcast.

If no thread is blocked on the condition, the subroutine succeeds, but the signalling of the condition is not held. The next thread calling pthread_cond_wait will be blocked.

Note: The pthread.h header file must be the first included file of each source file using the threads library. Otherwise, the -D_THREAD_SAFE compilation flag should be used, or the cc_r compiler used. In this case, the flag is automatically set.

Parameters

Item	Description
condition	Specifies the condition to signal.

Return Values

Upon successful completion, 0 is returned. Otherwise, an error code is returned.

Error Code

The pthread_cond_signal and pthread_cond_broadcast subroutines are unsuccessful if the following is true:

Item	Description
EINVAL	The condition parameter is not valid.