KallistiOS
##version##
|
Condition variables. More...
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_t * | cond_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... | |
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.
#define COND_INITIALIZER { 1, 0 } |
Initializer for a transient condvar.
Condition variable.
There are no public members of this structure for you to actually do anything with in your code, so don't try.
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.
cv | The condition to signal |
0 | On success |
-1 | On error, errno will be set as appropriate |
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.
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.
0 | On 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.
cv | The condition variable to initialize |
0 | On success |
-1 | On 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.
cv | The condition to signal |
0 | On success |
-1 | On error, errno will be set as appropriate |
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.
cv | The condition to wait on |
m | The associated mutex |
0 | On success |
-1 | On error, sets errno as appropriate |
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.
cv | The condition to wait on |
m | The associated mutex |
timeout | The number of milliseconds before timeout |
0 | On success |
-1 | On error, sets errno as appropriate |