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


abseil_cpp
Author(s):
autogenerated on Mon Feb 28 2022 21:31:19