Lock Class Reference

Description:

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

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. Note that instead of wrapping std::mutex, with debug-compilations class std::timed_mutex is wrapped.

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.
• For this class, as well as for all other five lock types of this module, a pretty printer for the GNU debugger is provided.

Definition at line 58 of file lock.hpp.

#include <lock.hpp>

Inheritance diagram for Lock:

Collaboration diagram for Lock:

Public Field Index:
DbgLockAsserter	Dbg
	The debug tool instance.

Public Method Index:
	~Lock () override
	Destructor. With debug-compilations, asserts that this lock is not acquired.
ALIB_API void	Acquire (ALIB_DBG_TAKE_CI)
virtual ALIB_API bool	DCSIsAcquired () const override
virtual ALIB_API bool	DCSIsSharedAcquired () const override
ALIB_API void	Release (ALIB_DBG_TAKE_CI)
ALIB_API bool	TryAcquire (ALIB_DBG_TAKE_CI)
Public Method Index: inherited from DbgCriticalSections::AssociatedLock
virtual	~AssociatedLock ()
	Virtual Destructor.

Protected Field Index:
std::mutex	mutex

Field Details:

Dbg

DbgLockAsserter Dbg

The debug tool instance.

Definition at line 78 of file lock.hpp.

mutex

std::mutex mutex

protected

The internal object to lock on.

Note

With debug-compilations, this is of type std::timed_mutex.

Definition at line 71 of file lock.hpp.

Constructor(s) / Destructor Details:

~Lock()

~Lock ( )

inlineoverride

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

Definition at line 85 of file lock.hpp.

Here is the call graph for this function:

Method Details:

Acquire()

void Acquire

(

ALIB_DBG_TAKE_CI

)

Acquires this lock. 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.

Debug Parameter:

Pass macro ALIB_CALLER_PRUNED with invocations.

Definition at line 312 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 274 of file locks.cpp.

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

Release()

void 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 360 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. 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 346 of file locks.cpp.

Here is the call graph for this function:

---

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

• lock.hpp
• locks.cpp