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.inl.

Inheritance diagram for alib::threads::DbgLockAsserter:

[legend]

Collaboration diagram for alib::threads::DbgLockAsserter:

[legend]

Public Static Field Index:
static ALIB_DLL const char *	ASSERTION_FORMAT

Public Field Index:
CallerInfo	AcqCI
	Source location of the most recent acquirement.

std::atomic< int >	CntAcquirements {0}
	The number of shared acquirements.

const char *	Name ="<unnamed>"

int	RecursionLimit =10

CallerInfo	RelCI
	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 ALIB_DLL void	DoAssert (int type, const CallerInfo &assertCI, const CallerInfo &ci, const char *headline)

ALIB_DLL Thread *	GetOwner () const

bool	IsOwnedByCurrentThread () const

void	Release (const CallerInfo &assertCI, const CallerInfo &requestCI)

void	SetOwner (const CallerInfo &assertCI, const CallerInfo &requestCI)

ALIB_DLL void	SetRecursiveOwner (const CallerInfo &assertCI, const CallerInfo &requestCI)

bool	WillRelease () const noexcept

Field Details:

◆ AcqCI

CallerInfo alib::threads::DbgLockAsserter::AcqCI

Source location of the most recent acquirement.

Definition at line 24 of file dbgasserters.inl.

◆ 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"
"                 Thread: {}"         "\n"
"      Latest Release By: {}:{}"      "\n"
"                     At: {}:{}"      "\n"
"                 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: {}:{}
                 Thread: {}
      Latest Release By: {}:{}
                     At: {}:{}
                 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-15: CallerInfo of the latest acquisition.
16-20: CallerInfo of the latest release.

Definition at line 65 of file dbgasserters.inl.

◆ CntAcquirements

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

The number of shared acquirements.

Definition at line 27 of file dbgasserters.inl.

◆ 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.inl.

◆ 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 79 of file dbgasserters.inl.

◆ RelCI

CallerInfo alib::threads::DbgLockAsserter::RelCI

Source location of the most recent release.

Definition at line 25 of file dbgasserters.inl.

◆ 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 73 of file dbgasserters.inl.

Constructor(s) / Destructor Details:

◆ ~DbgLockAsserter()

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

inlinevirtual

Destructor.

Definition at line 82 of file dbgasserters.inl.

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 166 of file dbgasserters.inl.

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 128 of file dbgasserters.inl.

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 84 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 33 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 97 of file dbgasserters.inl.

◆ 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 155 of file dbgasserters.inl.

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 138 of file dbgasserters.inl.

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 160 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 110 of file dbgasserters.inl.

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

Description:

Public Static Field Index:

Public Field Index:

Public Method Index:

Field Details:

◆ AcqCI

◆ ASSERTION_FORMAT

◆ CntAcquirements

◆ Name

◆ RecursionLimit

◆ RelCI

◆ WaitTimeLimit

Constructor(s) / Destructor Details:

◆ ~DbgLockAsserter()

Method Details:

◆ AssertNotOwning()

◆ AssertOwned()

◆ DoAssert()

◆ GetOwner()

◆ IsOwnedByCurrentThread()

◆ Release()

◆ SetOwner()

◆ SetRecursiveOwner()

◆ WillRelease()