ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
lock.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_threads of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8#if !ALIB_SINGLE_THREADED
9ALIB_EXPORT namespace alib { namespace threads {
10
11// =================================================================================================
12/// This class is a simple wrapper around C++ standard library type \c std::mutex.
13/// Thus, it is used to implement <em>mutual exclusive access</em> to resources by protecting
14/// critical code sections from being executed in parallel in concurrent threads.
15///
16/// When a pair of #Acquire and #Release invocations is performed within the same code block, then
17/// it is recommended to use a stack instantiation of class \alib{lang;Owner} to acquire and release
18/// objects of this class. Such a use is highly simplified with macros \ref ALIB_LOCK and
19/// \ref ALIB_LOCK_WITH.
20///
21/// This class does not allow nested calls to the method #Acquire - method #Release has to be
22/// invoked (from within the same thread that acquired this mutex), before any other thread can
23/// again gain access. Nested acquisitions constitute undefined behavior.
24///
25/// \par Debug-Features
26/// Public member #Dbg is available with debug-compilations. It offers the following features:
27/// - An assertion is raised when nested use is performed.
28/// - The object stores the actual owning thread and the source code position of the last
29/// acquirement.
30/// - Releasing non-acquired instances, as well as destructing acquired one, raise an assertion.
31/// - Field \alib{threads::DbgLockAsserter;WaitTimeLimit} enables the raise of \alib warnings in
32/// case a certain wait time is exceeded.
33/// Note that instead of wrapping \c std::mutex, with debug-compilations class
34/// \c std::timed_mutex is wrapped.
35///
36/// \par Availability
37/// This type is not available if the compiler-symbol \ref ALIB_SINGLE_THREADED is set.
38///
39/// @see
40/// - Chapter \ref alib_threads_locks of the Programmer's Manual of the module \alib_threads_nl.
41/// - Chapter \ref alib_manual_appendix_callerinfo of the General Programmer's Manual.
42/// - For this class, as well as for all other five lock types of this module, a
43/// \ref alibtools_debug_helpers_gdb "pretty printer" for the GNU debugger is provided.
44// =================================================================================================
45class Lock
48#endif
49{
50 protected:
51 #if !ALIB_DEBUG && !DOXYGEN
52 std::mutex mutex; // the only member in release compilations
53
54 #else
55 #if DOXYGEN
56 /// The internal object to lock on.
57 /// \note With debug-compilations, this is of type <c>std::timed_mutex</c>.
58 std::mutex mutex;
59 #else
60 std::timed_mutex mutex;
61 #endif
62
63 public:
64 /// The debug tool instance.
66 #endif
67
68 public:
69
70 #if ALIB_DEBUG_CRITICAL_SECTIONS
71 /// Destructor. With debug-compilations, asserts that this lock is not acquired.
72 ~Lock() override
73 { Dbg.AssertNotOwned( ALIB_CALLER, ALIB_CALLER, "Destructing acquired lock" ); }
74
75 /// @return \c true if the lock is acquired (in non-shared mode), \c false otherwise.
76 ALIB_DLL virtual bool DCSIsAcquired() const override;
77
78 /// @return \c true if the lock is shared-acquired (by at least any thread).
79 /// Otherwise, returns \c false.
80 ALIB_DLL virtual bool DCSIsSharedAcquired() const override;
81
82 #elif ALIB_DEBUG
83 ~Lock()
84 { Dbg.AssertNotOwned( ALIB_CALLER, ALIB_CALLER, "Destructing acquired lock" ); }
85 #endif
86
87 #if ALIB_DEBUG || DOXYGEN
88 /// Acquires this lock.
89 /// In the case that this object is already owned by another thread, the invoking thread is
90 /// suspended until ownership can be gained.
91 /// Multiple (nested) calls to this method are not supported and lead to undefined behavior.
92 ///
93 /// \par Debug Parameter:
94 /// Pass macro \ref ALIB_CALLER_PRUNED with invocations.
97
98 /// Tries to acquire this lock.
99 /// Multiple (nested) successful calls to this method or method #Acquire are not supported and
100 /// lead to undefined behavior.
101 ///
102 /// \par Debug Parameter:
103 /// Pass macro \ref ALIB_CALLER_PRUNED with invocations.
104 ///
105 /// @return \c true if the lock was not acquired by a different thread and thus, this
106 /// call was successful. \c false otherwise.
108 [[nodiscard]]
110
111 /// Releases ownership of this object.
112 /// If this method is invoked on an object that is not acquired, in debug-compilations an
113 /// assertion is raised.
114 /// In release compilations, this leads to undefined behavior.
115 ///
116 /// \par Debug Parameter:
117 /// Pass macro \ref ALIB_CALLER_PRUNED with invocations.
120 #else
121 void Acquire() { mutex.lock(); }
122 [[nodiscard]] bool TryAcquire() { return mutex.try_lock(); }
123 void Release() { mutex.unlock(); }
124 #endif
125};
126
128
129} // namespace alib[threads]
130
131/// Type alias in namespace \b alib.
133
134} // namespace [alib]
135#endif // !ALIB_SINGLE_THREADED
136
virtual ALIB_DLL bool DCSIsAcquired() const override
Definition locks.cpp:759
virtual ALIB_DLL bool DCSIsSharedAcquired() const override
Definition locks.cpp:760
DbgLockAsserter Dbg
The debug tool instance.
Definition lock.inl:65
std::mutex mutex
Definition lock.inl:58
~Lock() override
Destructor. With debug-compilations, asserts that this lock is not acquired.
Definition lock.inl:72
ALIB_DLL void Release(ALIB_DBG_TAKE_CI)
Definition locks.cpp:99
ALIB_DLL bool TryAcquire(ALIB_DBG_TAKE_CI)
Definition locks.cpp:85
ALIB_DLL void Acquire(ALIB_DBG_TAKE_CI)
Definition locks.cpp:50
#define ALIB_DBG_TAKE_CI
Definition alib.inl:1013
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_CALLER
Definition alib.inl:1001
#define ALIB_EXPORT
Definition alib.inl:488
#define ALIB_DEBUG_CRITICAL_SECTIONS
Definition prepro.md:43
ALIB_DLL Lock STD_IOSTREAMS_LOCK
Definition locks.cpp:44
threads::Lock Lock
Type alias in namespace alib.
Definition lock.inl:132
void AssertNotOwned(const CallerInfo &assertCI, const CallerInfo &ci, const char *headline)