Description:

This class supports detecting a racing condition in multithreaded applications. For this, entering and exiting of critical sections is tracked in either "write" or "read only" mode. The interface methods are named in accordance with types Owner (Acquire/Release) and OwnerShared (AcquireShared/ReleaseShared).

With the use of atomic counters, both pairs of acquirement are reentrant, which simplifies the use of this type. Furthermore, it is allowed to gain read access after write access by the same thread was acquired. The reverse is not allowed: If the first read access was registered, a subsequent write access will be asserted.

The type becomes empty, and thus any call will be optimized out in case the compiler-symbol ALIB_DEBUG_CRITICAL_SECTIONS is not set. Nevertheless, it is recommended to exclusively use the ALib Module Threads Macros when using this type, as those fully guarantee that any use of this type is pruned with release compilations. Only in exclamatory cases, these macros may not be flexible enough for use.

In case critical sections that are protected using this class are in fact protected by one of the ALib mutex types, it can furthermore be asserted that such mutex is acquired when a section is entered. For this, assign the instance to field DCSLock. A lock-instance may be assigned to more than one DbgCriticalSections instance.

If the compiler-symbol ALIB_DEBUG_CRITICAL_SECTIONS is set, besides counting owners and readers, and raising corresponding assertions, the type can be enabled to simulate some workload on the using machine. For this, a thread can be forced to either yield to the system or even to sleep a given number of nanoseconds before continuing execution. This increases the probability of (detecting) racing conditions.
To activate this feature for all instances, namespace variable DBG_CRITICAL_SECTION_YIELD_OR_SLEEP_TIME_IN_NS is to be adjusted. Per-instance adjustments can be made by setting the field DCSYieldOrSleepTimeInNS.

The output format of assertions should be 'clickable' inside a users' IDE. The default output string is optimized for JetBrains CLion and can be changed by manipulating the member ASSERTION_FORMAT.

See also: Chapter 1.4 Assertions With Debug-Builds of the Programmer's Manual of module ALib Threads.

Definition at line 63 of file dbgcriticalsections.inl.

Inheritance diagram for alib::lang::DbgCriticalSections:

[legend]

Collaboration diagram for alib::lang::DbgCriticalSections:

[legend]

Inner Type Index:
struct	AssociatedLock

Public Static Field Index:
static ALIB_DLL const char *	ASSERTION_FORMAT

Public Field Index:
CallerInfo	DCSAcq
	Source location of acquirement.

AssociatedLock *	DCSLock {nullptr}

const char *	DCSName
	The name of this DCS. Used for debug-output.

std::atomic< int >	DCSReaderCnt {0}
	Tracks enter/exit calls of readers.

CallerInfo	DCSRel
	Source location of the last "reader" seen.

CallerInfo	DCSSAcq
	Source location of acquirement.

CallerInfo	DCSSRel
	Source location of the last "reader" seen.

std::atomic< int >	DCSWriterCnt {0}
	Tracks enter/exit calls (including readers)

int	DCSYieldOrSleepTimeInNS = -1

Public Method Index:
	DbgCriticalSections (const char *name)

	~DbgCriticalSections ()
	Destructor. Checks that this instance is unused.

ALIB_DLL void	Acquire (const CallerInfo &ci) const

ALIB_DLL void	AcquireShared (const CallerInfo &ci) const

ALIB_DLL void	doAssert (bool cond, const CallerInfo &ciAssert, const CallerInfo &ci, const char *headline) const

ALIB_DLL void	Release (const CallerInfo &ci) const

ALIB_DLL void	ReleaseShared (const CallerInfo &ci) const

void	yieldOrSleep () const

Field Details:

◆ ASSERTION_FORMAT

const char * alib::lang::DbgCriticalSections::ASSERTION_FORMAT

static

Initial value:

=
"Assertion in Critical Section \"{}\""       "\n"
"                       Message: {}"         "\n"
"          In (Member-)Function: {}"         "\n"
"                      Is Owned: {} ({})"    "\n"
"               Is Shared 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"
                                             "\n"
"  Latest Shared Acquisition By: {}::{}"     "\n"
"                            At: {}:{}"      "\n"
"                        Thread: {}"         "\n"
"       Latest SharedRelease 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:

Assertion in Critical Section \"{}\"
                       Message: {}
          In (Member-)Function: {}
                      Is Owned: {} ({})
               Is Shared Owned: {} ({})

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

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

  Latest Shared Acquisition By: {}::{}
                            At: {}:{}
                        Thread: {}
       Latest SharedRelease By: {}::{}
                            At: {}:{}
                        Thread: {}

Definition at line 137 of file dbgcriticalsections.inl.

◆ DCSAcq

CallerInfo alib::lang::DbgCriticalSections::DCSAcq

mutable

Source location of acquirement.

Definition at line 95 of file dbgcriticalsections.inl.

◆ DCSLock

AssociatedLock* alib::lang::DbgCriticalSections::DCSLock {nullptr}

A union of pointers to different lock types. Those can optionally be attached to be checked whether a lock is duly acquired.

Definition at line 102 of file dbgcriticalsections.inl.

◆ DCSName

const char* alib::lang::DbgCriticalSections::DCSName

The name of this DCS. Used for debug-output.

Definition at line 86 of file dbgcriticalsections.inl.

◆ DCSReaderCnt

std::atomic<int> alib::lang::DbgCriticalSections::DCSReaderCnt {0}

mutable

Tracks enter/exit calls of readers.

Definition at line 94 of file dbgcriticalsections.inl.

◆ DCSRel

CallerInfo alib::lang::DbgCriticalSections::DCSRel

mutable

Source location of the last "reader" seen.

Definition at line 96 of file dbgcriticalsections.inl.

◆ DCSSAcq

CallerInfo alib::lang::DbgCriticalSections::DCSSAcq

mutable

Source location of acquirement.

Definition at line 97 of file dbgcriticalsections.inl.

◆ DCSSRel

CallerInfo alib::lang::DbgCriticalSections::DCSSRel

mutable

Source location of the last "reader" seen.

Definition at line 98 of file dbgcriticalsections.inl.

◆ DCSWriterCnt

std::atomic<int> alib::lang::DbgCriticalSections::DCSWriterCnt {0}

mutable

Tracks enter/exit calls (including readers)

Definition at line 93 of file dbgcriticalsections.inl.

◆ DCSYieldOrSleepTimeInNS

int alib::lang::DbgCriticalSections::DCSYieldOrSleepTimeInNS = -1

If positive, the value found here, overwrites what is given with namespace variable DBG_CRITICAL_SECTION_YIELD_OR_SLEEP_TIME_IN_NS.
Defaults to -1.

Definition at line 91 of file dbgcriticalsections.inl.

Constructor(s) / Destructor Details:

◆ DbgCriticalSections()

alib::lang::DbgCriticalSections::DbgCriticalSections ( const char * name )

inline

Constructor.

Parameters

name	The name to display with assertions.

Definition at line 172 of file dbgcriticalsections.inl.

◆ ~DbgCriticalSections()

alib::lang::DbgCriticalSections::~DbgCriticalSections ( )

inline

Destructor. Checks that this instance is unused.

Definition at line 175 of file dbgcriticalsections.inl.

Here is the call graph for this function:

Method Details:

◆ Acquire()

void alib::lang::DbgCriticalSections::Acquire ( const CallerInfo & ci ) const

Increases the DCSWriterCnt and checks for potential assertions.

Parameters

ci	Caller information.

Definition at line 73 of file dbgcriticalsections.cpp.

Here is the call graph for this function:

◆ AcquireShared()

void alib::lang::DbgCriticalSections::AcquireShared ( const CallerInfo & ci ) const

Increases DCSReaderCnt and checks for potential assertions.

Parameters

ci	Caller information.

Definition at line 94 of file dbgcriticalsections.cpp.

Here is the call graph for this function:

◆ doAssert()

void alib::lang::DbgCriticalSections::doAssert	(	bool	cond,
		const CallerInfo &	ciAssert,
		const CallerInfo &	ci,
		const char *	headline ) const

Asserts the condition and if false, raises an ALib error.

Parameters

cond	The condition to assert.
ciAssert	Caller information of the assertion in this class.
ci	Caller information.
headline	The problem that occurred.

Definition at line 57 of file dbgcriticalsections.cpp.

Here is the call graph for this function:

◆ Release()

void alib::lang::DbgCriticalSections::Release ( const CallerInfo & ci ) const

Decreases the DCSWriterCnt and checks for potential assertions.

Parameters

ci	Caller information.

Definition at line 85 of file dbgcriticalsections.cpp.

Here is the call graph for this function:

◆ ReleaseShared()

void alib::lang::DbgCriticalSections::ReleaseShared ( const CallerInfo & ci ) const

Decreases DCSReaderCnt and checks for potential assertions.

Parameters

ci	Caller information.

Definition at line 107 of file dbgcriticalsections.cpp.

Here is the call graph for this function:

◆ yieldOrSleep()

void alib::lang::DbgCriticalSections::yieldOrSleep ( ) const

inline

Evaluates DCSYieldOrSleepTimeInNS, respectively, if this is negative, DBG_CRITICAL_SECTION_YIELD_OR_SLEEP_TIME_IN_NS. For value

0, nothing is done, for
1, a yield into the system is done, and for
values greater than 1, the calling thread sleeps for the corresponding number of nanoseconds sleep time.

Definition at line 149 of file dbgcriticalsections.inl.

Here is the call graph for this function:

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:

◆ ASSERTION_FORMAT

◆ DCSAcq

◆ DCSLock

◆ DCSName

◆ DCSReaderCnt

◆ DCSRel

◆ DCSSAcq

◆ DCSSRel

◆ DCSWriterCnt

◆ DCSYieldOrSleepTimeInNS

Constructor(s) / Destructor Details:

◆ DbgCriticalSections()

◆ ~DbgCriticalSections()

Method Details:

◆ Acquire()

◆ AcquireShared()

◆ doAssert()

◆ Release()

◆ ReleaseShared()

◆ yieldOrSleep()