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
84namespace absl {
85
86class Condition;
87struct 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
138class LOCKABLE Mutex {
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
322 void WriterLockWhen(const Condition &cond) EXCLUSIVE_LOCK_FUNCTION() {
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)
364 EXCLUSIVE_LOCK_FUNCTION();
365 bool ReaderLockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
366 SHARED_LOCK_FUNCTION();
367 bool WriterLockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
368 EXCLUSIVE_LOCK_FUNCTION() {
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)
384 EXCLUSIVE_LOCK_FUNCTION();
385 bool ReaderLockWhenWithDeadline(const Condition &cond, absl::Time deadline)
386 SHARED_LOCK_FUNCTION();
387 bool WriterLockWhenWithDeadline(const Condition &cond, absl::Time deadline)
388 EXCLUSIVE_LOCK_FUNCTION() {
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,
478 base_internal::PerThreadSynch *w);
479 static inline bool DecrementSynchSem(
480 Mutex *mu, base_internal::PerThreadSynch *w,
481 synchronization_internal::KernelTimeout t);
482
483 // slow path acquire
484 void LockSlowLoop(SynchWaitParams *waitp, int flags);
485 // wrappers around LockSlowLoop()
486 bool LockSlowWithDeadline(MuHow how, const Condition *cond,
487 synchronization_internal::KernelTimeout t,
488 int flags);
489 void LockSlow(MuHow how, const Condition *cond,
490 int flags) ABSL_ATTRIBUTE_COLD;
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,
495 synchronization_internal::KernelTimeout t);
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.
501 base_internal::PerThreadSynch *Wakeup(base_internal::PerThreadSynch *w);
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// };
538class SCOPED_LOCKABLE MutexLock {
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.
559class SCOPED_LOCKABLE ReaderMutexLock {
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.
583class SCOPED_LOCKABLE WriterMutexLock {
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.
645class 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//
775class 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.
863class SCOPED_LOCKABLE MutexLockMaybe {
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.
882class SCOPED_LOCKABLE ReleasableMutexLock {
883 public:
884 explicit ReleasableMutexLock(Mutex *mu) EXCLUSIVE_LOCK_FUNCTION(mu)
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;
897 ReleasableMutexLock(ReleasableMutexLock&&) = delete;
898 ReleasableMutexLock& operator=(const ReleasableMutexLock&) = delete;
899 ReleasableMutexLock& operator=(ReleasableMutexLock&&) = delete;
900};
901
902#ifdef ABSL_INTERNAL_USE_NONPROD_MUTEX
903inline constexpr Mutex::Mutex(absl::ConstInitType) : impl_(absl::kConstInit) {}
904
905#else
906inline Mutex::Mutex() : mu_(0) {
907 ABSL_TSAN_MUTEX_CREATE(this, __tsan_mutex_not_static);
908}
909
910inline constexpr Mutex::Mutex(absl::ConstInitType) : mu_(0) {}
911
912inline CondVar::CondVar() : cv_(0) {}
913#endif
914
915// static
916template <typename T>
917bool Condition::CastAndCallMethod(const Condition *c) {
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
925template <typename T>
926bool Condition::CastAndCallFunction(const Condition *c) {
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
933template <typename T>
934inline 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
940template <typename T>
941inline 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
948template <typename T>
949inline 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.
967void 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.
980void 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.
997void 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.
1011ABSL_DEPRECATED("absl::RegisterSymbolizer() is deprecated and will be removed "
1012 "on or after 2023-05-01")
1013void 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().
1020void 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.
1027enum 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.
1040void SetMutexDeadlockDetectionMode(OnDeadlockCycle mode);
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.
1050extern "C" {
1051void AbslInternalMutexYield();
1052} // extern "C"
1053
1054#endif // ABSL_SYNCHRONIZATION_MUTEX_H_
1055