ThreadLockNR Class Reference

Description:

---

This class is a simple wrapper around C++ standard library type std::mutex and hence allows mutual exclusive access to resources, by protecting data from concurrent thread access.

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 use is highly simplified with macros ALIB_LOCK and ALIB_LOCK_WITH.

This class allows to be "disabled" with method SetSafeness. The objective here is to gain execution speed, as thread synchronization causes "relatively" expensive system calls. An interface of a class might this way be designed to be "thread safe" by default, but in the case that a user of such class assures that an individual instance is used in a context that is free of race conditions, a corresponding lock might be disabled.

This class does not allow repeated calls to method Acquire without prior invocations of Release. Repeated acquisitions cause undefined behavior. With debug builds, an assertion is raised when Acquire is invoked while the lock is already acquired.

Due to this limitation, the class performs several times faster than sibling class ThreadLock . For very time critical code sections which are invoked often in relation to their length, the use of this class might be considered, taking its limitation into account.

Definition at line 63 of file threadlocknr.hpp.

#include <threadlocknr.hpp>

Collaboration diagram for ThreadLockNR:

Public Method Index:
	ThreadLockNR (lang::Safeness pSafeness=lang::Safeness::Safe)
void	Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)
lang::Safeness	GetSafeness () const
void	Release ()
void	SetSafeness (lang::Safeness pSafeness)

Field Details:

dbgIsAcquiredBy

std::thread::id dbgIsAcquiredBy

protected

Id of a thread that currently acquired this object's mutex, used to detect forbidden multiple (nested) acquirements.Available only in debug compilations.

Definition at line 85 of file threadlocknr.hpp.

DbgOwnerFile

NCString DbgOwnerFile =nullptr

protected

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

Definition at line 74 of file threadlocknr.hpp.

DbgOwnerFunc

NCString DbgOwnerFunc =nullptr

protected

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

Definition at line 80 of file threadlocknr.hpp.

DbgOwnerLine

int DbgOwnerLine

protected

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

Definition at line 77 of file threadlocknr.hpp.

mutex

std::mutex mutex

protected

The std::mutex used for locking.

Definition at line 67 of file threadlocknr.hpp.

safeness

lang::Safeness safeness

protected

The safeness mode.

Definition at line 70 of file threadlocknr.hpp.

Constructor(s) / Destructor Details::

ThreadLockNR()

ThreadLockNR ( lang::Safeness pSafeness = lang::Safeness::Safe )

inlineexplicit

---

Default constructor.

Parameters

pSafeness

The safeness mode. See SetSafeness for more information.

Definition at line 95 of file threadlocknr.hpp.

Method Details:

Acquire()

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

inline

---

A 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 not supported and lead to undefined behavior.

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.

Definition at line 118 of file threadlocknr.hpp.

Here is the call graph for this function:

GetSafeness()

lang::Safeness GetSafeness ( ) const

inline

---

Query the safeness mode of this object.

Returns

The safeness mode of this object.

Definition at line 192 of file threadlocknr.hpp.

Release()

void Release ( )

inline

---

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.

Definition at line 141 of file threadlocknr.hpp.

Here is the call graph for this function:

SetSafeness()

void SetSafeness ( lang::Safeness pSafeness )

inline

---

If parameter is 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 is executed in a single threaded environment or otherwise it is assured that no concurrent thread access is performed.

Note that "relative expensive" means: locking is not "really" expensive. This is only for the rare case that your critical section is very, very frequently executed.

Parameters

pSafeness

Denotes the new safeness mode.

Definition at line 171 of file threadlocknr.hpp.

Here is the call graph for this function:

---

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

• threadlocknr.hpp