pcondvariable.h File Reference

Condition variable. More...

#include <pmacros.h>
#include <ptypes.h>
#include <pmutex.h>

Go to the source code of this file.

Typedefs
typedef struct PCondVariable_	PCondVariable
	Condition variable opaque data structure.

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

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.

Definition in file pcondvariable.h.

Typedef Documentation

PCondVariable

typedef struct PCondVariable_ PCondVariable

Condition variable opaque data structure.

Definition at line 82 of file pcondvariable.h.

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

cond	Condition 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

cond	Condtion 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

cond	Condition 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

cond	Condition variable to wait on.
mutex	Locked 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.