Description:

template<typename TDerived>
struct alib::threads::TCondition< TDerived >

This struct wraps C++ standard library types std::mutex and std::condition_variable. It allows one or more threads to sleep until any other thread satisfies a condition and wakes one or all threads up.

Abstract Template Type:

This class is an "abstract template type", which means that it invokes methods which are not declared and thus have to be declared by a type that derives from this class. The derived type needs to pass its own type name to template parameter TDerived.
With that, this type can cast its this-pointer to that type and access its interface. The derived type has to provide only one function member:

bool isConditionMet()

: This has to return true if the condition is fulfilled, otherwise false.

Acquisition Rules:: Before using one of the overloaded blocking sleep methods WaitForNotification, the object has to be locked by calling Acquire. Such acquirement is guaranteed to be held after the method returns.

: A notifying thread has to likewise acquire this object before calling either ReleaseAndNotify or ReleaseAndNotifyAll. However, as the method names indicate, with the return from the notification call, the internal mutex is released.

: Similar to class Lock, nested calls to the method Acquire are not allowed and constitute undefined behavior.

Usage Recipe:

Being an "abstract" type, the class is not designed for direct use. Instead, a derived type should expose its own, dedicated interface, which replaces this type's interface. As a sample, let us look at provided derived type Condition, which implements the simplest possible use-case of this class:

The type has protected inheritance to this struct.
Protected method isConditionMet is defined, which returns true if the instance was notified.
This parent struct is made a friend too enable access to the protected method.
Own interface methods are provided. In this case methods Notify, NotifyAll, and Wait.

: A more sophisticated but still simple implementation can be reviewed by analyzing the source of type job-queues in classes DedicatedWorker and ThreadPool. Its corresponding interface methods are push and pop alike, which do not resemble too much to the terms wait/notify anymore.

Debug-Information:: With debug-builds, several assertions are made to avoid wrong use of the type. This is implemented by adding the field member Dbg. The output format of assertions should be 'clickable' inside a users' IDE. The default output string is optimized for JetBrains CLion and can be changed by manipulating the static field member DbgConditionAsserter::ASSERTION_FORMAT.

Availability: This type is not available if the compiler-symbol ALIB_SINGLE_THREADED is set.

See also

Chapter A.5 Collecting Caller Information of the General Programmer's Manual.
For this class, a pretty printer for the GNU debugger is provided.

Template Parameters

TDerived The derived type which provides method isConditionMet.

Definition at line 78 of file condition.inl.

Collaboration diagram for alib::threads::TCondition< TDerived >:

[legend]

Public Field Index:
std::condition_variable	conditionVariable
	The condition variable used for blocking and notification.

DbgConditionAsserter	Dbg
	The debug tool instance.

std::mutex	mutex
	The mutex used for locking this instance.

Public Method Index:
	TCondition (const character *dbgName)

void	Acquire (ALIB_DBG_TAKE_CI)

TDerived &	cast ()

void	Release (ALIB_DBG_TAKE_CI)

void	ReleaseAndNotify (ALIB_DBG_TAKE_CI)

void	ReleaseAndNotifyAll (ALIB_DBG_TAKE_CI)

void	WaitForNotification (ALIB_DBG_TAKE_CI)

void	WaitForNotification (const Ticks &wakeUpTime, const CallerInfo &ci)

void	WaitForNotification (const Ticks::Duration &maxWaitTimeSpan, const CallerInfo &ci)

void	WaitForNotification (const Ticks::Duration::TDuration &maxWaitTimeSpan, const CallerInfo &ci)

Field Details:

◆ conditionVariable

template<typename TDerived>

std::condition_variable alib::threads::TCondition< TDerived >::conditionVariable

The condition variable used for blocking and notification.

Definition at line 84 of file condition.inl.

◆ Dbg

template<typename TDerived>

DbgConditionAsserter alib::threads::TCondition< TDerived >::Dbg

The debug tool instance.

Definition at line 93 of file condition.inl.

◆ mutex

template<typename TDerived>

std::mutex alib::threads::TCondition< TDerived >::mutex

The mutex used for locking this instance.

Definition at line 81 of file condition.inl.

Constructor(s) / Destructor Details:

◆ TCondition()

template<typename TDerived>

alib::threads::TCondition< TDerived >::TCondition ( const character * dbgName )

inline

Constructor.

Parameters

dbgName The name of this instance.
Available only with debug-builds. With release-builds, this type is default constructed. Hence, this parameter has to be provided using macro ALIB_DBG, which prunes the name away.

Definition at line 101 of file condition.inl.

Method Details:

◆ Acquire()

template<typename TDerived>

void alib::threads::TCondition< TDerived >::Acquire ( ALIB_DBG_TAKE_CI )

inline

A thread which invokes this method gets registered as the current owner of this object, until the same thread releases the ownership invoking Release. In the case that this object is already owned by another thread, the invoking thread is suspended until ownership can be gained.

Multiple (nested) calls to this method are not supported and constitute undefined behavior. In debug-compilations, an error is raised.

An instance has to be acquired before invoking any of the notifiy- or wait-methods. When return from a notification method, the instance is released. With return from a wait method, the instance is still held.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 121 of file condition.inl.

◆ cast()

template<typename TDerived>

TDerived & alib::threads::TCondition< TDerived >::cast ( )

inline

Helper to statically casts this object to the derived type.

Returns: *this cast to a reference of TDerived.

Definition at line 88 of file condition.inl.

◆ Release()

template<typename TDerived>

void alib::threads::TCondition< TDerived >::Release ( ALIB_DBG_TAKE_CI )

inline

Releases ownership of this object. If this method is invoked on an object that is not acquired or acquired by a different thread, in debug-compilations an error is raised. In release compilations, this leads to undefined behavior.

See also: Method Acquire.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 147 of file condition.inl.

◆ ReleaseAndNotify()

template<typename TDerived>

void alib::threads::TCondition< TDerived >::ReleaseAndNotify ( ALIB_DBG_TAKE_CI )

inline

Unblock a next waiting thread.

As the method name indicates, with this implementation, it is necessary to acquire this object before invoking this method. Internally, the mutex will be released, and thus no separate call to Release is necessary, respectively allowed.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 170 of file condition.inl.

◆ ReleaseAndNotifyAll()

template<typename TDerived>

void alib::threads::TCondition< TDerived >::ReleaseAndNotifyAll ( ALIB_DBG_TAKE_CI )

inline

Releases the internal mutex and wakes up all sleeping threads.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 193 of file condition.inl.

◆ WaitForNotification() [1/4]

template<typename TDerived>

void alib::threads::TCondition< TDerived >::WaitForNotification ( ALIB_DBG_TAKE_CI )

inline

Waits for notification (for an unlimited time).
Before invoking this method, this object has to be acquired. After the wake-up call, the internal mutex is (again) acquired and thus has to be released by the owner.
It is allowed to create (endless) loops that never actively release this instance but call one of the waiting methods instead.
Note that "spurious wake-ups" are internally caught with this implementation.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 224 of file condition.inl.

◆ WaitForNotification() [2/4]

template<typename TDerived>

void alib::threads::TCondition< TDerived >::WaitForNotification	(	const Ticks &	wakeUpTime,
		const CallerInfo &	ci )

inline

Same as WaitForNotification(ALIB_DBG_TAKE_CI), but takes a point in time at which waiting stops.

Parameters

wakeUpTime	The point in time to wake up, even if not notified.
ci	Caller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.

Definition at line 320 of file condition.inl.

◆ WaitForNotification() [3/4]

template<typename TDerived>

void alib::threads::TCondition< TDerived >::WaitForNotification	(	const Ticks::Duration &	maxWaitTimeSpan,
		const CallerInfo &	ci )

inline

Same as WaitForNotification(ALIB_DBG_TAKE_CI), but takes a time span that defines a maximum wait time.

Parameters

maxWaitTimeSpan	The maximum time to wait.
ci	Caller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.

Definition at line 300 of file condition.inl.

◆ WaitForNotification() [4/4]

template<typename TDerived>

void alib::threads::TCondition< TDerived >::WaitForNotification	(	const Ticks::Duration::TDuration &	maxWaitTimeSpan,
		const CallerInfo &	ci )

inline

Same as WaitForNotification(ALIB_DBG_TAKE_CI), but takes a C++ time span that defines a maximum wait time.

Parameters

maxWaitTimeSpan	The maximum time to wait.
ci	Caller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.

Definition at line 264 of file condition.inl.

The documentation for this struct was generated from the following file:

condition.inl

Description:

Public Field Index:

Public Method Index:

Field Details:

◆ conditionVariable

◆ Dbg

◆ mutex

Constructor(s) / Destructor Details:

◆ TCondition()

Method Details:

◆ Acquire()

◆ cast()

◆ Release()

◆ ReleaseAndNotify()

◆ ReleaseAndNotifyAll()

◆ WaitForNotification() [1/4]

◆ WaitForNotification() [2/4]

◆ WaitForNotification() [3/4]

◆ WaitForNotification() [4/4]