Description:

This class is a simple wrapper around C++ standard library type std::recursive_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.
With release-compilations, the only difference to using std::recursive_timed_mutex directly is that "spurious wake-ups" are detected and mitigated by this implementation.

code block, then it is recommended to use a stack instantiation of class OwnerRecursive to acquire and release objects of this class. Such a use is highly simplified with macros ALIB_LOCK_RECURSIVE and ALIB_LOCK_RECURSIVE_WITH.

Nested acquisitions are supported with this type. An instance of this class is released when an equal number of invocations to AcquireRecursive and ReleaseRecursive have been performed.
This class has slightly reduced performance in comparison to non-recursive type Lock. Not only for this reason, non-nested locking is the preferred technique. But there are situations where nested locks are just unavoidable.

Debug-Features

Public member Dbg is available with debug-compilations. It offers the following features:

The object stores the actual owning thread and the source code position of the last acquirement.
Releasing non-acquired instances, as well as destructing acquired one, raise an assertion.
A warning threshold for the number of nested acquisitions can be defined with public member DbgLockAsserter::RecursionLimit.
Field WaitTimeLimit enables the raise of ALib warnings in case a certain wait time is exceeded.

See also

Chapter 3. Locks of the Programmer's Manual of the module ALib Threads.
Chapter A.4 Collecting Caller Information of the General Programmer's Manual.

Definition at line 63 of file recursivetimedlock.hpp.

#include <recursivetimedlock.hpp>

Inheritance diagram for RecursiveTimedLock:

[legend]

Collaboration diagram for RecursiveTimedLock:

[legend]

Public Field Index:
DbgLockAsserter	Dbg
	The debug tool instance.

Public Method Index:
	~RecursiveTimedLock () override
	Destructor. With debug-compilations, asserts that this lock is not acquired.

ALIB_API void	AcquireRecursive (ALIB_DBG_TAKE_CI)

virtual ALIB_API bool	DCSIsAcquired () const override

virtual ALIB_API bool	DCSIsSharedAcquired () const override

ALIB_API void	ReleaseRecursive (ALIB_DBG_TAKE_CI)

ALIB_API bool	TryAcquire (ALIB_DBG_TAKE_CI)

bool	TryAcquireTimed (const Ticks &pointInTime, const CallerInfo &ci)

ALIB_API 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 DbgCriticalSections::AssociatedLock
virtual	~AssociatedLock ()
	Virtual Destructor.

Protected Field Index:
std::recursive_timed_mutex	mutex
	The internal object to lock on.

Field Details:

◆ Dbg

DbgLockAsserter Dbg

The debug tool instance.

Definition at line 75 of file recursivetimedlock.hpp.

◆ mutex

std::recursive_timed_mutex mutex

protected

The internal object to lock on.

Definition at line 70 of file recursivetimedlock.hpp.

Constructor(s) / Destructor Details:

◆ ~RecursiveTimedLock()

~RecursiveTimedLock ( )

inlineoverride

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

Definition at line 80 of file recursivetimedlock.hpp.

Here is the call graph for this function:

Method Details:

◆ AcquireRecursive()

void AcquireRecursive ( ALIB_DBG_TAKE_CI )

Thread which invokes this method gets registered as the current owner of this object, until the same thread releases the ownership invoking ReleaseRecursive. 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 counted and the object is only released when the same number of Release() calls have been made.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 561 of file locks.cpp.

Here is the call graph for this function:

◆ DCSIsAcquired()

bool DCSIsAcquired ( ) const

overridevirtual

Returns: true if the lock is acquired (in non-shared mode), false otherwise.

Implements DbgCriticalSections::AssociatedLock.

Definition at line 280 of file locks.cpp.

Here is the call graph for this function:

◆ DCSIsSharedAcquired()

bool DCSIsSharedAcquired ( ) const

overridevirtual

Returns: true if the lock is shared-acquired (by at least any thread). Otherwise, returns false.

Implements DbgCriticalSections::AssociatedLock.

Definition at line 281 of file locks.cpp.

Here is the call graph for this function:

◆ ReleaseRecursive()

void ReleaseRecursive ( ALIB_DBG_TAKE_CI )

Releases ownership of this object. If AcquireRecursive was called multiple times before, the same number of calls to this method has to be performed to release ownership.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 637 of file locks.cpp.

Here is the call graph for this function:

◆ TryAcquire()

bool TryAcquire ( ALIB_DBG_TAKE_CI )

nodiscard

Tries to acquire this lock. Successful calls to this method are counted, as if AcquireRecursive was called and an according invocation of ReleaseRecursive has to be performed.

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 597 of file locks.cpp.

Here is the call graph for this function:

◆ TryAcquireTimed() [1/4]

bool TryAcquireTimed	(	const Ticks &	pointInTime,
		const CallerInfo &	ci )

inlinenodiscard

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

Parameters

pointInTime	The point in time, when this method stops waiting.
ci	Caller 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 162 of file recursivetimedlock.hpp.

Here is the call graph for this function:

◆ TryAcquireTimed() [2/4]

bool 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 ReleaseRecursive. In the case that this object is already owned by another thread, the invoking thread is suspended until ownership can be gained.
Successful calls to this method are counted, as if AcquireRecursive was called and an according invocation of ReleaseRecursive has to be performed.

Parameters

waitDuration	The maximum time-span to wait.
ci	Caller 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 613 of file locks.cpp.

Here is the call graph for this function:

◆ TryAcquireTimed() [3/4]

bool 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

waitDuration	The point in time, when this method stops waiting.
ci	Caller 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 152 of file recursivetimedlock.hpp.

Here is the call graph for this function:

◆ TryAcquireTimed() [4/4]

bool 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.

Parameters

pointInTime	The point in time, when this method stops waiting.
ci	Caller 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 174 of file recursivetimedlock.hpp.

Here is the call graph for this function:

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

Description:

Public Field Index:

Public Method Index:

Protected Field Index:

Field Details:

◆ Dbg

◆ mutex

Constructor(s) / Destructor Details:

◆ ~RecursiveTimedLock()

Method Details:

◆ AcquireRecursive()

◆ DCSIsAcquired()

◆ DCSIsSharedAcquired()

◆ ReleaseRecursive()

◆ TryAcquire()

◆ TryAcquireTimed() [1/4]

◆ TryAcquireTimed() [2/4]

◆ TryAcquireTimed() [3/4]

◆ TryAcquireTimed() [4/4]