ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
alib::threads::SharedTimedLock Class Reference

Description:

This class is a simple wrapper around C++ standard library type std::shared_timed_mutex. Thus, it is used to implement mutual exclusive access to resources by protecting critical code sections from being executed in parallel in concurrent threads, while allowing typical read-operations to continue to be executed in parallel.
With release-compilations, the only difference to using std::shared_timed_mutex directly is that "spurious wake-ups" are detected and mitigated by this implementation.

When a pair of Acquire and Release invocations is performed within the same code block, then it is recommended to use a stack instantiation of class Owner to acquire and release objects of this class. Such a use is highly simplified with macros ALIB_LOCK and ALIB_LOCK_WITH.
The same is recommended for paired invocations of AcquireShared and ReleaseShared. Here, class OwnerShared is to be used, best using macros ALIB_LOCK_SHARED and ALIB_LOCK_SHARED_WITH.

This class does not allow nested calls to the method Acquire - method Release has to be invoked (from within the same thread that acquired this mutex), before any other thread can again gain access. Nested acquisitions constitute undefined behavior.

Debug-Features
Public member Dbg is available with debug-compilations. It offers the following features:
  • An assertion is raised when nested use is performed.
  • The object stores the actual owning thread and the source code position of the last acquirement. Likewise the last shared acquirement's caller information is stored.
  • Releasing non-acquired instances, as well as destructing acquired one, raises an ALib error.
  • Field WaitTimeLimit the raise of ALib warnings in case a certain wait time is exceeded.
  • Field DbgWarningMaximumShared enables the raise of ALib warnings in the case that the number of parallel shared acquirements reaches the limit given with this member.
Availability
This type is not available if the compiler-symbol ALIB_SINGLE_THREADED is set.
See also

Definition at line 51 of file sharedtimedlock.inl.

Inheritance diagram for alib::threads::SharedTimedLock:
[legend]
Collaboration diagram for alib::threads::SharedTimedLock:
[legend]

Public Field Index:

DbgSharedLockAsserter Dbg
 The debug tool instance.
 
std::atomic< int > DbgWarningMaximumShared =10
 

Public Method Index:

 ~SharedTimedLock () override
 Destructor. With debug-compilations, asserts that this lock is not acquired.
 
ALIB_DLL void Acquire (ALIB_DBG_TAKE_CI)
 
ALIB_DLL void AcquireShared (ALIB_DBG_TAKE_CI)
 
virtual ALIB_DLL bool DCSIsAcquired () const override
 
virtual ALIB_DLL bool DCSIsSharedAcquired () const override
 
ALIB_DLL void Release (ALIB_DBG_TAKE_CI)
 
ALIB_DLL void ReleaseShared (ALIB_DBG_TAKE_CI)
 
ALIB_DLL bool TryAcquire (ALIB_DBG_TAKE_CI)
 
ALIB_DLL bool TryAcquireShared (ALIB_DBG_TAKE_CI)
 
bool TryAcquireSharedTimed (const Ticks &pointInTime, const CallerInfo &ci)
 
ALIB_DLL bool TryAcquireSharedTimed (const Ticks::Duration &waitDuration, const CallerInfo &ci)
 
bool TryAcquireSharedTimed (const Ticks::Duration::TDuration &waitDuration, const CallerInfo &ci)
 
bool TryAcquireSharedTimed (const Ticks::TTimePoint &pointInTime, const CallerInfo &ci)
 
bool TryAcquireTimed (const Ticks &pointInTime, const CallerInfo &ci)
 
ALIB_DLL bool TryAcquireTimed (const Ticks::Duration &waitDuration, const CallerInfo &ci)
 
bool TryAcquireTimed (const Ticks::Duration::TDuration &waitDuration, const CallerInfo &ci)
 
bool TryAcquireTimed (const Ticks::TTimePoint &pointInTime, const CallerInfo &ci)
 
- Public Method Index: inherited from alib::lang::DbgCriticalSections::AssociatedLock
virtual ~AssociatedLock ()
 Virtual Destructor.
 

Protected Field Index:

std::shared_timed_mutex mutex
 The internal object to lock on.
 

Field Details:

◆ Dbg

DbgSharedLockAsserter alib::threads::SharedTimedLock::Dbg

The debug tool instance.

Definition at line 63 of file sharedtimedlock.inl.

◆ DbgWarningMaximumShared

std::atomic<int> alib::threads::SharedTimedLock::DbgWarningMaximumShared =10

Warning-threshold of maximum number of parallel shared acquisitions.
Defaults to 10.

Definition at line 67 of file sharedtimedlock.inl.

◆ mutex

std::shared_timed_mutex alib::threads::SharedTimedLock::mutex
protected

The internal object to lock on.

Definition at line 58 of file sharedtimedlock.inl.

Constructor(s) / Destructor Details:

◆ ~SharedTimedLock()

alib::threads::SharedTimedLock::~SharedTimedLock ( )
inlineoverride

Destructor. With debug-compilations, asserts that this lock is not acquired.

Definition at line 71 of file sharedtimedlock.inl.

Method Details:

◆ Acquire()

void alib::threads::SharedTimedLock::Acquire ( ALIB_DBG_TAKE_CI )

Same as TryAcquireTimed(const Ticks::Duration&, const CallerInfo&) but misses the parameter waitTime. Using this method, the behavior is equivalent to that of sibling type Lock.

Debug Parameter:
Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 562 of file locks.cpp.

Here is the call graph for this function:

◆ AcquireShared()

void alib::threads::SharedTimedLock::AcquireShared ( ALIB_DBG_TAKE_CI )

Same as TryAcquireSharedTimed(const Ticks::Duration&, const CallerInfo&) but misses the parameter waitTime. Using this method, the behavior is equivalent to that of sibling type SharedLock.

Debug Parameter:
Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 658 of file locks.cpp.

Here is the call graph for this function:

◆ DCSIsAcquired()

bool alib::threads::SharedTimedLock::DCSIsAcquired ( ) const
overridevirtual
Returns
true if the lock is acquired (in non-shared mode), false otherwise.

Implements alib::lang::DbgCriticalSections::AssociatedLock.

Definition at line 770 of file locks.cpp.

◆ DCSIsSharedAcquired()

bool alib::threads::SharedTimedLock::DCSIsSharedAcquired ( ) const
overridevirtual
Returns
true if the lock is shared-acquired (by at least any thread). Otherwise, returns false.

Implements alib::lang::DbgCriticalSections::AssociatedLock.

Definition at line 771 of file locks.cpp.

◆ Release()

void alib::threads::SharedTimedLock::Release ( ALIB_DBG_TAKE_CI )

Releases ownership of this object. If this method is invoked on an object that is not acquired, in debug-compilations an assertion is raised. In release compilations, this leads to undefined behavior.

Debug Parameter:
Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 630 of file locks.cpp.

◆ ReleaseShared()

void alib::threads::SharedTimedLock::ReleaseShared ( ALIB_DBG_TAKE_CI )

Releases shared ownership of this object. Invoking this method on an object that is not "shared acquired" by this thread constitutes undefined behavior.
In debug-compilations the overall sum (of any thread) of shared acquirements and releases is counted, and an error is raised if more releases than acquisitions are performed.

Debug Parameter:
Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 745 of file locks.cpp.

◆ TryAcquire()

bool alib::threads::SharedTimedLock::TryAcquire ( ALIB_DBG_TAKE_CI )
nodiscard

Tries to acquire this lock. Multiple (nested) successful calls to this method or method Acquire are not supported and lead to undefined behavior.

Debug Parameter:
Pass macro ALIB_CALLER_PRUNED with invocations.
Returns
true if the lock was not acquired by a different thread and thus, this call was successful. false otherwise.

Definition at line 596 of file locks.cpp.

◆ TryAcquireShared()

bool alib::threads::SharedTimedLock::TryAcquireShared ( ALIB_DBG_TAKE_CI )
nodiscard

Tries to acquire this lock in shared mode. Multiple (nested) calls to this method or method AcquireShared from within the same thread are not supported and lead to undefined behavior.

Debug Parameter:
Pass macro ALIB_CALLER_PRUNED with invocations.
Returns
true if the lock was not acquired by a different thread and thus, this call was successful. false otherwise.

Definition at line 699 of file locks.cpp.

◆ TryAcquireSharedTimed() [1/4]

bool alib::threads::SharedTimedLock::TryAcquireSharedTimed ( const Ticks & pointInTime,
const CallerInfo & ci )
inlinenodiscard

Same as overloaded sibling, but expects a point in time rather than an Ticks::Duration.

Parameters
pointInTimeThe point in time, when this method stops waiting.
ciCaller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.
Returns
true if the lock was acquired, false if the pointInTime was reached without successful acquisition.

Definition at line 243 of file sharedtimedlock.inl.

Here is the call graph for this function:

◆ TryAcquireSharedTimed() [2/4]

bool alib::threads::SharedTimedLock::TryAcquireSharedTimed ( const Ticks::Duration & waitDuration,
const CallerInfo & ci )
nodiscard

Same as method TryAcquireShared(ALIB_DBG_TAKE_CI), but accepts a maximum wait time as first parameter.

Parameters
waitDurationThe maximum time-span to wait.
ciCaller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.
Returns
true if the lock was acquired, false if the waitDuration expired without successful acquisition

Definition at line 718 of file locks.cpp.

Here is the call graph for this function:

◆ TryAcquireSharedTimed() [3/4]

bool alib::threads::SharedTimedLock::TryAcquireSharedTimed ( const Ticks::Duration::TDuration & waitDuration,
const CallerInfo & ci )
inlinenodiscard

Same as overloaded sibling, but expects a C++ standard library duration type rather than an Ticks::Duration.

Parameters
waitDurationThe point in time, when this method stops waiting.
ciCaller information. Available only with debug-builds.
Returns
true if the lock was acquired, false if the pointInTime was reached without successful acquisition.

Definition at line 232 of file sharedtimedlock.inl.

Here is the call graph for this function:

◆ TryAcquireSharedTimed() [4/4]

bool alib::threads::SharedTimedLock::TryAcquireSharedTimed ( const Ticks::TTimePoint & pointInTime,
const CallerInfo & ci )
inlinenodiscard

Same as overloaded sibling, but expects a C++ standard library point in time type rather than a Ticks::Duration value.

Parameters
pointInTimeThe point in time, when this method stops waiting.
ciCaller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.
Returns
true if the lock was acquired, false if the pointInTime was reached without successful acquisition.

Definition at line 255 of file sharedtimedlock.inl.

Here is the call graph for this function:

◆ TryAcquireTimed() [1/4]

bool alib::threads::SharedTimedLock::TryAcquireTimed ( const Ticks & pointInTime,
const CallerInfo & ci )
inlinenodiscard

Same as overloaded sibling, but expects a point in time rather than an Ticks::Duration.

Parameters
pointInTimeThe point in time, when this method stops waiting.
ciCaller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.
Returns
true if the lock was acquired, false if the pointInTime was reached without successful acquisition.

Definition at line 147 of file sharedtimedlock.inl.

Here is the call graph for this function:

◆ TryAcquireTimed() [2/4]

bool alib::threads::SharedTimedLock::TryAcquireTimed ( const Ticks::Duration & waitDuration,
const CallerInfo & ci )
nodiscard

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.

Parameters
waitDurationThe maximum time-span to wait.
ciCaller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.
Returns
true if the lock was acquired, false if the waitDuration expired without successful acquisition

Definition at line 609 of file locks.cpp.

Here is the call graph for this function:

◆ TryAcquireTimed() [3/4]

bool alib::threads::SharedTimedLock::TryAcquireTimed ( const Ticks::Duration::TDuration & waitDuration,
const CallerInfo & ci )
inlinenodiscard

Same as overloaded sibling, but expects a C++ standard library duration type rather than an Ticks::Duration.

Parameters
waitDurationThe point in time, when this method stops waiting.
ciCaller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.
Returns
true if the lock was acquired, false if the pointInTime was reached without successful acquisition.

Definition at line 136 of file sharedtimedlock.inl.

Here is the call graph for this function:

◆ TryAcquireTimed() [4/4]

bool alib::threads::SharedTimedLock::TryAcquireTimed ( const Ticks::TTimePoint & pointInTime,
const CallerInfo & ci )
inlinenodiscard

Same as overloaded sibling, but expects a C++ standard library point in time type rather than an Ticks::Duration.

Debug Parameter:
Pass macro ALIB_COMMA_CALLER_PRUNED with invocations.
Parameters
pointInTimeThe point in time, when this method stops waiting.
ciCaller information. Use macro ALIB_COMMA_CALLER_PRUNED with invocations.
Returns
true if the lock was acquired, false if the pointInTime was reached without successful acquisition.

Definition at line 161 of file sharedtimedlock.inl.

Here is the call graph for this function:

The documentation for this class was generated from the following files: