cond.h File Reference

Condition variables. More...

#include <kos/cdefs.h>
#include <arch/types.h>
#include <kos/thread.h>
#include <kos/mutex.h>

Go to the source code of this file.

Data Structures
struct	condvar_t
	Condition variable. More...

Macros
#define	COND_INITIALIZER   { 0, 0 }
	Initializer for a transient condvar.

Functions
condvar_t *	cond_create () __depr("Use cond_init or COND_INITIALIZER.")
	Allocate a new condition variable.
int	cond_init (condvar_t *cv)
	Initialize a condition variable.
int	cond_destroy (condvar_t *cv)
	Free a condition variable.
int	cond_wait (condvar_t *cv, mutex_t *m)
	Wait on a condition variable.
int	cond_wait_timed (condvar_t *cv, mutex_t *m, int timeout)
	Wait on a condition variable with a timeout.
int	cond_signal (condvar_t *cv)
	Signal a single thread waiting on the condition variable.
int	cond_broadcast (condvar_t *cv)
	Signal all threads waiting on the condition variable.

Detailed Description

Condition variables.

This file contains the definition of a Condition Variable. Condition Variables (or condvars for short) are used with a mutex to act as a lock and checkpoint pair for threads.

Basically, things work as follows (for the thread doing work):

• The associated mutex is locked.
• A predicate is checked to see if it is safe to do something.
• If it is not safe, you call cond_wait(), which releases the mutex.
• When cond_wait() returns, the mutex is reacquired, and work can go on.
• Update any predicates so that we know that the work is done, and unlock the mutex.

Meanwhile, the thread updating the condition works as follows:

• Lock the mutex associated with the condvar.
• Produce work to be done.
• Call cond_signal() (with the associated mutex still locked), so that any threads waiting on the condvar will know they can continue on when the mutex is released, also update any predicates that say whether work can be done.
• Unlock the mutex so that worker threads can acquire the mutex and do whatever work needs to be done.

Condition variables can be quite useful when used properly, and provide a fairly easy way to wait for work to be ready to be done.

Condition variables should never be used with mutexes that are of the type MUTEX_TYPE_RECURSIVE. The lock will only be released once by the wait function, and thus you will end up deadlocking if you use a recursive mutex that has been locked more than once.

Author

Megan Potter

Macro Definition Documentation

COND_INITIALIZER

#define COND_INITIALIZER   { 0, 0 }

Initializer for a transient condvar.

Function Documentation

cond_broadcast()

int cond_broadcast

(

condvar_t *

cv

)

Signal all threads waiting on the condition variable.

This function will wake up all threads that are waiting on the condition. The calling thread should be holding the associated mutex or recursive lock before calling this to guarantee sane behavior.

Parameters

cv	The condition to signal

Return values

0	On success
-1	On error, errno will be set as appropriate

Error Conditions:

EINVAL - the condvar was not initialized

cond_create()

condvar_t * cond_create

(

)

Allocate a new condition variable.

This function allocates and initializes a new condition variable for use.

Deprecated

This function is formally deprecated and should not be used in new code. Instead you should use either the static initializer or the cond_init() function.

Returns

The created condvar on success. NULL is returned on failure and errno is set as appropriate.

Error Conditions:

ENOMEM - out of memory

cond_destroy()

int cond_destroy

(

condvar_t *

cv

)

Free a condition variable.

This function frees a condition variable, releasing all memory associated with it (but not with the mutex that is associated with it). This will also wake all threads waiting on the condition.

Return values

0	On success (no error conditions currently defined)

cond_init()

int cond_init

(

condvar_t *

cv

)

Initialize a condition variable.

This function initializes a new condition variable for use.

Parameters

cv	The condition variable to initialize

Return values

0	On success
-1	On error, sets errno as appropriate

cond_signal()

int cond_signal

(

condvar_t *

cv

)

Signal a single thread waiting on the condition variable.

This function will wake up a single thread that is waiting on the condition. The calling thread should be holding the associated mutex or recursive lock before calling this to guarantee sane behavior.

Parameters

cv	The condition to signal

Return values

0	On success
-1	On error, errno will be set as appropriate

Error Conditions:

EINVAL - the condvar was not initialized

cond_wait()

int cond_wait	(	condvar_t *	cv,
		mutex_t *	m )

Wait on a condition variable.

This function will wait on the condition variable, unlocking the mutex and putting the calling thread to sleep as one atomic operation. The wait in this function has no timeout, and will sleep forever if the condition is not signalled.

The mutex will be locked and owned by the calling thread on return, regardless of whether it is a successful or error return.

Parameters

cv	The condition to wait on
m	The associated mutex

Return values

0	On success
-1	On error, sets errno as appropriate

Error Conditions:

EPERM - called inside an interrupt
EINVAL - the condvar was not initialized
EINVAL - the mutex is not initialized or not locked
ENOTRECOVERABLE - the condvar was destroyed while waiting

cond_wait_timed()

int cond_wait_timed	(	condvar_t *	cv,
		mutex_t *	m,
		int	timeout )

Wait on a condition variable with a timeout.

This function will wait on the condition variable, unlocking the mutex and putting the calling thread to sleep as one atomic operation. If the timeout elapses before the condition is signalled, this function will return error. If a timeout of 0 is given, the call is equivalent to cond_wait() (there is no timeout).

The mutex will be locked and owned by the calling thread on return, regardless of whether it is a successful or error return.

Parameters

cv	The condition to wait on
m	The associated mutex
timeout	The number of milliseconds before timeout

Return values

0	On success
-1	On error, sets errno as appropriate

Error Conditions:

EPERM - called inside an interrupt
ETIMEDOUT - timed out
EINVAL - the condvar was not initialized
EINVAL - the mutex is not initialized or not locked
ENOTRECOVERABLE - the condvar was destroyed while waiting