1 // Copyright 2017 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 // -----------------------------------------------------------------------------
16 // mutex.h
17 // -----------------------------------------------------------------------------
18 //
19 // This header file defines a `Mutex` -- a mutually exclusive lock -- and the
20 // most common type of synchronization primitive for facilitating locks on
21 // shared resources. A mutex is used to prevent multiple threads from accessing
22 // and/or writing to a shared resource concurrently.
23 //
24 // Unlike a `std::mutex`, the Abseil `Mutex` provides the following additional
25 // features:
26 // * Conditional predicates intrinsic to the `Mutex` object
27 // * Shared/reader locks, in addition to standard exclusive/writer locks
28 // * Deadlock detection and debug support.
29 //
30 // The following helper classes are also defined within this file:
31 //
32 // MutexLock - An RAII wrapper to acquire and release a `Mutex` for exclusive/
33 // write access within the current scope.
34 // ReaderMutexLock
35 // - An RAII wrapper to acquire and release a `Mutex` for shared/read
36 // access within the current scope.
37 //
38 // WriterMutexLock
39 // - Alias for `MutexLock` above, designed for use in distinguishing
40 // reader and writer locks within code.
41 //
42 // In addition to simple mutex locks, this file also defines ways to perform
43 // locking under certain conditions.
44 //
45 // Condition - (Preferred) Used to wait for a particular predicate that
46 // depends on state protected by the `Mutex` to become true.
47 // CondVar - A lower-level variant of `Condition` that relies on
48 // application code to explicitly signal the `CondVar` when
49 // a condition has been met.
50 //
51 // See below for more information on using `Condition` or `CondVar`.
52 //
53 // Mutexes and mutex behavior can be quite complicated. The information within
54 // this header file is limited, as a result. Please consult the Mutex guide for
55 // more complete information and examples.
56
57 #ifndef ABSL_SYNCHRONIZATION_MUTEX_H_
58 #define ABSL_SYNCHRONIZATION_MUTEX_H_
59
60 #include <atomic>
61 #include <cstdint>
62 #include <string>
63
64 #include "absl/base/const_init.h"
65 #include "absl/base/internal/identity.h"
66 #include "absl/base/internal/low_level_alloc.h"
67 #include "absl/base/internal/thread_identity.h"
68 #include "absl/base/internal/tsan_mutex_interface.h"
69 #include "absl/base/port.h"
70 #include "absl/base/thread_annotations.h"
71 #include "absl/synchronization/internal/kernel_timeout.h"
72 #include "absl/synchronization/internal/per_thread_sem.h"
73 #include "absl/time/time.h"
74
75 // Decide if we should use the non-production implementation because
76 // the production implementation hasn't been fully ported yet.
77 #ifdef ABSL_INTERNAL_USE_NONPROD_MUTEX
78 #error ABSL_INTERNAL_USE_NONPROD_MUTEX cannot be directly set
79 #elif defined(ABSL_LOW_LEVEL_ALLOC_MISSING)
80 #define ABSL_INTERNAL_USE_NONPROD_MUTEX 1
81 #include "absl/synchronization/internal/mutex_nonprod.inc"
82 #endif
83
84 namespace absl {
85 ABSL_NAMESPACE_BEGIN
86
87 class Condition;
88 struct SynchWaitParams;
89
90 // -----------------------------------------------------------------------------
91 // Mutex
92 // -----------------------------------------------------------------------------
93 //
94 // A `Mutex` is a non-reentrant (aka non-recursive) Mutually Exclusive lock
95 // on some resource, typically a variable or data structure with associated
96 // invariants. Proper usage of mutexes prevents concurrent access by different
97 // threads to the same resource.
98 //
99 // A `Mutex` has two basic operations: `Mutex::Lock()` and `Mutex::Unlock()`.
100 // The `Lock()` operation *acquires* a `Mutex` (in a state known as an
101 // *exclusive* -- or write -- lock), while the `Unlock()` operation *releases* a
102 // Mutex. During the span of time between the Lock() and Unlock() operations,
103 // a mutex is said to be *held*. By design all mutexes support exclusive/write
104 // locks, as this is the most common way to use a mutex.
105 //
106 // The `Mutex` state machine for basic lock/unlock operations is quite simple:
107 //
108 // | | Lock() | Unlock() |
109 // |----------------+------------+----------|
110 // | Free | Exclusive | invalid |
111 // | Exclusive | blocks | Free |
112 //
113 // Attempts to `Unlock()` must originate from the thread that performed the
114 // corresponding `Lock()` operation.
115 //
116 // An "invalid" operation is disallowed by the API. The `Mutex` implementation
117 // is allowed to do anything on an invalid call, including but not limited to
118 // crashing with a useful error message, silently succeeding, or corrupting
119 // data structures. In debug mode, the implementation attempts to crash with a
120 // useful error message.
121 //
122 // `Mutex` is not guaranteed to be "fair" in prioritizing waiting threads; it
123 // is, however, approximately fair over long periods, and starvation-free for
124 // threads at the same priority.
125 //
126 // The lock/unlock primitives are now annotated with lock annotations
127 // defined in (base/thread_annotations.h). When writing multi-threaded code,
128 // you should use lock annotations whenever possible to document your lock
129 // synchronization policy. Besides acting as documentation, these annotations
130 // also help compilers or static analysis tools to identify and warn about
131 // issues that could potentially result in race conditions and deadlocks.
132 //
133 // For more information about the lock annotations, please see
134 // [Thread Safety Analysis](http://clang.llvm.org/docs/ThreadSafetyAnalysis.html)
135 // in the Clang documentation.
136 //
137 // See also `MutexLock`, below, for scoped `Mutex` acquisition.
138
139 class ABSL_LOCKABLE Mutex {
140 public:
141 // Creates a `Mutex` that is not held by anyone. This constructor is
142 // typically used for Mutexes allocated on the heap or the stack.
143 //
144 // To create `Mutex` instances with static storage duration
145 // (e.g. a namespace-scoped or global variable), see
146 // `Mutex::Mutex(absl::kConstInit)` below instead.
147 Mutex();
148
149 // Creates a mutex with static storage duration. A global variable
150 // constructed this way avoids the lifetime issues that can occur on program
151 // startup and shutdown. (See absl/base/const_init.h.)
152 //
153 // For Mutexes allocated on the heap and stack, instead use the default
154 // constructor, which can interact more fully with the thread sanitizer.
155 //
156 // Example usage:
157 // namespace foo {
158 // ABSL_CONST_INIT Mutex mu(absl::kConstInit);
159 // }
160 explicit constexpr Mutex(absl::ConstInitType);
161
162 ~Mutex();
163
164 // Mutex::Lock()
165 //
166 // Blocks the calling thread, if necessary, until this `Mutex` is free, and
167 // then acquires it exclusively. (This lock is also known as a "write lock.")
168 void Lock() ABSL_EXCLUSIVE_LOCK_FUNCTION();
169
170 // Mutex::Unlock()
171 //
172 // Releases this `Mutex` and returns it from the exclusive/write state to the
173 // free state. Caller must hold the `Mutex` exclusively.
174 void Unlock() ABSL_UNLOCK_FUNCTION();
175
176 // Mutex::TryLock()
177 //
178 // If the mutex can be acquired without blocking, does so exclusively and
179 // returns `true`. Otherwise, returns `false`. Returns `true` with high
180 // probability if the `Mutex` was free.
181 bool TryLock() ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(true);
182
183 // Mutex::AssertHeld()
184 //
185 // Return immediately if this thread holds the `Mutex` exclusively (in write
186 // mode). Otherwise, may report an error (typically by crashing with a
187 // diagnostic), or may return immediately.
188 void AssertHeld() const ABSL_ASSERT_EXCLUSIVE_LOCK();
189
190 // ---------------------------------------------------------------------------
191 // Reader-Writer Locking
192 // ---------------------------------------------------------------------------
193
194 // A Mutex can also be used as a starvation-free reader-writer lock.
195 // Neither read-locks nor write-locks are reentrant/recursive to avoid
196 // potential client programming errors.
197 //
198 // The Mutex API provides `Writer*()` aliases for the existing `Lock()`,
199 // `Unlock()` and `TryLock()` methods for use within applications mixing
200 // reader/writer locks. Using `Reader*()` and `Writer*()` operations in this
201 // manner can make locking behavior clearer when mixing read and write modes.
202 //
203 // Introducing reader locks necessarily complicates the `Mutex` state
204 // machine somewhat. The table below illustrates the allowed state transitions
205 // of a mutex in such cases. Note that ReaderLock() may block even if the lock
206 // is held in shared mode; this occurs when another thread is blocked on a
207 // call to WriterLock().
208 //
209 // ---------------------------------------------------------------------------
210 // Operation: WriterLock() Unlock() ReaderLock() ReaderUnlock()
211 // ---------------------------------------------------------------------------
212 // State
213 // ---------------------------------------------------------------------------
214 // Free Exclusive invalid Shared(1) invalid
215 // Shared(1) blocks invalid Shared(2) or blocks Free
216 // Shared(n) n>1 blocks invalid Shared(n+1) or blocks Shared(n-1)
217 // Exclusive blocks Free blocks invalid
218 // ---------------------------------------------------------------------------
219 //
220 // In comments below, "shared" refers to a state of Shared(n) for any n > 0.
221
222 // Mutex::ReaderLock()
223 //
224 // Blocks the calling thread, if necessary, until this `Mutex` is either free,
225 // or in shared mode, and then acquires a share of it. Note that
226 // `ReaderLock()` will block if some other thread has an exclusive/writer lock
227 // on the mutex.
228
229 void ReaderLock() ABSL_SHARED_LOCK_FUNCTION();
230
231 // Mutex::ReaderUnlock()
232 //
233 // Releases a read share of this `Mutex`. `ReaderUnlock` may return a mutex to
234 // the free state if this thread holds the last reader lock on the mutex. Note
235 // that you cannot call `ReaderUnlock()` on a mutex held in write mode.
236 void ReaderUnlock() ABSL_UNLOCK_FUNCTION();
237
238 // Mutex::ReaderTryLock()
239 //
240 // If the mutex can be acquired without blocking, acquires this mutex for
241 // shared access and returns `true`. Otherwise, returns `false`. Returns
242 // `true` with high probability if the `Mutex` was free or shared.
243 bool ReaderTryLock() ABSL_SHARED_TRYLOCK_FUNCTION(true);
244
245 // Mutex::AssertReaderHeld()
246 //
247 // Returns immediately if this thread holds the `Mutex` in at least shared
248 // mode (read mode). Otherwise, may report an error (typically by
249 // crashing with a diagnostic), or may return immediately.
250 void AssertReaderHeld() const ABSL_ASSERT_SHARED_LOCK();
251
252 // Mutex::WriterLock()
253 // Mutex::WriterUnlock()
254 // Mutex::WriterTryLock()
255 //
256 // Aliases for `Mutex::Lock()`, `Mutex::Unlock()`, and `Mutex::TryLock()`.
257 //
258 // These methods may be used (along with the complementary `Reader*()`
259 // methods) to distingish simple exclusive `Mutex` usage (`Lock()`,
260 // etc.) from reader/writer lock usage.
WriterLock()261 void WriterLock() ABSL_EXCLUSIVE_LOCK_FUNCTION() { this->Lock(); }
262
WriterUnlock()263 void WriterUnlock() ABSL_UNLOCK_FUNCTION() { this->Unlock(); }
264
WriterTryLock()265 bool WriterTryLock() ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(true) {
266 return this->TryLock();
267 }
268
269 // ---------------------------------------------------------------------------
270 // Conditional Critical Regions
271 // ---------------------------------------------------------------------------
272
273 // Conditional usage of a `Mutex` can occur using two distinct paradigms:
274 //
275 // * Use of `Mutex` member functions with `Condition` objects.
276 // * Use of the separate `CondVar` abstraction.
277 //
278 // In general, prefer use of `Condition` and the `Mutex` member functions
279 // listed below over `CondVar`. When there are multiple threads waiting on
280 // distinctly different conditions, however, a battery of `CondVar`s may be
281 // more efficient. This section discusses use of `Condition` objects.
282 //
283 // `Mutex` contains member functions for performing lock operations only under
284 // certain conditions, of class `Condition`. For correctness, the `Condition`
285 // must return a boolean that is a pure function, only of state protected by
286 // the `Mutex`. The condition must be invariant w.r.t. environmental state
287 // such as thread, cpu id, or time, and must be `noexcept`. The condition will
288 // always be invoked with the mutex held in at least read mode, so you should
289 // not block it for long periods or sleep it on a timer.
290 //
291 // Since a condition must not depend directly on the current time, use
292 // `*WithTimeout()` member function variants to make your condition
293 // effectively true after a given duration, or `*WithDeadline()` variants to
294 // make your condition effectively true after a given time.
295 //
296 // The condition function should have no side-effects aside from debug
297 // logging; as a special exception, the function may acquire other mutexes
298 // provided it releases all those that it acquires. (This exception was
299 // required to allow logging.)
300
301 // Mutex::Await()
302 //
303 // Unlocks this `Mutex` and blocks until simultaneously both `cond` is `true`
304 // and this `Mutex` can be reacquired, then reacquires this `Mutex` in the
305 // same mode in which it was previously held. If the condition is initially
306 // `true`, `Await()` *may* skip the release/re-acquire step.
307 //
308 // `Await()` requires that this thread holds this `Mutex` in some mode.
309 void Await(const Condition &cond);
310
311 // Mutex::LockWhen()
312 // Mutex::ReaderLockWhen()
313 // Mutex::WriterLockWhen()
314 //
315 // Blocks until simultaneously both `cond` is `true` and this `Mutex` can
316 // be acquired, then atomically acquires this `Mutex`. `LockWhen()` is
317 // logically equivalent to `*Lock(); Await();` though they may have different
318 // performance characteristics.
319 void LockWhen(const Condition &cond) ABSL_EXCLUSIVE_LOCK_FUNCTION();
320
321 void ReaderLockWhen(const Condition &cond) ABSL_SHARED_LOCK_FUNCTION();
322
WriterLockWhen(const Condition & cond)323 void WriterLockWhen(const Condition &cond) ABSL_EXCLUSIVE_LOCK_FUNCTION() {
324 this->LockWhen(cond);
325 }
326
327 // ---------------------------------------------------------------------------
328 // Mutex Variants with Timeouts/Deadlines
329 // ---------------------------------------------------------------------------
330
331 // Mutex::AwaitWithTimeout()
332 // Mutex::AwaitWithDeadline()
333 //
334 // If `cond` is initially true, do nothing, or act as though `cond` is
335 // initially false.
336 //
337 // If `cond` is initially false, unlock this `Mutex` and block until
338 // simultaneously:
339 // - either `cond` is true or the {timeout has expired, deadline has passed}
340 // and
341 // - this `Mutex` can be reacquired,
342 // then reacquire this `Mutex` in the same mode in which it was previously
343 // held, returning `true` iff `cond` is `true` on return.
344 //
345 // Deadlines in the past are equivalent to an immediate deadline.
346 // Negative timeouts are equivalent to a zero timeout.
347 //
348 // This method requires that this thread holds this `Mutex` in some mode.
349 bool AwaitWithTimeout(const Condition &cond, absl::Duration timeout);
350
351 bool AwaitWithDeadline(const Condition &cond, absl::Time deadline);
352
353 // Mutex::LockWhenWithTimeout()
354 // Mutex::ReaderLockWhenWithTimeout()
355 // Mutex::WriterLockWhenWithTimeout()
356 //
357 // Blocks until simultaneously both:
358 // - either `cond` is `true` or the timeout has expired, and
359 // - this `Mutex` can be acquired,
360 // then atomically acquires this `Mutex`, returning `true` iff `cond` is
361 // `true` on return.
362 //
363 // Negative timeouts are equivalent to a zero timeout.
364 bool LockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
365 ABSL_EXCLUSIVE_LOCK_FUNCTION();
366 bool ReaderLockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
367 ABSL_SHARED_LOCK_FUNCTION();
WriterLockWhenWithTimeout(const Condition & cond,absl::Duration timeout)368 bool WriterLockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
369 ABSL_EXCLUSIVE_LOCK_FUNCTION() {
370 return this->LockWhenWithTimeout(cond, timeout);
371 }
372
373 // Mutex::LockWhenWithDeadline()
374 // Mutex::ReaderLockWhenWithDeadline()
375 // Mutex::WriterLockWhenWithDeadline()
376 //
377 // Blocks until simultaneously both:
378 // - either `cond` is `true` or the deadline has been passed, and
379 // - this `Mutex` can be acquired,
380 // then atomically acquires this Mutex, returning `true` iff `cond` is `true`
381 // on return.
382 //
383 // Deadlines in the past are equivalent to an immediate deadline.
384 bool LockWhenWithDeadline(const Condition &cond, absl::Time deadline)
385 ABSL_EXCLUSIVE_LOCK_FUNCTION();
386 bool ReaderLockWhenWithDeadline(const Condition &cond, absl::Time deadline)
387 ABSL_SHARED_LOCK_FUNCTION();
WriterLockWhenWithDeadline(const Condition & cond,absl::Time deadline)388 bool WriterLockWhenWithDeadline(const Condition &cond, absl::Time deadline)
389 ABSL_EXCLUSIVE_LOCK_FUNCTION() {
390 return this->LockWhenWithDeadline(cond, deadline);
391 }
392
393 // ---------------------------------------------------------------------------
394 // Debug Support: Invariant Checking, Deadlock Detection, Logging.
395 // ---------------------------------------------------------------------------
396
397 // Mutex::EnableInvariantDebugging()
398 //
399 // If `invariant`!=null and if invariant debugging has been enabled globally,
400 // cause `(*invariant)(arg)` to be called at moments when the invariant for
401 // this `Mutex` should hold (for example: just after acquire, just before
402 // release).
403 //
404 // The routine `invariant` should have no side-effects since it is not
405 // guaranteed how many times it will be called; it should check the invariant
406 // and crash if it does not hold. Enabling global invariant debugging may
407 // substantially reduce `Mutex` performance; it should be set only for
408 // non-production runs. Optimization options may also disable invariant
409 // checks.
410 void EnableInvariantDebugging(void (*invariant)(void *), void *arg);
411
412 // Mutex::EnableDebugLog()
413 //
414 // Cause all subsequent uses of this `Mutex` to be logged via
415 // `ABSL_RAW_LOG(INFO)`. Log entries are tagged with `name` if no previous
416 // call to `EnableInvariantDebugging()` or `EnableDebugLog()` has been made.
417 //
418 // Note: This method substantially reduces `Mutex` performance.
419 void EnableDebugLog(const char *name);
420
421 // Deadlock detection
422
423 // Mutex::ForgetDeadlockInfo()
424 //
425 // Forget any deadlock-detection information previously gathered
426 // about this `Mutex`. Call this method in debug mode when the lock ordering
427 // of a `Mutex` changes.
428 void ForgetDeadlockInfo();
429
430 // Mutex::AssertNotHeld()
431 //
432 // Return immediately if this thread does not hold this `Mutex` in any
433 // mode; otherwise, may report an error (typically by crashing with a
434 // diagnostic), or may return immediately.
435 //
436 // Currently this check is performed only if all of:
437 // - in debug mode
438 // - SetMutexDeadlockDetectionMode() has been set to kReport or kAbort
439 // - number of locks concurrently held by this thread is not large.
440 // are true.
441 void AssertNotHeld() const;
442
443 // Special cases.
444
445 // A `MuHow` is a constant that indicates how a lock should be acquired.
446 // Internal implementation detail. Clients should ignore.
447 typedef const struct MuHowS *MuHow;
448
449 // Mutex::InternalAttemptToUseMutexInFatalSignalHandler()
450 //
451 // Causes the `Mutex` implementation to prepare itself for re-entry caused by
452 // future use of `Mutex` within a fatal signal handler. This method is
453 // intended for use only for last-ditch attempts to log crash information.
454 // It does not guarantee that attempts to use Mutexes within the handler will
455 // not deadlock; it merely makes other faults less likely.
456 //
457 // WARNING: This routine must be invoked from a signal handler, and the
458 // signal handler must either loop forever or terminate the process.
459 // Attempts to return from (or `longjmp` out of) the signal handler once this
460 // call has been made may cause arbitrary program behaviour including
461 // crashes and deadlocks.
462 static void InternalAttemptToUseMutexInFatalSignalHandler();
463
464 private:
465 #ifdef ABSL_INTERNAL_USE_NONPROD_MUTEX
466 friend class CondVar;
467
impl()468 synchronization_internal::MutexImpl *impl() { return impl_.get(); }
469
470 synchronization_internal::SynchronizationStorage<
471 synchronization_internal::MutexImpl>
472 impl_;
473 #else
474 std::atomic<intptr_t> mu_; // The Mutex state.
475
476 // Post()/Wait() versus associated PerThreadSem; in class for required
477 // friendship with PerThreadSem.
478 static inline void IncrementSynchSem(Mutex *mu,
479 base_internal::PerThreadSynch *w);
480 static inline bool DecrementSynchSem(
481 Mutex *mu, base_internal::PerThreadSynch *w,
482 synchronization_internal::KernelTimeout t);
483
484 // slow path acquire
485 void LockSlowLoop(SynchWaitParams *waitp, int flags);
486 // wrappers around LockSlowLoop()
487 bool LockSlowWithDeadline(MuHow how, const Condition *cond,
488 synchronization_internal::KernelTimeout t,
489 int flags);
490 void LockSlow(MuHow how, const Condition *cond,
491 int flags) ABSL_ATTRIBUTE_COLD;
492 // slow path release
493 void UnlockSlow(SynchWaitParams *waitp) ABSL_ATTRIBUTE_COLD;
494 // Common code between Await() and AwaitWithTimeout/Deadline()
495 bool AwaitCommon(const Condition &cond,
496 synchronization_internal::KernelTimeout t);
497 // Attempt to remove thread s from queue.
498 void TryRemove(base_internal::PerThreadSynch *s);
499 // Block a thread on mutex.
500 void Block(base_internal::PerThreadSynch *s);
501 // Wake a thread; return successor.
502 base_internal::PerThreadSynch *Wakeup(base_internal::PerThreadSynch *w);
503
504 friend class CondVar; // for access to Trans()/Fer().
505 void Trans(MuHow how); // used for CondVar->Mutex transfer
506 void Fer(
507 base_internal::PerThreadSynch *w); // used for CondVar->Mutex transfer
508 #endif
509
510 // Catch the error of writing Mutex when intending MutexLock.
Mutex(const volatile Mutex *)511 Mutex(const volatile Mutex * /*ignored*/) {} // NOLINT(runtime/explicit)
512
513 Mutex(const Mutex&) = delete;
514 Mutex& operator=(const Mutex&) = delete;
515 };
516
517 // -----------------------------------------------------------------------------
518 // Mutex RAII Wrappers
519 // -----------------------------------------------------------------------------
520
521 // MutexLock
522 //
523 // `MutexLock` is a helper class, which acquires and releases a `Mutex` via
524 // RAII.
525 //
526 // Example:
527 //
528 // Class Foo {
529 //
530 // Foo::Bar* Baz() {
531 // MutexLock l(&lock_);
532 // ...
533 // return bar;
534 // }
535 //
536 // private:
537 // Mutex lock_;
538 // };
539 class ABSL_SCOPED_LOCKABLE MutexLock {
540 public:
MutexLock(Mutex * mu)541 explicit MutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) : mu_(mu) {
542 this->mu_->Lock();
543 }
544
545 MutexLock(const MutexLock &) = delete; // NOLINT(runtime/mutex)
546 MutexLock(MutexLock&&) = delete; // NOLINT(runtime/mutex)
547 MutexLock& operator=(const MutexLock&) = delete;
548 MutexLock& operator=(MutexLock&&) = delete;
549
ABSL_UNLOCK_FUNCTION()550 ~MutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->Unlock(); }
551
552 private:
553 Mutex *const mu_;
554 };
555
556 // ReaderMutexLock
557 //
558 // The `ReaderMutexLock` is a helper class, like `MutexLock`, which acquires and
559 // releases a shared lock on a `Mutex` via RAII.
560 class ABSL_SCOPED_LOCKABLE ReaderMutexLock {
561 public:
ReaderMutexLock(Mutex * mu)562 explicit ReaderMutexLock(Mutex *mu) ABSL_SHARED_LOCK_FUNCTION(mu) : mu_(mu) {
563 mu->ReaderLock();
564 }
565
566 ReaderMutexLock(const ReaderMutexLock&) = delete;
567 ReaderMutexLock(ReaderMutexLock&&) = delete;
568 ReaderMutexLock& operator=(const ReaderMutexLock&) = delete;
569 ReaderMutexLock& operator=(ReaderMutexLock&&) = delete;
570
ABSL_UNLOCK_FUNCTION()571 ~ReaderMutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->ReaderUnlock(); }
572
573 private:
574 Mutex *const mu_;
575 };
576
577 // WriterMutexLock
578 //
579 // The `WriterMutexLock` is a helper class, like `MutexLock`, which acquires and
580 // releases a write (exclusive) lock on a `Mutex` via RAII.
581 class ABSL_SCOPED_LOCKABLE WriterMutexLock {
582 public:
WriterMutexLock(Mutex * mu)583 explicit WriterMutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
584 : mu_(mu) {
585 mu->WriterLock();
586 }
587
588 WriterMutexLock(const WriterMutexLock&) = delete;
589 WriterMutexLock(WriterMutexLock&&) = delete;
590 WriterMutexLock& operator=(const WriterMutexLock&) = delete;
591 WriterMutexLock& operator=(WriterMutexLock&&) = delete;
592
ABSL_UNLOCK_FUNCTION()593 ~WriterMutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->WriterUnlock(); }
594
595 private:
596 Mutex *const mu_;
597 };
598
599 // -----------------------------------------------------------------------------
600 // Condition
601 // -----------------------------------------------------------------------------
602 //
603 // As noted above, `Mutex` contains a number of member functions which take a
604 // `Condition` as an argument; clients can wait for conditions to become `true`
605 // before attempting to acquire the mutex. These sections are known as
606 // "condition critical" sections. To use a `Condition`, you simply need to
607 // construct it, and use within an appropriate `Mutex` member function;
608 // everything else in the `Condition` class is an implementation detail.
609 //
610 // A `Condition` is specified as a function pointer which returns a boolean.
611 // `Condition` functions should be pure functions -- their results should depend
612 // only on passed arguments, should not consult any external state (such as
613 // clocks), and should have no side-effects, aside from debug logging. Any
614 // objects that the function may access should be limited to those which are
615 // constant while the mutex is blocked on the condition (e.g. a stack variable),
616 // or objects of state protected explicitly by the mutex.
617 //
618 // No matter which construction is used for `Condition`, the underlying
619 // function pointer / functor / callable must not throw any
620 // exceptions. Correctness of `Mutex` / `Condition` is not guaranteed in
621 // the face of a throwing `Condition`. (When Abseil is allowed to depend
622 // on C++17, these function pointers will be explicitly marked
623 // `noexcept`; until then this requirement cannot be enforced in the
624 // type system.)
625 //
626 // Note: to use a `Condition`, you need only construct it and pass it within the
627 // appropriate `Mutex' member function, such as `Mutex::Await()`.
628 //
629 // Example:
630 //
631 // // assume count_ is not internal reference count
632 // int count_ ABSL_GUARDED_BY(mu_);
633 //
634 // mu_.LockWhen(Condition(+[](int* count) { return *count == 0; },
635 // &count_));
636 //
637 // When multiple threads are waiting on exactly the same condition, make sure
638 // that they are constructed with the same parameters (same pointer to function
639 // + arg, or same pointer to object + method), so that the mutex implementation
640 // can avoid redundantly evaluating the same condition for each thread.
641 class Condition {
642 public:
643 // A Condition that returns the result of "(*func)(arg)"
644 Condition(bool (*func)(void *), void *arg);
645
646 // Templated version for people who are averse to casts.
647 //
648 // To use a lambda, prepend it with unary plus, which converts the lambda
649 // into a function pointer:
650 // Condition(+[](T* t) { return ...; }, arg).
651 //
652 // Note: lambdas in this case must contain no bound variables.
653 //
654 // See class comment for performance advice.
655 template<typename T>
656 Condition(bool (*func)(T *), T *arg);
657
658 // Templated version for invoking a method that returns a `bool`.
659 //
660 // `Condition(object, &Class::Method)` constructs a `Condition` that evaluates
661 // `object->Method()`.
662 //
663 // Implementation Note: `absl::internal::identity` is used to allow methods to
664 // come from base classes. A simpler signature like
665 // `Condition(T*, bool (T::*)())` does not suffice.
666 template<typename T>
667 Condition(T *object, bool (absl::internal::identity<T>::type::* method)());
668
669 // Same as above, for const members
670 template<typename T>
671 Condition(const T *object,
672 bool (absl::internal::identity<T>::type::* method)() const);
673
674 // A Condition that returns the value of `*cond`
675 explicit Condition(const bool *cond);
676
677 // Templated version for invoking a functor that returns a `bool`.
678 // This approach accepts pointers to non-mutable lambdas, `std::function`,
679 // the result of` std::bind` and user-defined functors that define
680 // `bool F::operator()() const`.
681 //
682 // Example:
683 //
684 // auto reached = [this, current]() {
685 // mu_.AssertReaderHeld(); // For annotalysis.
686 // return processed_ >= current;
687 // };
688 // mu_.Await(Condition(&reached));
689
690 // See class comment for performance advice. In particular, if there
691 // might be more than one waiter for the same condition, make sure
692 // that all waiters construct the condition with the same pointers.
693
694 // Implementation note: The second template parameter ensures that this
695 // constructor doesn't participate in overload resolution if T doesn't have
696 // `bool operator() const`.
697 template <typename T, typename E = decltype(
698 static_cast<bool (T::*)() const>(&T::operator()))>
Condition(const T * obj)699 explicit Condition(const T *obj)
700 : Condition(obj, static_cast<bool (T::*)() const>(&T::operator())) {}
701
702 // A Condition that always returns `true`.
703 static const Condition kTrue;
704
705 // Evaluates the condition.
706 bool Eval() const;
707
708 // Returns `true` if the two conditions are guaranteed to return the same
709 // value if evaluated at the same time, `false` if the evaluation *may* return
710 // different results.
711 //
712 // Two `Condition` values are guaranteed equal if both their `func` and `arg`
713 // components are the same. A null pointer is equivalent to a `true`
714 // condition.
715 static bool GuaranteedEqual(const Condition *a, const Condition *b);
716
717 private:
718 typedef bool (*InternalFunctionType)(void * arg);
719 typedef bool (Condition::*InternalMethodType)();
720 typedef bool (*InternalMethodCallerType)(void * arg,
721 InternalMethodType internal_method);
722
723 bool (*eval_)(const Condition*); // Actual evaluator
724 InternalFunctionType function_; // function taking pointer returning bool
725 InternalMethodType method_; // method returning bool
726 void *arg_; // arg of function_ or object of method_
727
728 Condition(); // null constructor used only to create kTrue
729
730 // Various functions eval_ can point to:
731 static bool CallVoidPtrFunction(const Condition*);
732 template <typename T> static bool CastAndCallFunction(const Condition* c);
733 template <typename T> static bool CastAndCallMethod(const Condition* c);
734 };
735
736 // -----------------------------------------------------------------------------
737 // CondVar
738 // -----------------------------------------------------------------------------
739 //
740 // A condition variable, reflecting state evaluated separately outside of the
741 // `Mutex` object, which can be signaled to wake callers.
742 // This class is not normally needed; use `Mutex` member functions such as
743 // `Mutex::Await()` and intrinsic `Condition` abstractions. In rare cases
744 // with many threads and many conditions, `CondVar` may be faster.
745 //
746 // The implementation may deliver signals to any condition variable at
747 // any time, even when no call to `Signal()` or `SignalAll()` is made; as a
748 // result, upon being awoken, you must check the logical condition you have
749 // been waiting upon.
750 //
751 // Examples:
752 //
753 // Usage for a thread waiting for some condition C protected by mutex mu:
754 // mu.Lock();
755 // while (!C) { cv->Wait(&mu); } // releases and reacquires mu
756 // // C holds; process data
757 // mu.Unlock();
758 //
759 // Usage to wake T is:
760 // mu.Lock();
761 // // process data, possibly establishing C
762 // if (C) { cv->Signal(); }
763 // mu.Unlock();
764 //
765 // If C may be useful to more than one waiter, use `SignalAll()` instead of
766 // `Signal()`.
767 //
768 // With this implementation it is efficient to use `Signal()/SignalAll()` inside
769 // the locked region; this usage can make reasoning about your program easier.
770 //
771 class CondVar {
772 public:
773 CondVar();
774 ~CondVar();
775
776 // CondVar::Wait()
777 //
778 // Atomically releases a `Mutex` and blocks on this condition variable.
779 // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
780 // spurious wakeup), then reacquires the `Mutex` and returns.
781 //
782 // Requires and ensures that the current thread holds the `Mutex`.
783 void Wait(Mutex *mu);
784
785 // CondVar::WaitWithTimeout()
786 //
787 // Atomically releases a `Mutex` and blocks on this condition variable.
788 // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
789 // spurious wakeup), or until the timeout has expired, then reacquires
790 // the `Mutex` and returns.
791 //
792 // Returns true if the timeout has expired without this `CondVar`
793 // being signalled in any manner. If both the timeout has expired
794 // and this `CondVar` has been signalled, the implementation is free
795 // to return `true` or `false`.
796 //
797 // Requires and ensures that the current thread holds the `Mutex`.
798 bool WaitWithTimeout(Mutex *mu, absl::Duration timeout);
799
800 // CondVar::WaitWithDeadline()
801 //
802 // Atomically releases a `Mutex` and blocks on this condition variable.
803 // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
804 // spurious wakeup), or until the deadline has passed, then reacquires
805 // the `Mutex` and returns.
806 //
807 // Deadlines in the past are equivalent to an immediate deadline.
808 //
809 // Returns true if the deadline has passed without this `CondVar`
810 // being signalled in any manner. If both the deadline has passed
811 // and this `CondVar` has been signalled, the implementation is free
812 // to return `true` or `false`.
813 //
814 // Requires and ensures that the current thread holds the `Mutex`.
815 bool WaitWithDeadline(Mutex *mu, absl::Time deadline);
816
817 // CondVar::Signal()
818 //
819 // Signal this `CondVar`; wake at least one waiter if one exists.
820 void Signal();
821
822 // CondVar::SignalAll()
823 //
824 // Signal this `CondVar`; wake all waiters.
825 void SignalAll();
826
827 // CondVar::EnableDebugLog()
828 //
829 // Causes all subsequent uses of this `CondVar` to be logged via
830 // `ABSL_RAW_LOG(INFO)`. Log entries are tagged with `name` if `name != 0`.
831 // Note: this method substantially reduces `CondVar` performance.
832 void EnableDebugLog(const char *name);
833
834 private:
835 #ifdef ABSL_INTERNAL_USE_NONPROD_MUTEX
impl()836 synchronization_internal::CondVarImpl *impl() { return impl_.get(); }
837 synchronization_internal::SynchronizationStorage<
838 synchronization_internal::CondVarImpl>
839 impl_;
840 #else
841 bool WaitCommon(Mutex *mutex, synchronization_internal::KernelTimeout t);
842 void Remove(base_internal::PerThreadSynch *s);
843 void Wakeup(base_internal::PerThreadSynch *w);
844 std::atomic<intptr_t> cv_; // Condition variable state.
845 #endif
846 CondVar(const CondVar&) = delete;
847 CondVar& operator=(const CondVar&) = delete;
848 };
849
850
851 // Variants of MutexLock.
852 //
853 // If you find yourself using one of these, consider instead using
854 // Mutex::Unlock() and/or if-statements for clarity.
855
856 // MutexLockMaybe
857 //
858 // MutexLockMaybe is like MutexLock, but is a no-op when mu is null.
859 class ABSL_SCOPED_LOCKABLE MutexLockMaybe {
860 public:
MutexLockMaybe(Mutex * mu)861 explicit MutexLockMaybe(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
862 : mu_(mu) {
863 if (this->mu_ != nullptr) {
864 this->mu_->Lock();
865 }
866 }
ABSL_UNLOCK_FUNCTION()867 ~MutexLockMaybe() ABSL_UNLOCK_FUNCTION() {
868 if (this->mu_ != nullptr) { this->mu_->Unlock(); }
869 }
870
871 private:
872 Mutex *const mu_;
873 MutexLockMaybe(const MutexLockMaybe&) = delete;
874 MutexLockMaybe(MutexLockMaybe&&) = delete;
875 MutexLockMaybe& operator=(const MutexLockMaybe&) = delete;
876 MutexLockMaybe& operator=(MutexLockMaybe&&) = delete;
877 };
878
879 // ReleasableMutexLock
880 //
881 // ReleasableMutexLock is like MutexLock, but permits `Release()` of its
882 // mutex before destruction. `Release()` may be called at most once.
883 class ABSL_SCOPED_LOCKABLE ReleasableMutexLock {
884 public:
ReleasableMutexLock(Mutex * mu)885 explicit ReleasableMutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
886 : mu_(mu) {
887 this->mu_->Lock();
888 }
ABSL_UNLOCK_FUNCTION()889 ~ReleasableMutexLock() ABSL_UNLOCK_FUNCTION() {
890 if (this->mu_ != nullptr) { this->mu_->Unlock(); }
891 }
892
893 void Release() ABSL_UNLOCK_FUNCTION();
894
895 private:
896 Mutex *mu_;
897 ReleasableMutexLock(const ReleasableMutexLock&) = delete;
898 ReleasableMutexLock(ReleasableMutexLock&&) = delete;
899 ReleasableMutexLock& operator=(const ReleasableMutexLock&) = delete;
900 ReleasableMutexLock& operator=(ReleasableMutexLock&&) = delete;
901 };
902
903 #ifdef ABSL_INTERNAL_USE_NONPROD_MUTEX
Mutex(absl::ConstInitType)904 inline constexpr Mutex::Mutex(absl::ConstInitType) : impl_(absl::kConstInit) {}
905
906 #else
Mutex()907 inline Mutex::Mutex() : mu_(0) {
908 ABSL_TSAN_MUTEX_CREATE(this, __tsan_mutex_not_static);
909 }
910
Mutex(absl::ConstInitType)911 inline constexpr Mutex::Mutex(absl::ConstInitType) : mu_(0) {}
912
CondVar()913 inline CondVar::CondVar() : cv_(0) {}
914 #endif
915
916 // static
917 template <typename T>
CastAndCallMethod(const Condition * c)918 bool Condition::CastAndCallMethod(const Condition *c) {
919 typedef bool (T::*MemberType)();
920 MemberType rm = reinterpret_cast<MemberType>(c->method_);
921 T *x = static_cast<T *>(c->arg_);
922 return (x->*rm)();
923 }
924
925 // static
926 template <typename T>
CastAndCallFunction(const Condition * c)927 bool Condition::CastAndCallFunction(const Condition *c) {
928 typedef bool (*FuncType)(T *);
929 FuncType fn = reinterpret_cast<FuncType>(c->function_);
930 T *x = static_cast<T *>(c->arg_);
931 return (*fn)(x);
932 }
933
934 template <typename T>
Condition(bool (* func)(T *),T * arg)935 inline Condition::Condition(bool (*func)(T *), T *arg)
936 : eval_(&CastAndCallFunction<T>),
937 function_(reinterpret_cast<InternalFunctionType>(func)),
938 method_(nullptr),
939 arg_(const_cast<void *>(static_cast<const void *>(arg))) {}
940
941 template <typename T>
Condition(T * object,bool (absl::internal::identity<T>::type::* method)())942 inline Condition::Condition(T *object,
943 bool (absl::internal::identity<T>::type::*method)())
944 : eval_(&CastAndCallMethod<T>),
945 function_(nullptr),
946 method_(reinterpret_cast<InternalMethodType>(method)),
947 arg_(object) {}
948
949 template <typename T>
Condition(const T * object,bool (absl::internal::identity<T>::type::* method)()const)950 inline Condition::Condition(const T *object,
951 bool (absl::internal::identity<T>::type::*method)()
952 const)
953 : eval_(&CastAndCallMethod<T>),
954 function_(nullptr),
955 method_(reinterpret_cast<InternalMethodType>(method)),
956 arg_(reinterpret_cast<void *>(const_cast<T *>(object))) {}
957
958 // Register a hook for profiling support.
959 //
960 // The function pointer registered here will be called whenever a mutex is
961 // contended. The callback is given the absl/base/cycleclock.h timestamp when
962 // waiting began.
963 //
964 // Calls to this function do not race or block, but there is no ordering
965 // guaranteed between calls to this function and call to the provided hook.
966 // In particular, the previously registered hook may still be called for some
967 // time after this function returns.
968 void RegisterMutexProfiler(void (*fn)(int64_t wait_timestamp));
969
970 // Register a hook for Mutex tracing.
971 //
972 // The function pointer registered here will be called whenever a mutex is
973 // contended. The callback is given an opaque handle to the contended mutex,
974 // an event name, and the number of wait cycles (as measured by
975 // //absl/base/internal/cycleclock.h, and which may not be real
976 // "cycle" counts.)
977 //
978 // The only event name currently sent is "slow release".
979 //
980 // This has the same memory ordering concerns as RegisterMutexProfiler() above.
981 void RegisterMutexTracer(void (*fn)(const char *msg, const void *obj,
982 int64_t wait_cycles));
983
984 // TODO(gfalcon): Combine RegisterMutexProfiler() and RegisterMutexTracer()
985 // into a single interface, since they are only ever called in pairs.
986
987 // Register a hook for CondVar tracing.
988 //
989 // The function pointer registered here will be called here on various CondVar
990 // events. The callback is given an opaque handle to the CondVar object and
991 // a string identifying the event. This is thread-safe, but only a single
992 // tracer can be registered.
993 //
994 // Events that can be sent are "Wait", "Unwait", "Signal wakeup", and
995 // "SignalAll wakeup".
996 //
997 // This has the same memory ordering concerns as RegisterMutexProfiler() above.
998 void RegisterCondVarTracer(void (*fn)(const char *msg, const void *cv));
999
1000 // Register a hook for symbolizing stack traces in deadlock detector reports.
1001 //
1002 // 'pc' is the program counter being symbolized, 'out' is the buffer to write
1003 // into, and 'out_size' is the size of the buffer. This function can return
1004 // false if symbolizing failed, or true if a NUL-terminated symbol was written
1005 // to 'out.'
1006 //
1007 // This has the same memory ordering concerns as RegisterMutexProfiler() above.
1008 //
1009 // DEPRECATED: The default symbolizer function is absl::Symbolize() and the
1010 // ability to register a different hook for symbolizing stack traces will be
1011 // removed on or after 2023-05-01.
1012 ABSL_DEPRECATED("absl::RegisterSymbolizer() is deprecated and will be removed "
1013 "on or after 2023-05-01")
1014 void RegisterSymbolizer(bool (*fn)(const void *pc, char *out, int out_size));
1015
1016 // EnableMutexInvariantDebugging()
1017 //
1018 // Enable or disable global support for Mutex invariant debugging. If enabled,
1019 // then invariant predicates can be registered per-Mutex for debug checking.
1020 // See Mutex::EnableInvariantDebugging().
1021 void EnableMutexInvariantDebugging(bool enabled);
1022
1023 // When in debug mode, and when the feature has been enabled globally, the
1024 // implementation will keep track of lock ordering and complain (or optionally
1025 // crash) if a cycle is detected in the acquired-before graph.
1026
1027 // Possible modes of operation for the deadlock detector in debug mode.
1028 enum class OnDeadlockCycle {
1029 kIgnore, // Neither report on nor attempt to track cycles in lock ordering
1030 kReport, // Report lock cycles to stderr when detected
1031 kAbort, // Report lock cycles to stderr when detected, then abort
1032 };
1033
1034 // SetMutexDeadlockDetectionMode()
1035 //
1036 // Enable or disable global support for detection of potential deadlocks
1037 // due to Mutex lock ordering inversions. When set to 'kIgnore', tracking of
1038 // lock ordering is disabled. Otherwise, in debug builds, a lock ordering graph
1039 // will be maintained internally, and detected cycles will be reported in
1040 // the manner chosen here.
1041 void SetMutexDeadlockDetectionMode(OnDeadlockCycle mode);
1042
1043 ABSL_NAMESPACE_END
1044 } // namespace absl
1045
1046 // In some build configurations we pass --detect-odr-violations to the
1047 // gold linker. This causes it to flag weak symbol overrides as ODR
1048 // violations. Because ODR only applies to C++ and not C,
1049 // --detect-odr-violations ignores symbols not mangled with C++ names.
1050 // By changing our extension points to be extern "C", we dodge this
1051 // check.
1052 extern "C" {
1053 void AbslInternalMutexYield();
1054 } // extern "C"
1055
1056 #endif // ABSL_SYNCHRONIZATION_MUTEX_H_
1057