Description:

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

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.

Typically macros ALIB_LOCK and ALIB_LOCK_WITH should be used to acquire this lock in non-shared mode and macros ALIB_LOCK_SHARED and ALIB_LOCK_SHARED_WITH for shared acquisitions.

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, 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::shared_mutex, with debug-compilations class std::shared_timed_mutex is wrapped.
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

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 54 of file sharedlock.inl.

Inheritance diagram for alib::threads::SharedLock:

[legend]

Collaboration diagram for alib::threads::SharedLock:

[legend]

Public Field Index:
DbgSharedLockAsserter	Dbg
	The debug tool instance.

std::atomic< int >	DbgWarningMaximumShared =10

Public Method Index:
	~SharedLock () 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)

Public Method Index: inherited from alib::lang::DbgCriticalSections::AssociatedLock
virtual	~AssociatedLock ()
	Virtual Destructor.

Protected Field Index:
std::shared_mutex	mutex

Field Details:

◆ Dbg

DbgSharedLockAsserter alib::threads::SharedLock::Dbg

The debug tool instance.

Definition at line 74 of file sharedlock.inl.

◆ DbgWarningMaximumShared

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

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

Definition at line 78 of file sharedlock.inl.

◆ mutex

std::shared_mutex alib::threads::SharedLock::mutex

protected

The internal object to lock on.

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

Definition at line 67 of file sharedlock.inl.

Constructor(s) / Destructor Details:

◆ ~SharedLock()

alib::threads::SharedLock::~SharedLock ( )

inlineoverride

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

Definition at line 84 of file sharedlock.inl.

Method Details:

◆ Acquire()

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

Here is the call graph for this function:

◆ AcquireShared()

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

Acquires this lock in shared mode. In the case that this object is already owned (not shared) 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 478 of file locks.cpp.

Here is the call graph for this function:

◆ DCSIsAcquired()

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

overridevirtual

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

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

Definition at line 767 of file locks.cpp.

◆ DCSIsSharedAcquired()

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

◆ Release()

void alib::threads::SharedLock::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_COMMA_CALLER_PRUNED with invocations.

Definition at line 468 of file locks.cpp.

◆ ReleaseShared()

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

◆ TryAcquire()

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

◆ TryAcquireShared()

bool alib::threads::SharedLock::TryAcquireShared ( ALIB_DBG_TAKE_CI )