Description:

While this class does not inherit from ThreadLockNR , it copies and extends its interface and functionality. With this lock, nested acquisitions are supported with this type. An instance of this class is released when an equal amount of invocations to Acquire and Release have been performed.

The object stores the actual owning thread and this thread may be queried. Such queries are not thread safe and should be performed only to perform tasks that are not mission critical, for example to create log output, usage statistics or similar things. In other words, a software's algorithmic logic should by principle never use information about the thread that currently owns a lock.

With debug builds, a warning threshold for the number of repeated acquisitions can be defined with public member DbgRecursionWarningThreshold. As the member's name indicates, it is assumed that too many repeated locks are caused by a recursive calls. Usually, locking data access should not be done in recursive code.
Furthermore, field DbgWarningAfterWaitTimeInMillis enables the raise of ALib warnings in case certain wait time is exceeded. Along with the warning, the owner and waiting threads' names and IDs are given, along with both source code location of the acquisition, respectively, the failed acquistion.

Definition at line 52 of file threadlock.hpp.

#include <threadlock.hpp>

Inheritance diagram for ThreadLock:

[legend]

Collaboration diagram for ThreadLock:

[legend]

Public Field Index:
NCString	DbgOwnerFile =nullptr

NCString	DbgOwnerFunc =nullptr

int	DbgOwnerLine

uint16_t	DbgRecursionWarningThreshold =10

integer	DbgWarningAfterWaitTimeInMillis =2000L

Public Method Index:
ALIB_API	ThreadLock (lang::Safeness safeness=lang::Safeness::Safe)

ALIB_API	~ThreadLock ()

ALIB_API void	Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)

int	CountAcquirements () const

Thread *	GetOwner () const

lang::Safeness	GetSafeness () const

bool	IsOwnedByCurrentThread () const

ALIB_API void	Release ()
	defined(ALIB_DOX)

ALIB_API void	SetSafeness (lang::Safeness safeness)

bool	WillRelease () const

Field Details:

◆ cntAcquirements

uint16_t cntAcquirements =0

protected

Counter for the number of Acquire() calls of the current thread.

Definition at line 69 of file threadlock.hpp.

◆ DbgOwnerFile

NCString DbgOwnerFile =nullptr

Source location of acquirement. (Available only in debug-builds.).

Definition at line 91 of file threadlock.hpp.

◆ DbgOwnerFunc

NCString DbgOwnerFunc =nullptr

Source location of acquirement. (Available only in debug-builds.).

Definition at line 97 of file threadlock.hpp.

◆ DbgOwnerLine

int DbgOwnerLine

Source location of acquirement. (Available only in debug-builds.).

Definition at line 94 of file threadlock.hpp.

◆ DbgRecursionWarningThreshold

uint16_t DbgRecursionWarningThreshold =10

Limit of recursions. If limit is reached or a multiple of it, an error is passed to ReportWriter . Defaults is 10. To disable, set to 0. Available only in debug versions of ALib .

Definition at line 105 of file threadlock.hpp.

◆ DbgWarningAfterWaitTimeInMillis

integer DbgWarningAfterWaitTimeInMillis =2000L

This is a threshold that causes Acquire() to raise an ALib warning in debug builds, if acquiring this lock takes longer than the given number of milliseconds. Such warning is often a quick first hint for a racing condition.

To disable such messages, set this value to 0. The default value is 2,000 (two seconds), which seems "very long", but can happen on systems with heavy load.

Definition at line 88 of file threadlock.hpp.

◆ mutex

std::mutex mutex

mutableprotected

The internal object to lock on.

Definition at line 63 of file threadlock.hpp.

◆ mutexNotifier

std::condition_variable mutexNotifier

protected

The internal object to lock on.

Definition at line 66 of file threadlock.hpp.

◆ owner

std::thread::id owner

protected

Thread ID of the current owner.

Definition at line 59 of file threadlock.hpp.

◆ safeness

lang::Safeness safeness

protected

The safeness setting.

Definition at line 72 of file threadlock.hpp.

Constructor(s) / Destructor Details::

◆ ThreadLock()

ThreadLock ( lang::Safeness safeness = lang::Safeness::Safe )

explicit

Constructor.

Parameters

safeness (Optional) Defaults to Safeness::Safe. See SetSafeness for more information.

Definition at line 25 of file threadlock.cpp.

◆ ~ThreadLock()

~ThreadLock ( )

Destructor.

Definition at line 30 of file threadlock.cpp.

Method Details:

◆ Acquire()

ALIB_API void Acquire	(	const NCString &	dbgFile,
		int	dbgLine,
		const NCString &	dbgFunc )

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 counted and the object is only released when the same number of Release() calls have been made.

Note

In debug-compilations of the library, this method accepts three parameters, providing information about the caller. In the release version these parameters do not exist. Therefore use macro ALIB_CALLER_PRUNED to provide the parameters:

   sample.Acquire( ALIB_CALLER_PRUNED );

Parameters

dbgFile	Caller information. Available only with debug builds.
dbgLine	Caller information. Available only with debug builds.
dbgFunc	Caller information. Available only with debug builds.

◆ CountAcquirements()

int CountAcquirements ( ) const

inline

Returns the number of acquirements of this ThreadLock.

Returns: The number of (recursive) acquirements.

Definition at line 214 of file threadlock.hpp.

◆ GetOwner()

Thread * GetOwner ( ) const

inline

Returns the current owner of this lock. If not acquired, nullptr is returned.

See also: Method IsOwnedByCurrentThread.

Returns: The thread that owns this lock, nullptr if not acquired.

Definition at line 200 of file threadlock.hpp.

Here is the call graph for this function:

◆ GetSafeness()

lang::Safeness GetSafeness ( ) const

inline

Query if this instance was set to unsafe mode.

Returns: A value of type alib::Safeness "Safeness"

Definition at line 238 of file threadlock.hpp.

◆ IsOwnedByCurrentThread()

bool IsOwnedByCurrentThread ( ) const

inline

Returns the current owner of this lock. If not acquired, nullptr is returned.

Returns: The thread that owns this lock.

Definition at line 189 of file threadlock.hpp.

◆ Release()

void Release ( )

defined(ALIB_DOX)

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

Definition at line 147 of file threadlock.cpp.

Here is the call graph for this function:

◆ SetSafeness()

void SetSafeness ( lang::Safeness safeness )

If parameter is Safeness::Unsafe, the whole locking system is disabled. The only objective here is to gain execution speed, as thread synchronization causes relatively expensive system calls. Use this method only if you are 100% sure that your (otherwise) critical section are executed in a single threaded environment. And: "relative expensive" means: they are not really expensive. This is provided only for the rare case that your critical section is very, very frequently executed.

Parameters

safeness Determines if this object should use a mutex (Safeness::Safe) or just do nothing (Safeness::Unsafe).

Definition at line 186 of file threadlock.cpp.

Here is the call graph for this function:

◆ WillRelease()

bool WillRelease ( ) const

inline

Returns true if the next invocation of Release will release the lock, otherwise false. In other words, returns true if this lock is acquired exactly 1.

Note: This method is not (and can not) be synchronized. Consequently, a reliable result is only guaranteed if IsOwnedByCurrentThread returns true. This method is therefore deemed to be used only in situations where it is assured that this lock is owned by the current thread.

Returns: true if locked exactly once.

Definition at line 178 of file threadlock.hpp.

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

Description:

Public Field Index:

Public Method Index:

Field Details:

◆ cntAcquirements

◆ DbgOwnerFile

◆ DbgOwnerFunc

◆ DbgOwnerLine

◆ DbgRecursionWarningThreshold

◆ DbgWarningAfterWaitTimeInMillis

◆ mutex

◆ mutexNotifier

◆ owner

◆ safeness

Constructor(s) / Destructor Details::

◆ ThreadLock()

◆ ~ThreadLock()

Method Details:

◆ Acquire()

◆ CountAcquirements()

◆ GetOwner()

◆ GetSafeness()

◆ IsOwnedByCurrentThread()

◆ Release()

◆ SetSafeness()

◆ WillRelease()