KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Macros | Typedefs | Functions
cond.h File Reference

Condition variables. More...

#include <sys/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
 Condition variable. More...
 

Macros

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

Typedefs

typedef struct condvar condvar_t
 Condition variable. More...
 

Functions

condvar_tcond_create () __attribute__((deprecated))
 Allocate a new condition variable. More...
 
int cond_init (condvar_t *cv)
 Initialize a condition variable. More...
 
int cond_destroy (condvar_t *cv)
 Free a condition variable. More...
 
int cond_wait (condvar_t *cv, mutex_t *m)
 Wait on a condition variable. More...
 
int cond_wait_timed (condvar_t *cv, mutex_t *m, int timeout)
 Wait on a condition variable with a timeout. More...
 
int cond_signal (condvar_t *cv)
 Signal a single thread waiting on the condition variable. More...
 
int cond_broadcast (condvar_t *cv)
 Signal all threads waiting on the condition variable. More...
 

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):

Meanwhile, the thread updating the condition works as follows:

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
Dan Potter

Macro Definition Documentation

#define COND_INITIALIZER   { 1, 0 }

Initializer for a transient condvar.

Typedef Documentation

typedef struct condvar condvar_t

Condition variable.

There are no public members of this structure for you to actually do anything with in your code, so don't try.

Function Documentation

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
cvThe condition to signal
Return values
0On success
-1On error, errno will be set as appropriate
Error Conditions:
EINVAL - the condvar was not initialized
condvar_t* cond_create ( )

Allocate a new condition variable.

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

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
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
0On success (no error conditions currently defined)
int cond_init ( condvar_t cv)

Initialize a condition variable.

This function initializes a new condition variable for use.

Parameters
cvThe condition variable to initialize
Return values
0On success
-1On error, sets errno as appropriate
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
cvThe condition to signal
Return values
0On success
-1On error, errno will be set as appropriate
Error Conditions:
EINVAL - the condvar was not initialized
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
cvThe condition to wait on
mThe associated mutex
Return values
0On success
-1On 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
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
cvThe condition to wait on
mThe associated mutex
timeoutThe number of milliseconds before timeout
Return values
0On success
-1On 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