ALib C++ Library
Library Version: 2402 R1
Documentation generated by doxygen
Loading...
Searching...
No Matches
Public Method Index: | List of all members
Sleeper Class Reference

Description:

This class is a simple wrapper around C++ standard library types std::mutex and std::condition_variable and allows a thread to sleep until another thread wakes the thread up.

Prior to using one of the overloaded sleep methods WaitForNotification, the object has to be acquired. During sleep, a notifying thread may, but in most situations should not acquire this object. Further details are given with the documentation of method Notify.

This class does not allow repeated calls to method Acquire without prior invocations of Release. Repeated acquisitions cause undefined behavior. With debug builds, an assertion is raised when Acquire is invoked while the lock is already acquired. In this respect, this class compares to that of ThreadLockNR and not to that of ThreadLock

Multiple threads may sleep in parallel using a single instance of this object. The notification thread may either wake up one of them or wake all up by using NotifyAll.

Definition at line 53 of file sleeper.hpp.

#include <sleeper.hpp>

Collaboration diagram for Sleeper:
[legend]

Public Method Index:

 Sleeper ()=default
 
void Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)
 
void Notify ()
 
void NotifyAll ()
 
void Release ()
 
void WaitForNotification ()
 
void WaitForNotification (const Ticks &wakeUpTime)
 
void WaitForNotification (const Ticks::Duration &maxSleepTime)
 

Field Details:

◆ dbgIsAcquiredBy

std::thread::id dbgIsAcquiredBy
protected

Id of a thread that currently acquired this object's mutex, used to detect invocations of methods WaitForNotification and Release without prior acquirement, as well as forbidden multiple (nested) acquirements.s Available only in debug compilations.

Definition at line 80 of file sleeper.hpp.

◆ DbgOwnerFile

NCString DbgOwnerFile =nullptr
protected

Source location of acquirement. (Available only in debug-builds.).

Definition at line 67 of file sleeper.hpp.

◆ DbgOwnerFunc

NCString DbgOwnerFunc =nullptr
protected

Source location of acquirement. (Available only in debug-builds.).

Definition at line 73 of file sleeper.hpp.

◆ DbgOwnerLine

int DbgOwnerLine
protected

Source location of acquirement. (Available only in debug-builds.).

Definition at line 70 of file sleeper.hpp.

◆ event

std::condition_variable event
protected

The condition variable used for sleeping and notification to wake up.

Definition at line 60 of file sleeper.hpp.

◆ mutex

std::mutex mutex
protected

The mutex used for locking.

Definition at line 57 of file sleeper.hpp.

◆ wasNotified

bool wasNotified
protected

Flag used to detect "spurious" wake-ups.

Definition at line 63 of file sleeper.hpp.

Constructor(s) / Destructor Details::

◆ Sleeper()

Sleeper ( )
default

Default constructor.

Method Details:

◆ Acquire()

void Acquire ( const NCString & dbgFile,
int dbgLine,
const NCString & dbgFunc )
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 lead to undefined behavior. In debug-compilations, an assertion is raised.

Note
In debug-compilations of the library, this method accepts three parameters, providing information about the caller. In the release version these parameters do not exist. Therefore use macro ALIB_CALLER_PRUNED to provide the parameters: 
   sample.Acquire( ALIB_CALLER_PRUNED );
Parameters
dbgFileCaller information. Available only with debug builds.
dbgLineCaller information. Available only with debug builds.
dbgFuncCaller information. Available only with debug builds.

Definition at line 109 of file sleeper.hpp.

Here is the call graph for this function:

◆ Notify()

void Notify ( )
inline

Wakes up the next sleeping thread.

It is not necessary and not even recommended to acquiring this object, prior to waking the next thread up. However, in some situations, it should be done. Further explanation on this is given with the documentation of the standard C++ library, which is quoted here:

"The notifying thread does not need to hold the lock on the same mutex as the one held by the waiting thread(s); in fact doing so is a pessimization, since the notified thread would immediately block again, waiting for the notifying thread to release the lock. However, some implementations (in particular many implementations of pthreads) recognize this situation and avoid this "hurry up and wait" scenario by transferring the waiting thread from the condition variable's queue directly to the queue of the mutex within the notify call, without waking it up.

Notifying while under the lock may nevertheless be necessary when precise scheduling of events is required, e.g. if the waiting thread would exit the program if the condition is satisfied, causing destruction of the notifying thread's condition variable. A spurious wakeup after mutex unlock but before notify would result in notify called on a destroyed object.

Definition at line 168 of file sleeper.hpp.

◆ NotifyAll()

void NotifyAll ( )
inline

Wakes up all sleeping threads.

See also
For explanations about the necessity of acquiring this object prior to to notification, see documentation of method Notify.

Definition at line 179 of file sleeper.hpp.

◆ Release()

void Release ( )
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 assertion is raised. In release compilations, this leads to undefined behavior.

Definition at line 130 of file sleeper.hpp.

Here is the call graph for this function:

◆ WaitForNotification() [1/3]

void WaitForNotification ( )
inline

Waits for notification (for an unlimited time).

Prior to 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 later.

Definition at line 191 of file sleeper.hpp.

Here is the call graph for this function:

◆ WaitForNotification() [2/3]

void WaitForNotification ( const Ticks & wakeUpTime)
inline

Waits for notification, but only fore a given duration. Prior to 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 later.

Note
In the absense of module ALib Time , this method has template parameters and parameter maxSleepTime will be defined like in std::condition_variable::WaitForNotification as const std::chrono::time_point<Clock, Duration>&.
Parameters
wakeUpTimeThe point in time to wake up, even if not notified.

Definition at line 252 of file sleeper.hpp.

Here is the call graph for this function:

◆ WaitForNotification() [3/3]

void WaitForNotification ( const Ticks::Duration & maxSleepTime)
inline

Waits for notification, but only fore a given duration..

Prior to 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 later.

Note
In the absense of module ALib Time , this method has template parameters and parameter maxSleepTime will be defined like in std::condition_variable::wait_for as const std::chrono::duration<Rep, Period>&.
Parameters
maxSleepTimeThe maximum time to wait.

Definition at line 223 of file sleeper.hpp.

Here is the call graph for this function:
The documentation for this class was generated from the following file: