Description:

This type is used for debugging and asserting ALib lock (mutex) types. With debug compilations the non-shared lock types hold one member of this struct, which aggregates all debug information.

Definition at line 17 of file dbgasserters.hpp.

#include <dbgasserters.hpp>

Inheritance diagram for alib::threads::DbgLockAsserter:

[legend]

Collaboration diagram for alib::threads::DbgLockAsserter:

[legend]

Inner Type Index:
struct	ActionInfo
	Collects caller info and the sequence number of actions. More...

Public Static Field Index:
static const char *	ASSERTION_FORMAT

Public Field Index:
ActionInfo	Acq
	Source location of the most recent acquirement.
std::atomic< int >	ActionCounter {1}
	Counter of the actions.
std::atomic< int >	CntAcquirements {0}
	The number of shared acquirements.
const char *	Name ="<unnamed>"
int	RecursionLimit =10
ActionInfo	Rel
	Source location of the most recent release.
Ticks::Duration	WaitTimeLimit = Ticks::Duration::FromAbsoluteSeconds(2)

Public Method Index:
virtual	~DbgLockAsserter ()
	Destructor.
void	AssertNotOwning (const CallerInfo &assertCI, const CallerInfo &ci, const char *headline)
void	AssertOwned (const CallerInfo &assertCI, const CallerInfo &ci)
virtual void	DoAssert (int type, const CallerInfo &assertCI, const CallerInfo &ci, const char *headline)
Thread *	GetOwner () const
bool	IsOwnedByCurrentThread () const
void	Release (const CallerInfo &assertCI, const CallerInfo &requestCI)
void	SetOwner (const CallerInfo &assertCI, const CallerInfo &requestCI)
void	SetRecursiveOwner (const CallerInfo &assertCI, const CallerInfo &requestCI)
bool	WillRelease () const noexcept

Field Details:

◆ Acq

ActionInfo alib::threads::DbgLockAsserter::Acq

Source location of the most recent acquirement.

Definition at line 33 of file dbgasserters.hpp.

◆ ActionCounter

std::atomic<int> alib::threads::DbgLockAsserter::ActionCounter {1}

Counter of the actions.

Definition at line 24 of file dbgasserters.hpp.

◆ ASSERTION_FORMAT

const char * alib::threads::DbgLockAsserter::ASSERTION_FORMAT

static

Initial value:

                                            =
"Multi-Threading {} in Lock \"{}\""   "\n"
"                Message: {}"         "\n"
"   In (Member-)Function: {}"         "\n"
"               Is Owned: {} ({})"    "\n"
                                      "\n"
"              Called By: {}::{}"     "\n"
"                     At: {}:{}"      "\n"
"                 Thread: {}"         "\n"
                                      "\n"
"  Latest Acquisition By: {}::{}"     "\n"
"                     At: {}:{}"      "\n"
"           Seq / Thread: {} / {}"    "\n"
"      Latest Release By: {}:{}"      "\n"
"                     At: {}:{}"      "\n"
"           Seq / Thread: {} / {}"    "\n"

The format string used to write exceptions to the console. This string can be changed if the source information is not "clickable" in a user's development environment.

The default string is optimized for JetBrains CLion and is defined as:

Multi-Threading {} in Lock \"{}\"
                Message: {}
   In (Member-)Function: {}
               Is Owned: {} ({})

              Called By: {}::{}
                     At: {}:{}
                 Thread: {}

  Latest Acquisition By: {}::{}
                     At: {}:{}
           Seq / Thread: {} / {}
      Latest Release By: {}:{}
                     At: {}:{}
           Seq / Thread: {} / {}

The placeholder fields that this format string refers to are set as follows:

0: String "Assertion" or "Warning"
1: Debug-name of the lock.
2: Headline.
3: Function name.
4: Is acquired (true/false).
5: number of acquirements.
6-10: CallerInfo of caller.
11-16: ActionInfo of the latest acquisition.
17-22: ActionInfo of the latest release.

Definition at line 72 of file dbgasserters.hpp.

◆ CntAcquirements

std::atomic<int> alib::threads::DbgLockAsserter::CntAcquirements {0}

The number of shared acquirements.

Definition at line 25 of file dbgasserters.hpp.

◆ Name

const char* alib::threads::DbgLockAsserter::Name ="<unnamed>"

The name of this Lock. Set to "<unnamed>" by default. Used for debug-output. For automatic pruning of changes to this name, macro ALIB_DBG should be used.

Definition at line 23 of file dbgasserters.hpp.

◆ RecursionLimit

int alib::threads::DbgLockAsserter::RecursionLimit =10

Limit of recursions. If the limit is reached or a multiple of it, an ALib Warning is raised. Defaults is 10. To disable, set to 0.

Available only in debug versions of ALib.

Definition at line 86 of file dbgasserters.hpp.

◆ Rel

ActionInfo alib::threads::DbgLockAsserter::Rel

Source location of the most recent release.

Definition at line 34 of file dbgasserters.hpp.

◆ WaitTimeLimit

Ticks::Duration alib::threads::DbgLockAsserter::WaitTimeLimit = Ticks::Duration::FromAbsoluteSeconds(2)

This is a threshold that causes non-timed Acquire() methods to raise a ALib Warning in debug-builds in case a thread is blocked longer than the given duration.

To disable warnings in cases that high block times are suitable, set this value to 0. The default value is two seconds.

Definition at line 80 of file dbgasserters.hpp.

Constructor(s) / Destructor Details:

◆ ~DbgLockAsserter()

virtual alib::threads::DbgLockAsserter::~DbgLockAsserter ( )

inlinevirtual

Destructor.

Definition at line 89 of file dbgasserters.hpp.

Here is the call graph for this function:

Method Details:

◆ AssertNotOwning()

void alib::threads::DbgLockAsserter::AssertNotOwning	(	const CallerInfo &	assertCI,
		const CallerInfo &	ci,
		const char *	headline )

inline

Asserts that this lock is not owned by the thread in ci.

Parameters

assertCI	Location where the assertion is placed.
ci	Location of the call to the method that asserted.
headline	The message.

Definition at line 175 of file dbgasserters.hpp.

Here is the call graph for this function:

◆ AssertOwned()

void alib::threads::DbgLockAsserter::AssertOwned	(	const CallerInfo &	assertCI,
		const CallerInfo &	ci )

inline

Asserts that CntAcquirements is not 0

Parameters

assertCI	Location where the assertion is placed.
ci	Location of the call to the method that asserted.

Definition at line 135 of file dbgasserters.hpp.

Here is the call graph for this function:

◆ DoAssert()

void alib::threads::DbgLockAsserter::DoAssert	(	int	type,
		const CallerInfo &	assertCI,
		const CallerInfo &	ci,
		const char *	headline )

virtual

Collects assertion info and raises a warning or error.

See also: Field ASSERTION_FORMAT which allows changing the output format to achieve 'clickable' assertion messages.

Parameters

type	0= assertion, 1= warning.
assertCI	Location where the assertion is placed.
ci	Location of the call to the method that asserted.
headline	The message.

Reimplemented in alib::threads::DbgSharedLockAsserter.

Definition at line 59 of file dbgasserters.cpp.

Here is the call graph for this function:

◆ GetOwner()

Thread * alib::threads::DbgLockAsserter::GetOwner ( ) const

Returns a pointer the owning thread.

Available only in debug-builds.

Returns: Pointer to the owning thread, or nullptr if not owned.

Definition at line 8 of file dbgasserters.cpp.

Here is the call graph for this function:

◆ IsOwnedByCurrentThread()

bool alib::threads::DbgLockAsserter::IsOwnedByCurrentThread ( ) const

inline

Returns true if the current owner is the current thread.

Available only in debug-builds.

Returns: true, if the lock is owned by this thread, false if it is owned by another thread or not owned.

Definition at line 104 of file dbgasserters.hpp.

◆ Release()

void alib::threads::DbgLockAsserter::Release	(	const CallerInfo &	assertCI,
		const CallerInfo &	requestCI )

inline

Asserts that this lock is owned by the thread in ci.

Parameters

assertCI	Location where the release is implemented.
requestCI	Location where the release was requested (the caller of assertCI)

Definition at line 163 of file dbgasserters.hpp.

Here is the call graph for this function:

◆ SetOwner()

void alib::threads::DbgLockAsserter::SetOwner	(	const CallerInfo &	assertCI,
		const CallerInfo &	requestCI )

inline

Sets the given caller as the current owner. Asserts that CntAcquirements is 0 when called.

Parameters

assertCI	Location where ownership was implemented (usually the lock).
requestCI	Location where ownership was requested (the caller of assertCI)

Definition at line 145 of file dbgasserters.hpp.

Here is the call graph for this function:

◆ SetRecursiveOwner()

void alib::threads::DbgLockAsserter::SetRecursiveOwner	(	const CallerInfo &	assertCI,
		const CallerInfo &	requestCI )

Sets the given caller as the current owner. Asserts that either CntAcquirements is 0 or the current owner is the same as in parameter requestCI.

Parameters

assertCI	Location where ownership was implemented (usually the lock).
requestCI	Location where ownership was requested (the caller of assertCI)

Definition at line 135 of file dbgasserters.cpp.

Here is the call graph for this function:

◆ WillRelease()

bool alib::threads::DbgLockAsserter::WillRelease ( ) const

inlinenoexcept

Returns true if this is a non-recursive lock or a recursive instance which is acquired exactly once.
Available only in debug-builds.

Note: This method is not (and cannot) be synchronized. Consequently, a reliable result is only guaranteed in case IsOwnedByCurrentThread returns true before this method is invoked.

Returns: true if the next release will free this lock, false otherwise.

Definition at line 117 of file dbgasserters.hpp.

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

Description:

Inner Type Index:

Public Static Field Index:

Public Field Index:

Public Method Index:

Field Details:

◆ Acq

◆ ActionCounter

◆ ASSERTION_FORMAT

◆ CntAcquirements

◆ Name

◆ RecursionLimit

◆ Rel

◆ WaitTimeLimit

Constructor(s) / Destructor Details:

◆ ~DbgLockAsserter()

Method Details:

◆ AssertNotOwning()

◆ AssertOwned()

◆ DoAssert()

◆ GetOwner()

◆ IsOwnedByCurrentThread()

◆ Release()

◆ SetOwner()

◆ SetRecursiveOwner()

◆ WillRelease()