Embedded Multicore Building Blocks V1.0.0
Typedefs | Functions
Condition Variable

Condition variables for thread synchronization. More...

Typedefs

typedef opaque_type embb_condition_t
 Opaque type representing a condition variable. More...
 

Functions

int embb_condition_init (embb_condition_t *condition_var)
 Initializes a condition variable. More...
 
int embb_condition_notify_one (embb_condition_t *condition_var)
 Wakes up one thread waiting for condition_var. More...
 
int embb_condition_notify_all (embb_condition_t *condition_var)
 Wakes up all threads waiting for condition_var. More...
 
int embb_condition_wait (embb_condition_t *condition_var, embb_mutex_t *mutex)
 Unlocks mutex and waits until the thread is woken up. More...
 
int embb_condition_wait_until (embb_condition_t *condition_var, embb_mutex_t *mutex, const embb_time_t *time)
 Unlocks mutex and waits until the thread is woken up or time has passed. More...
 
int embb_condition_wait_for (embb_condition_t *condition_var, embb_mutex_t *mutex, const embb_duration_t *duration)
 Unlocks mutex and waits until the thread is woken up or duration has passed. More...
 
int embb_condition_destroy (embb_condition_t *condition_var)
 Destroys condition_var and frees used memory. More...
 

Detailed Description

Condition variables for thread synchronization.

Provides an abstraction from platform-specific condition variable implementations. Condition variables can be waited for with timeouts using relative durations and absolute time points.

Typedef Documentation

typedef opaque_type embb_condition_t

Opaque type representing a condition variable.

Function Documentation

int embb_condition_init ( embb_condition_t condition_var)

Initializes a condition variable.

Dynamic memory allocation
Potentially allocates dynamic memory
Precondition
condition_var is not initialized
Postcondition
If successful, condition_var is initialized
Returns
EMBB_SUCCESS if successful
EMBB_ERROR otherwise
Concurrency
Not thread-safe
See also
embb_condition_destroy()
Parameters
[out]condition_varPointer to condition variable
int embb_condition_notify_one ( embb_condition_t condition_var)

Wakes up one thread waiting for condition_var.

Precondition
condition_var is initialized
Returns
EMBB_SUCCESS if signaling was successful
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_condition_notify_all(), embb_condition_wait(), embb_condition_wait_until(), embb_condition_wait_for()
Parameters
[in,out]condition_varPointer to condition variable
int embb_condition_notify_all ( embb_condition_t condition_var)

Wakes up all threads waiting for condition_var.

Precondition
condition_var is initialized
Returns
EMBB_SUCCESS if broadcast was successful
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_condition_notify_one(), embb_condition_wait(), embb_condition_wait_until(), embb_condition_wait_for()
Parameters
[in,out]condition_varPointer to condition variable
int embb_condition_wait ( embb_condition_t condition_var,
embb_mutex_t mutex 
)

Unlocks mutex and waits until the thread is woken up.

Precondition
condition_var is initialized and mutex is locked by calling thread
Postcondition
If successful, mutex is locked by the calling thread
Returns
EMBB_SUCCESS if successful
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_condition_notify_one(), embb_condition_notify_all(), embb_condition_wait_until(), embb_condition_wait_for()
Note
It is strongly recommended checking the condition in a loop in order to deal with spurious wakeups and situations where another thread has locked the mutex between notification and wakeup.
Parameters
[in,out]condition_varPointer to condition variable
[in,out]mutexPointer to mutex
int embb_condition_wait_until ( embb_condition_t condition_var,
embb_mutex_t mutex,
const embb_time_t time 
)

Unlocks mutex and waits until the thread is woken up or time has passed.

Precondition
condition_var is initialized and mutex is locked by calling thread
Postcondition
If successful, mutex is locked by the calling thread
Returns
EMBB_SUCCESS if successful
EMBB_TIMEDOUT if mutex could not be locked until the specified point of time
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_condition_notify_one(), embb_condition_notify_all(), embb_condition_wait(), embb_condition_wait_for()
Note
It is strongly recommended checking the condition in a loop in order to deal with spurious wakeups and situations where another thread has locked the mutex between notification and wakeup.
Parameters
[in,out]condition_varPointer to condition variable
[in,out]mutexPointer to mutex
[in]timePoint of time until the thread waits
int embb_condition_wait_for ( embb_condition_t condition_var,
embb_mutex_t mutex,
const embb_duration_t duration 
)

Unlocks mutex and waits until the thread is woken up or duration has passed.

Precondition
condition_var is initialized and mutex is locked by calling thread
Postcondition
If successful, mutex is locked by the calling thread
Returns
EMBB_SUCCESS if successful
EMBB_TIMEDOUT if mutex could not be locked within the specified time span
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_condition_notify_one(), embb_condition_notify_all(), embb_condition_wait(), embb_condition_wait_until()
Note
It is strongly recommended checking the condition in a loop in order to deal with spurious wakeups and situations where another thread has locked the mutex between notification and wakeup.
Parameters
[in,out]condition_varPointer to condition variable
[in,out]mutexPointer to mutex
[in]durationDuration in microseconds the thread waits
int embb_condition_destroy ( embb_condition_t condition_var)

Destroys condition_var and frees used memory.

Precondition
condition_var is initialized and no thread is waiting for it using embb_condition_wait(), embb_condition_wait_for(), or embb_condition_wait_until().
Postcondition
condition_var is uninitialized
Returns
EMBB_SUCCESS if destruction of condition variable was successful
EMBB_ERROR otherwise
Concurrency
Not thread-safe
See also
embb_condition_init()
Parameters
[in]condition_varPointer to condition variable