Description:

This class is a simple wrapper around C++ standard library type std::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::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.

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.
Releasing non-acquired instances, as well as destructing acquired one, raise an assertion.
Field WaitTimeLimit enables the raise of ALib warnings in case a certain wait time is exceeded.

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

See also

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

Definition at line 43 of file timedlock.inl.

Inheritance diagram for alib::threads::TimedLock:

[legend]

Collaboration diagram for alib::threads::TimedLock:

[legend]

Public Field Index:
DbgLockAsserter	Dbg
	The debug tool instance.

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

ALIB_DLL void	Acquire (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 bool	TryAcquire (ALIB_DBG_TAKE_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::timed_mutex	mutex
	The internal object to lock on.

Field Details:

◆ Dbg

DbgLockAsserter alib::threads::TimedLock::Dbg

The debug tool instance.

Definition at line 55 of file timedlock.inl.

◆ mutex

std::timed_mutex alib::threads::TimedLock::mutex

protected

The internal object to lock on.

Definition at line 50 of file timedlock.inl.

Constructor(s) / Destructor Details:

◆ ~TimedLock()

alib::threads::TimedLock::~TimedLock ( )

inlineoverride

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

Definition at line 60 of file timedlock.inl.

Method Details:

◆ Acquire()

void alib::threads::TimedLock::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 129 of file locks.cpp.

Here is the call graph for this function:

◆ DCSIsAcquired()

bool alib::threads::TimedLock::DCSIsAcquired ( ) const

overridevirtual

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

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

Definition at line 761 of file locks.cpp.

◆ DCSIsSharedAcquired()

bool alib::threads::TimedLock::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 762 of file locks.cpp.

◆ Release()

void alib::threads::TimedLock::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 199 of file locks.cpp.

◆ TryAcquire()

bool alib::threads::TimedLock::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 164 of file locks.cpp.

◆ TryAcquireTimed() [1/4]

bool alib::threads::TimedLock::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 129 of file timedlock.inl.

Here is the call graph for this function:

◆ TryAcquireTimed() [2/4]

bool alib::threads::TimedLock::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

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

Here is the call graph for this function:

◆ TryAcquireTimed() [3/4]

bool alib::threads::TimedLock::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 119 of file timedlock.inl.

Here is the call graph for this function:

◆ TryAcquireTimed() [4/4]

bool alib::threads::TimedLock::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 140 of file timedlock.inl.

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:

◆ ~TimedLock()

Method Details:

◆ Acquire()

◆ DCSIsAcquired()

◆ DCSIsSharedAcquired()

◆ Release()

◆ TryAcquire()

◆ TryAcquireTimed() [1/4]

◆ TryAcquireTimed() [2/4]

◆ TryAcquireTimed() [3/4]

◆ TryAcquireTimed() [4/4]