plibsys
Typedefs | Functions
pcondvariable.h File Reference

Condition variable. More...

#include <pmacros.h>
#include <ptypes.h>
#include <pmutex.h>
Include dependency graph for pcondvariable.h:

Go to the source code of this file.

Typedefs

typedef typedefP_BEGIN_DECLS struct PCondVariable_ PCondVariable
 Condition variable opaque data structure. More...
 

Functions

P_LIB_API PCondVariablep_cond_variable_new (void)
 Creates a new PCondVariable. More...
 
P_LIB_API void p_cond_variable_free (PCondVariable *cond)
 Frees PCondVariable structure. More...
 
P_LIB_API pboolean p_cond_variable_wait (PCondVariable *cond, PMutex *mutex)
 Waits for a signal on a given condition variable. More...
 
P_LIB_API pboolean p_cond_variable_signal (PCondVariable *cond)
 Emitts a signal on a given condition variable for one waiting thread. More...
 
P_LIB_API pboolean p_cond_variable_broadcast (PCondVariable *cond)
 Emitts a signal on a given condition variable for all the waiting threads. More...
 

Detailed Description

Condition variable.

Author
Alexander Saprykin

A condition variable is an inter-thread synchronization primitive, often used in the classical 'producers-consumers' concurrent data access models.

The main idea is to notify waiting thread(s) for some events before they can enter a critical section. Hence the name of the primitive: a thread enters the critical section upon an accomplished condition. Compare it with a mutex where the thread enters the critical section as soon as no one holds a lock.

Several threads can be notified at once, but only one of them can enter the critical section. The order of the threads in that case is implementation dependent.

As the thread enters the critical section upon a condition it still requires a mutex to guard its code against concurrent access from other threads. The mutex provided in pair with a condition variable will be automatically locked on the condition, the thread should unlock it explicitly after leaving the critical section. That mutex is unlocked while waiting for the condition and should be locked prior calling the condition waiting routine.

The waiting thread behavior: create a new condition variable with p_cond_variable_new(), create and lock a mutex before a critical section and wait for a signal from another thread on this condition variable using p_cond_variable_wait().

The signaling thread behavior: upon reaching event time emit a signal with p_cond_variable_signal() to wake up a single waiting thread or p_cond_variable_broadcast() to wake up all the waiting threads.

After emitting the signal only the one thread will get the locked mutex back to continue executing the critical section.

It is implementation dependent whether a thread will receive a missed signal (when a notification from the one thread was emitted prior another thread has been called for waiting), so do not rely on this behavior.

Typedef Documentation

◆ PCondVariable

typedef typedefP_BEGIN_DECLS struct PCondVariable_ PCondVariable

Condition variable opaque data structure.

Function Documentation

◆ p_cond_variable_broadcast()

P_LIB_API pboolean p_cond_variable_broadcast ( PCondVariable cond)

Emitts a signal on a given condition variable for all the waiting threads.

Parameters
condCondition variable to emit the signal on.
Returns
TRUE on success, FALSE otherwise.
Since
0.0.1

After emitting the signal all the threads waiting for it will be waken up.

◆ p_cond_variable_free()

P_LIB_API void p_cond_variable_free ( PCondVariable cond)

Frees PCondVariable structure.

Parameters
condCondtion variable to free.
Since
0.0.1

◆ p_cond_variable_new()

P_LIB_API PCondVariable* p_cond_variable_new ( void  )

Creates a new PCondVariable.

Returns
Pointer to a newly created PCondVariable structure, or NULL if failed.
Since
0.0.1

◆ p_cond_variable_signal()

P_LIB_API pboolean p_cond_variable_signal ( PCondVariable cond)

Emitts a signal on a given condition variable for one waiting thread.

Parameters
condCondition variable to emit the signal on.
Returns
TRUE on success, FALSE otherwise.
Since
0.0.1

After emitting the signal only the one thread waiting for it will be waken up. Do not rely on a queue concept for waiting threads. Though the implementation is intended to be much close to a queue, it's not fairly enough. Due that any thread can be waken up, even if it has just called p_cond_variable_wait() while there are other waiting threads.

◆ p_cond_variable_wait()

P_LIB_API pboolean p_cond_variable_wait ( PCondVariable cond,
PMutex mutex 
)

Waits for a signal on a given condition variable.

Parameters
condCondition variable to wait on.
mutexLocked mutex which will remain locked after waiting.
Returns
TRUE on success, FALSE otherwise.
Since
0.0.1

The calling thread will sleep until the signal on cond arrived.