1091 lines
43 KiB
C
1091 lines
43 KiB
C
![]() |
// Copyright 2017 The Abseil Authors.
|
||
|
//
|
||
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
// you may not use this file except in compliance with the License.
|
||
|
// You may obtain a copy of the License at
|
||
|
//
|
||
|
// https://www.apache.org/licenses/LICENSE-2.0
|
||
|
//
|
||
|
// Unless required by applicable law or agreed to in writing, software
|
||
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
// See the License for the specific language governing permissions and
|
||
|
// limitations under the License.
|
||
|
//
|
||
|
// -----------------------------------------------------------------------------
|
||
|
// mutex.h
|
||
|
// -----------------------------------------------------------------------------
|
||
|
//
|
||
|
// This header file defines a `Mutex` -- a mutually exclusive lock -- and the
|
||
|
// most common type of synchronization primitive for facilitating locks on
|
||
|
// shared resources. A mutex is used to prevent multiple threads from accessing
|
||
|
// and/or writing to a shared resource concurrently.
|
||
|
//
|
||
|
// Unlike a `std::mutex`, the Abseil `Mutex` provides the following additional
|
||
|
// features:
|
||
|
// * Conditional predicates intrinsic to the `Mutex` object
|
||
|
// * Shared/reader locks, in addition to standard exclusive/writer locks
|
||
|
// * Deadlock detection and debug support.
|
||
|
//
|
||
|
// The following helper classes are also defined within this file:
|
||
|
//
|
||
|
// MutexLock - An RAII wrapper to acquire and release a `Mutex` for exclusive/
|
||
|
// write access within the current scope.
|
||
|
//
|
||
|
// ReaderMutexLock
|
||
|
// - An RAII wrapper to acquire and release a `Mutex` for shared/read
|
||
|
// access within the current scope.
|
||
|
//
|
||
|
// WriterMutexLock
|
||
|
// - Effectively an alias for `MutexLock` above, designed for use in
|
||
|
// distinguishing reader and writer locks within code.
|
||
|
//
|
||
|
// In addition to simple mutex locks, this file also defines ways to perform
|
||
|
// locking under certain conditions.
|
||
|
//
|
||
|
// Condition - (Preferred) Used to wait for a particular predicate that
|
||
|
// depends on state protected by the `Mutex` to become true.
|
||
|
// CondVar - A lower-level variant of `Condition` that relies on
|
||
|
// application code to explicitly signal the `CondVar` when
|
||
|
// a condition has been met.
|
||
|
//
|
||
|
// See below for more information on using `Condition` or `CondVar`.
|
||
|
//
|
||
|
// Mutexes and mutex behavior can be quite complicated. The information within
|
||
|
// this header file is limited, as a result. Please consult the Mutex guide for
|
||
|
// more complete information and examples.
|
||
|
|
||
|
#ifndef ABSL_SYNCHRONIZATION_MUTEX_H_
|
||
|
#define ABSL_SYNCHRONIZATION_MUTEX_H_
|
||
|
|
||
|
#include <atomic>
|
||
|
#include <cstdint>
|
||
|
#include <string>
|
||
|
|
||
|
#include "absl/base/const_init.h"
|
||
|
#include "absl/base/internal/identity.h"
|
||
|
#include "absl/base/internal/low_level_alloc.h"
|
||
|
#include "absl/base/internal/thread_identity.h"
|
||
|
#include "absl/base/internal/tsan_mutex_interface.h"
|
||
|
#include "absl/base/port.h"
|
||
|
#include "absl/base/thread_annotations.h"
|
||
|
#include "absl/synchronization/internal/kernel_timeout.h"
|
||
|
#include "absl/synchronization/internal/per_thread_sem.h"
|
||
|
#include "absl/time/time.h"
|
||
|
|
||
|
namespace absl {
|
||
|
ABSL_NAMESPACE_BEGIN
|
||
|
|
||
|
class Condition;
|
||
|
struct SynchWaitParams;
|
||
|
|
||
|
// -----------------------------------------------------------------------------
|
||
|
// Mutex
|
||
|
// -----------------------------------------------------------------------------
|
||
|
//
|
||
|
// A `Mutex` is a non-reentrant (aka non-recursive) Mutually Exclusive lock
|
||
|
// on some resource, typically a variable or data structure with associated
|
||
|
// invariants. Proper usage of mutexes prevents concurrent access by different
|
||
|
// threads to the same resource.
|
||
|
//
|
||
|
// A `Mutex` has two basic operations: `Mutex::Lock()` and `Mutex::Unlock()`.
|
||
|
// The `Lock()` operation *acquires* a `Mutex` (in a state known as an
|
||
|
// *exclusive* -- or write -- lock), while the `Unlock()` operation *releases* a
|
||
|
// Mutex. During the span of time between the Lock() and Unlock() operations,
|
||
|
// a mutex is said to be *held*. By design all mutexes support exclusive/write
|
||
|
// locks, as this is the most common way to use a mutex.
|
||
|
//
|
||
|
// The `Mutex` state machine for basic lock/unlock operations is quite simple:
|
||
|
//
|
||
|
// | | Lock() | Unlock() |
|
||
|
// |----------------+------------+----------|
|
||
|
// | Free | Exclusive | invalid |
|
||
|
// | Exclusive | blocks | Free |
|
||
|
//
|
||
|
// Attempts to `Unlock()` must originate from the thread that performed the
|
||
|
// corresponding `Lock()` operation.
|
||
|
//
|
||
|
// An "invalid" operation is disallowed by the API. The `Mutex` implementation
|
||
|
// is allowed to do anything on an invalid call, including but not limited to
|
||
|
// crashing with a useful error message, silently succeeding, or corrupting
|
||
|
// data structures. In debug mode, the implementation attempts to crash with a
|
||
|
// useful error message.
|
||
|
//
|
||
|
// `Mutex` is not guaranteed to be "fair" in prioritizing waiting threads; it
|
||
|
// is, however, approximately fair over long periods, and starvation-free for
|
||
|
// threads at the same priority.
|
||
|
//
|
||
|
// The lock/unlock primitives are now annotated with lock annotations
|
||
|
// defined in (base/thread_annotations.h). When writing multi-threaded code,
|
||
|
// you should use lock annotations whenever possible to document your lock
|
||
|
// synchronization policy. Besides acting as documentation, these annotations
|
||
|
// also help compilers or static analysis tools to identify and warn about
|
||
|
// issues that could potentially result in race conditions and deadlocks.
|
||
|
//
|
||
|
// For more information about the lock annotations, please see
|
||
|
// [Thread Safety Analysis](http://clang.llvm.org/docs/ThreadSafetyAnalysis.html)
|
||
|
// in the Clang documentation.
|
||
|
//
|
||
|
// See also `MutexLock`, below, for scoped `Mutex` acquisition.
|
||
|
|
||
|
class ABSL_LOCKABLE Mutex {
|
||
|
public:
|
||
|
// Creates a `Mutex` that is not held by anyone. This constructor is
|
||
|
// typically used for Mutexes allocated on the heap or the stack.
|
||
|
//
|
||
|
// To create `Mutex` instances with static storage duration
|
||
|
// (e.g. a namespace-scoped or global variable), see
|
||
|
// `Mutex::Mutex(absl::kConstInit)` below instead.
|
||
|
Mutex();
|
||
|
|
||
|
// Creates a mutex with static storage duration. A global variable
|
||
|
// constructed this way avoids the lifetime issues that can occur on program
|
||
|
// startup and shutdown. (See absl/base/const_init.h.)
|
||
|
//
|
||
|
// For Mutexes allocated on the heap and stack, instead use the default
|
||
|
// constructor, which can interact more fully with the thread sanitizer.
|
||
|
//
|
||
|
// Example usage:
|
||
|
// namespace foo {
|
||
|
// ABSL_CONST_INIT absl::Mutex mu(absl::kConstInit);
|
||
|
// }
|
||
|
explicit constexpr Mutex(absl::ConstInitType);
|
||
|
|
||
|
~Mutex();
|
||
|
|
||
|
// Mutex::Lock()
|
||
|
//
|
||
|
// Blocks the calling thread, if necessary, until this `Mutex` is free, and
|
||
|
// then acquires it exclusively. (This lock is also known as a "write lock.")
|
||
|
void Lock() ABSL_EXCLUSIVE_LOCK_FUNCTION();
|
||
|
|
||
|
// Mutex::Unlock()
|
||
|
//
|
||
|
// Releases this `Mutex` and returns it from the exclusive/write state to the
|
||
|
// free state. Calling thread must hold the `Mutex` exclusively.
|
||
|
void Unlock() ABSL_UNLOCK_FUNCTION();
|
||
|
|
||
|
// Mutex::TryLock()
|
||
|
//
|
||
|
// If the mutex can be acquired without blocking, does so exclusively and
|
||
|
// returns `true`. Otherwise, returns `false`. Returns `true` with high
|
||
|
// probability if the `Mutex` was free.
|
||
|
bool TryLock() ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(true);
|
||
|
|
||
|
// Mutex::AssertHeld()
|
||
|
//
|
||
|
// Require that the mutex be held exclusively (write mode) by this thread.
|
||
|
//
|
||
|
// If the mutex is not currently held by this thread, this function may report
|
||
|
// an error (typically by crashing with a diagnostic) or it may do nothing.
|
||
|
// This function is intended only as a tool to assist debugging; it doesn't
|
||
|
// guarantee correctness.
|
||
|
void AssertHeld() const ABSL_ASSERT_EXCLUSIVE_LOCK();
|
||
|
|
||
|
// ---------------------------------------------------------------------------
|
||
|
// Reader-Writer Locking
|
||
|
// ---------------------------------------------------------------------------
|
||
|
|
||
|
// A Mutex can also be used as a starvation-free reader-writer lock.
|
||
|
// Neither read-locks nor write-locks are reentrant/recursive to avoid
|
||
|
// potential client programming errors.
|
||
|
//
|
||
|
// The Mutex API provides `Writer*()` aliases for the existing `Lock()`,
|
||
|
// `Unlock()` and `TryLock()` methods for use within applications mixing
|
||
|
// reader/writer locks. Using `Reader*()` and `Writer*()` operations in this
|
||
|
// manner can make locking behavior clearer when mixing read and write modes.
|
||
|
//
|
||
|
// Introducing reader locks necessarily complicates the `Mutex` state
|
||
|
// machine somewhat. The table below illustrates the allowed state transitions
|
||
|
// of a mutex in such cases. Note that ReaderLock() may block even if the lock
|
||
|
// is held in shared mode; this occurs when another thread is blocked on a
|
||
|
// call to WriterLock().
|
||
|
//
|
||
|
// ---------------------------------------------------------------------------
|
||
|
// Operation: WriterLock() Unlock() ReaderLock() ReaderUnlock()
|
||
|
// ---------------------------------------------------------------------------
|
||
|
// State
|
||
|
// ---------------------------------------------------------------------------
|
||
|
// Free Exclusive invalid Shared(1) invalid
|
||
|
// Shared(1) blocks invalid Shared(2) or blocks Free
|
||
|
// Shared(n) n>1 blocks invalid Shared(n+1) or blocks Shared(n-1)
|
||
|
// Exclusive blocks Free blocks invalid
|
||
|
// ---------------------------------------------------------------------------
|
||
|
//
|
||
|
// In comments below, "shared" refers to a state of Shared(n) for any n > 0.
|
||
|
|
||
|
// Mutex::ReaderLock()
|
||
|
//
|
||
|
// Blocks the calling thread, if necessary, until this `Mutex` is either free,
|
||
|
// or in shared mode, and then acquires a share of it. Note that
|
||
|
// `ReaderLock()` will block if some other thread has an exclusive/writer lock
|
||
|
// on the mutex.
|
||
|
|
||
|
void ReaderLock() ABSL_SHARED_LOCK_FUNCTION();
|
||
|
|
||
|
// Mutex::ReaderUnlock()
|
||
|
//
|
||
|
// Releases a read share of this `Mutex`. `ReaderUnlock` may return a mutex to
|
||
|
// the free state if this thread holds the last reader lock on the mutex. Note
|
||
|
// that you cannot call `ReaderUnlock()` on a mutex held in write mode.
|
||
|
void ReaderUnlock() ABSL_UNLOCK_FUNCTION();
|
||
|
|
||
|
// Mutex::ReaderTryLock()
|
||
|
//
|
||
|
// If the mutex can be acquired without blocking, acquires this mutex for
|
||
|
// shared access and returns `true`. Otherwise, returns `false`. Returns
|
||
|
// `true` with high probability if the `Mutex` was free or shared.
|
||
|
bool ReaderTryLock() ABSL_SHARED_TRYLOCK_FUNCTION(true);
|
||
|
|
||
|
// Mutex::AssertReaderHeld()
|
||
|
//
|
||
|
// Require that the mutex be held at least in shared mode (read mode) by this
|
||
|
// thread.
|
||
|
//
|
||
|
// If the mutex is not currently held by this thread, this function may report
|
||
|
// an error (typically by crashing with a diagnostic) or it may do nothing.
|
||
|
// This function is intended only as a tool to assist debugging; it doesn't
|
||
|
// guarantee correctness.
|
||
|
void AssertReaderHeld() const ABSL_ASSERT_SHARED_LOCK();
|
||
|
|
||
|
// Mutex::WriterLock()
|
||
|
// Mutex::WriterUnlock()
|
||
|
// Mutex::WriterTryLock()
|
||
|
//
|
||
|
// Aliases for `Mutex::Lock()`, `Mutex::Unlock()`, and `Mutex::TryLock()`.
|
||
|
//
|
||
|
// These methods may be used (along with the complementary `Reader*()`
|
||
|
// methods) to distingish simple exclusive `Mutex` usage (`Lock()`,
|
||
|
// etc.) from reader/writer lock usage.
|
||
|
void WriterLock() ABSL_EXCLUSIVE_LOCK_FUNCTION() { this->Lock(); }
|
||
|
|
||
|
void WriterUnlock() ABSL_UNLOCK_FUNCTION() { this->Unlock(); }
|
||
|
|
||
|
bool WriterTryLock() ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(true) {
|
||
|
return this->TryLock();
|
||
|
}
|
||
|
|
||
|
// ---------------------------------------------------------------------------
|
||
|
// Conditional Critical Regions
|
||
|
// ---------------------------------------------------------------------------
|
||
|
|
||
|
// Conditional usage of a `Mutex` can occur using two distinct paradigms:
|
||
|
//
|
||
|
// * Use of `Mutex` member functions with `Condition` objects.
|
||
|
// * Use of the separate `CondVar` abstraction.
|
||
|
//
|
||
|
// In general, prefer use of `Condition` and the `Mutex` member functions
|
||
|
// listed below over `CondVar`. When there are multiple threads waiting on
|
||
|
// distinctly different conditions, however, a battery of `CondVar`s may be
|
||
|
// more efficient. This section discusses use of `Condition` objects.
|
||
|
//
|
||
|
// `Mutex` contains member functions for performing lock operations only under
|
||
|
// certain conditions, of class `Condition`. For correctness, the `Condition`
|
||
|
// must return a boolean that is a pure function, only of state protected by
|
||
|
// the `Mutex`. The condition must be invariant w.r.t. environmental state
|
||
|
// such as thread, cpu id, or time, and must be `noexcept`. The condition will
|
||
|
// always be invoked with the mutex held in at least read mode, so you should
|
||
|
// not block it for long periods or sleep it on a timer.
|
||
|
//
|
||
|
// Since a condition must not depend directly on the current time, use
|
||
|
// `*WithTimeout()` member function variants to make your condition
|
||
|
// effectively true after a given duration, or `*WithDeadline()` variants to
|
||
|
// make your condition effectively true after a given time.
|
||
|
//
|
||
|
// The condition function should have no side-effects aside from debug
|
||
|
// logging; as a special exception, the function may acquire other mutexes
|
||
|
// provided it releases all those that it acquires. (This exception was
|
||
|
// required to allow logging.)
|
||
|
|
||
|
// Mutex::Await()
|
||
|
//
|
||
|
// Unlocks this `Mutex` and blocks until simultaneously both `cond` is `true`
|
||
|
// and this `Mutex` can be reacquired, then reacquires this `Mutex` in the
|
||
|
// same mode in which it was previously held. If the condition is initially
|
||
|
// `true`, `Await()` *may* skip the release/re-acquire step.
|
||
|
//
|
||
|
// `Await()` requires that this thread holds this `Mutex` in some mode.
|
||
|
void Await(const Condition &cond);
|
||
|
|
||
|
// Mutex::LockWhen()
|
||
|
// Mutex::ReaderLockWhen()
|
||
|
// Mutex::WriterLockWhen()
|
||
|
//
|
||
|
// Blocks until simultaneously both `cond` is `true` and this `Mutex` can
|
||
|
// be acquired, then atomically acquires this `Mutex`. `LockWhen()` is
|
||
|
// logically equivalent to `*Lock(); Await();` though they may have different
|
||
|
// performance characteristics.
|
||
|
void LockWhen(const Condition &cond) ABSL_EXCLUSIVE_LOCK_FUNCTION();
|
||
|
|
||
|
void ReaderLockWhen(const Condition &cond) ABSL_SHARED_LOCK_FUNCTION();
|
||
|
|
||
|
void WriterLockWhen(const Condition &cond) ABSL_EXCLUSIVE_LOCK_FUNCTION() {
|
||
|
this->LockWhen(cond);
|
||
|
}
|
||
|
|
||
|
// ---------------------------------------------------------------------------
|
||
|
// Mutex Variants with Timeouts/Deadlines
|
||
|
// ---------------------------------------------------------------------------
|
||
|
|
||
|
// Mutex::AwaitWithTimeout()
|
||
|
// Mutex::AwaitWithDeadline()
|
||
|
//
|
||
|
// Unlocks this `Mutex` and blocks until simultaneously:
|
||
|
// - either `cond` is true or the {timeout has expired, deadline has passed}
|
||
|
// and
|
||
|
// - this `Mutex` can be reacquired,
|
||
|
// then reacquire this `Mutex` in the same mode in which it was previously
|
||
|
// held, returning `true` iff `cond` is `true` on return.
|
||
|
//
|
||
|
// If the condition is initially `true`, the implementation *may* skip the
|
||
|
// release/re-acquire step and return immediately.
|
||
|
//
|
||
|
// Deadlines in the past are equivalent to an immediate deadline.
|
||
|
// Negative timeouts are equivalent to a zero timeout.
|
||
|
//
|
||
|
// This method requires that this thread holds this `Mutex` in some mode.
|
||
|
bool AwaitWithTimeout(const Condition &cond, absl::Duration timeout);
|
||
|
|
||
|
bool AwaitWithDeadline(const Condition &cond, absl::Time deadline);
|
||
|
|
||
|
// Mutex::LockWhenWithTimeout()
|
||
|
// Mutex::ReaderLockWhenWithTimeout()
|
||
|
// Mutex::WriterLockWhenWithTimeout()
|
||
|
//
|
||
|
// Blocks until simultaneously both:
|
||
|
// - either `cond` is `true` or the timeout has expired, and
|
||
|
// - this `Mutex` can be acquired,
|
||
|
// then atomically acquires this `Mutex`, returning `true` iff `cond` is
|
||
|
// `true` on return.
|
||
|
//
|
||
|
// Negative timeouts are equivalent to a zero timeout.
|
||
|
bool LockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION();
|
||
|
bool ReaderLockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
|
||
|
ABSL_SHARED_LOCK_FUNCTION();
|
||
|
bool WriterLockWhenWithTimeout(const Condition &cond, absl::Duration timeout)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION() {
|
||
|
return this->LockWhenWithTimeout(cond, timeout);
|
||
|
}
|
||
|
|
||
|
// Mutex::LockWhenWithDeadline()
|
||
|
// Mutex::ReaderLockWhenWithDeadline()
|
||
|
// Mutex::WriterLockWhenWithDeadline()
|
||
|
//
|
||
|
// Blocks until simultaneously both:
|
||
|
// - either `cond` is `true` or the deadline has been passed, and
|
||
|
// - this `Mutex` can be acquired,
|
||
|
// then atomically acquires this Mutex, returning `true` iff `cond` is `true`
|
||
|
// on return.
|
||
|
//
|
||
|
// Deadlines in the past are equivalent to an immediate deadline.
|
||
|
bool LockWhenWithDeadline(const Condition &cond, absl::Time deadline)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION();
|
||
|
bool ReaderLockWhenWithDeadline(const Condition &cond, absl::Time deadline)
|
||
|
ABSL_SHARED_LOCK_FUNCTION();
|
||
|
bool WriterLockWhenWithDeadline(const Condition &cond, absl::Time deadline)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION() {
|
||
|
return this->LockWhenWithDeadline(cond, deadline);
|
||
|
}
|
||
|
|
||
|
// ---------------------------------------------------------------------------
|
||
|
// Debug Support: Invariant Checking, Deadlock Detection, Logging.
|
||
|
// ---------------------------------------------------------------------------
|
||
|
|
||
|
// Mutex::EnableInvariantDebugging()
|
||
|
//
|
||
|
// If `invariant`!=null and if invariant debugging has been enabled globally,
|
||
|
// cause `(*invariant)(arg)` to be called at moments when the invariant for
|
||
|
// this `Mutex` should hold (for example: just after acquire, just before
|
||
|
// release).
|
||
|
//
|
||
|
// The routine `invariant` should have no side-effects since it is not
|
||
|
// guaranteed how many times it will be called; it should check the invariant
|
||
|
// and crash if it does not hold. Enabling global invariant debugging may
|
||
|
// substantially reduce `Mutex` performance; it should be set only for
|
||
|
// non-production runs. Optimization options may also disable invariant
|
||
|
// checks.
|
||
|
void EnableInvariantDebugging(void (*invariant)(void *), void *arg);
|
||
|
|
||
|
// Mutex::EnableDebugLog()
|
||
|
//
|
||
|
// Cause all subsequent uses of this `Mutex` to be logged via
|
||
|
// `ABSL_RAW_LOG(INFO)`. Log entries are tagged with `name` if no previous
|
||
|
// call to `EnableInvariantDebugging()` or `EnableDebugLog()` has been made.
|
||
|
//
|
||
|
// Note: This method substantially reduces `Mutex` performance.
|
||
|
void EnableDebugLog(const char *name);
|
||
|
|
||
|
// Deadlock detection
|
||
|
|
||
|
// Mutex::ForgetDeadlockInfo()
|
||
|
//
|
||
|
// Forget any deadlock-detection information previously gathered
|
||
|
// about this `Mutex`. Call this method in debug mode when the lock ordering
|
||
|
// of a `Mutex` changes.
|
||
|
void ForgetDeadlockInfo();
|
||
|
|
||
|
// Mutex::AssertNotHeld()
|
||
|
//
|
||
|
// Return immediately if this thread does not hold this `Mutex` in any
|
||
|
// mode; otherwise, may report an error (typically by crashing with a
|
||
|
// diagnostic), or may return immediately.
|
||
|
//
|
||
|
// Currently this check is performed only if all of:
|
||
|
// - in debug mode
|
||
|
// - SetMutexDeadlockDetectionMode() has been set to kReport or kAbort
|
||
|
// - number of locks concurrently held by this thread is not large.
|
||
|
// are true.
|
||
|
void AssertNotHeld() const;
|
||
|
|
||
|
// Special cases.
|
||
|
|
||
|
// A `MuHow` is a constant that indicates how a lock should be acquired.
|
||
|
// Internal implementation detail. Clients should ignore.
|
||
|
typedef const struct MuHowS *MuHow;
|
||
|
|
||
|
// Mutex::InternalAttemptToUseMutexInFatalSignalHandler()
|
||
|
//
|
||
|
// Causes the `Mutex` implementation to prepare itself for re-entry caused by
|
||
|
// future use of `Mutex` within a fatal signal handler. This method is
|
||
|
// intended for use only for last-ditch attempts to log crash information.
|
||
|
// It does not guarantee that attempts to use Mutexes within the handler will
|
||
|
// not deadlock; it merely makes other faults less likely.
|
||
|
//
|
||
|
// WARNING: This routine must be invoked from a signal handler, and the
|
||
|
// signal handler must either loop forever or terminate the process.
|
||
|
// Attempts to return from (or `longjmp` out of) the signal handler once this
|
||
|
// call has been made may cause arbitrary program behaviour including
|
||
|
// crashes and deadlocks.
|
||
|
static void InternalAttemptToUseMutexInFatalSignalHandler();
|
||
|
|
||
|
private:
|
||
|
std::atomic<intptr_t> mu_; // The Mutex state.
|
||
|
|
||
|
// Post()/Wait() versus associated PerThreadSem; in class for required
|
||
|
// friendship with PerThreadSem.
|
||
|
static void IncrementSynchSem(Mutex *mu, base_internal::PerThreadSynch *w);
|
||
|
static bool DecrementSynchSem(Mutex *mu, base_internal::PerThreadSynch *w,
|
||
|
synchronization_internal::KernelTimeout t);
|
||
|
|
||
|
// slow path acquire
|
||
|
void LockSlowLoop(SynchWaitParams *waitp, int flags);
|
||
|
// wrappers around LockSlowLoop()
|
||
|
bool LockSlowWithDeadline(MuHow how, const Condition *cond,
|
||
|
synchronization_internal::KernelTimeout t,
|
||
|
int flags);
|
||
|
void LockSlow(MuHow how, const Condition *cond,
|
||
|
int flags) ABSL_ATTRIBUTE_COLD;
|
||
|
// slow path release
|
||
|
void UnlockSlow(SynchWaitParams *waitp) ABSL_ATTRIBUTE_COLD;
|
||
|
// Common code between Await() and AwaitWithTimeout/Deadline()
|
||
|
bool AwaitCommon(const Condition &cond,
|
||
|
synchronization_internal::KernelTimeout t);
|
||
|
// Attempt to remove thread s from queue.
|
||
|
void TryRemove(base_internal::PerThreadSynch *s);
|
||
|
// Block a thread on mutex.
|
||
|
void Block(base_internal::PerThreadSynch *s);
|
||
|
// Wake a thread; return successor.
|
||
|
base_internal::PerThreadSynch *Wakeup(base_internal::PerThreadSynch *w);
|
||
|
|
||
|
friend class CondVar; // for access to Trans()/Fer().
|
||
|
void Trans(MuHow how); // used for CondVar->Mutex transfer
|
||
|
void Fer(
|
||
|
base_internal::PerThreadSynch *w); // used for CondVar->Mutex transfer
|
||
|
|
||
|
// Catch the error of writing Mutex when intending MutexLock.
|
||
|
Mutex(const volatile Mutex * /*ignored*/) {} // NOLINT(runtime/explicit)
|
||
|
|
||
|
Mutex(const Mutex&) = delete;
|
||
|
Mutex& operator=(const Mutex&) = delete;
|
||
|
};
|
||
|
|
||
|
// -----------------------------------------------------------------------------
|
||
|
// Mutex RAII Wrappers
|
||
|
// -----------------------------------------------------------------------------
|
||
|
|
||
|
// MutexLock
|
||
|
//
|
||
|
// `MutexLock` is a helper class, which acquires and releases a `Mutex` via
|
||
|
// RAII.
|
||
|
//
|
||
|
// Example:
|
||
|
//
|
||
|
// Class Foo {
|
||
|
// public:
|
||
|
// Foo::Bar* Baz() {
|
||
|
// MutexLock lock(&mu_);
|
||
|
// ...
|
||
|
// return bar;
|
||
|
// }
|
||
|
//
|
||
|
// private:
|
||
|
// Mutex mu_;
|
||
|
// };
|
||
|
class ABSL_SCOPED_LOCKABLE MutexLock {
|
||
|
public:
|
||
|
// Constructors
|
||
|
|
||
|
// Calls `mu->Lock()` and returns when that call returns. That is, `*mu` is
|
||
|
// guaranteed to be locked when this object is constructed. Requires that
|
||
|
// `mu` be dereferenceable.
|
||
|
explicit MutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) : mu_(mu) {
|
||
|
this->mu_->Lock();
|
||
|
}
|
||
|
|
||
|
// Like above, but calls `mu->LockWhen(cond)` instead. That is, in addition to
|
||
|
// the above, the condition given by `cond` is also guaranteed to hold when
|
||
|
// this object is constructed.
|
||
|
explicit MutexLock(Mutex *mu, const Condition &cond)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
this->mu_->LockWhen(cond);
|
||
|
}
|
||
|
|
||
|
MutexLock(const MutexLock &) = delete; // NOLINT(runtime/mutex)
|
||
|
MutexLock(MutexLock&&) = delete; // NOLINT(runtime/mutex)
|
||
|
MutexLock& operator=(const MutexLock&) = delete;
|
||
|
MutexLock& operator=(MutexLock&&) = delete;
|
||
|
|
||
|
~MutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->Unlock(); }
|
||
|
|
||
|
private:
|
||
|
Mutex *const mu_;
|
||
|
};
|
||
|
|
||
|
// ReaderMutexLock
|
||
|
//
|
||
|
// The `ReaderMutexLock` is a helper class, like `MutexLock`, which acquires and
|
||
|
// releases a shared lock on a `Mutex` via RAII.
|
||
|
class ABSL_SCOPED_LOCKABLE ReaderMutexLock {
|
||
|
public:
|
||
|
explicit ReaderMutexLock(Mutex *mu) ABSL_SHARED_LOCK_FUNCTION(mu) : mu_(mu) {
|
||
|
mu->ReaderLock();
|
||
|
}
|
||
|
|
||
|
explicit ReaderMutexLock(Mutex *mu, const Condition &cond)
|
||
|
ABSL_SHARED_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
mu->ReaderLockWhen(cond);
|
||
|
}
|
||
|
|
||
|
ReaderMutexLock(const ReaderMutexLock&) = delete;
|
||
|
ReaderMutexLock(ReaderMutexLock&&) = delete;
|
||
|
ReaderMutexLock& operator=(const ReaderMutexLock&) = delete;
|
||
|
ReaderMutexLock& operator=(ReaderMutexLock&&) = delete;
|
||
|
|
||
|
~ReaderMutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->ReaderUnlock(); }
|
||
|
|
||
|
private:
|
||
|
Mutex *const mu_;
|
||
|
};
|
||
|
|
||
|
// WriterMutexLock
|
||
|
//
|
||
|
// The `WriterMutexLock` is a helper class, like `MutexLock`, which acquires and
|
||
|
// releases a write (exclusive) lock on a `Mutex` via RAII.
|
||
|
class ABSL_SCOPED_LOCKABLE WriterMutexLock {
|
||
|
public:
|
||
|
explicit WriterMutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
mu->WriterLock();
|
||
|
}
|
||
|
|
||
|
explicit WriterMutexLock(Mutex *mu, const Condition &cond)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
mu->WriterLockWhen(cond);
|
||
|
}
|
||
|
|
||
|
WriterMutexLock(const WriterMutexLock&) = delete;
|
||
|
WriterMutexLock(WriterMutexLock&&) = delete;
|
||
|
WriterMutexLock& operator=(const WriterMutexLock&) = delete;
|
||
|
WriterMutexLock& operator=(WriterMutexLock&&) = delete;
|
||
|
|
||
|
~WriterMutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->WriterUnlock(); }
|
||
|
|
||
|
private:
|
||
|
Mutex *const mu_;
|
||
|
};
|
||
|
|
||
|
// -----------------------------------------------------------------------------
|
||
|
// Condition
|
||
|
// -----------------------------------------------------------------------------
|
||
|
//
|
||
|
// As noted above, `Mutex` contains a number of member functions which take a
|
||
|
// `Condition` as an argument; clients can wait for conditions to become `true`
|
||
|
// before attempting to acquire the mutex. These sections are known as
|
||
|
// "condition critical" sections. To use a `Condition`, you simply need to
|
||
|
// construct it, and use within an appropriate `Mutex` member function;
|
||
|
// everything else in the `Condition` class is an implementation detail.
|
||
|
//
|
||
|
// A `Condition` is specified as a function pointer which returns a boolean.
|
||
|
// `Condition` functions should be pure functions -- their results should depend
|
||
|
// only on passed arguments, should not consult any external state (such as
|
||
|
// clocks), and should have no side-effects, aside from debug logging. Any
|
||
|
// objects that the function may access should be limited to those which are
|
||
|
// constant while the mutex is blocked on the condition (e.g. a stack variable),
|
||
|
// or objects of state protected explicitly by the mutex.
|
||
|
//
|
||
|
// No matter which construction is used for `Condition`, the underlying
|
||
|
// function pointer / functor / callable must not throw any
|
||
|
// exceptions. Correctness of `Mutex` / `Condition` is not guaranteed in
|
||
|
// the face of a throwing `Condition`. (When Abseil is allowed to depend
|
||
|
// on C++17, these function pointers will be explicitly marked
|
||
|
// `noexcept`; until then this requirement cannot be enforced in the
|
||
|
// type system.)
|
||
|
//
|
||
|
// Note: to use a `Condition`, you need only construct it and pass it to a
|
||
|
// suitable `Mutex' member function, such as `Mutex::Await()`, or to the
|
||
|
// constructor of one of the scope guard classes.
|
||
|
//
|
||
|
// Example using LockWhen/Unlock:
|
||
|
//
|
||
|
// // assume count_ is not internal reference count
|
||
|
// int count_ ABSL_GUARDED_BY(mu_);
|
||
|
// Condition count_is_zero(+[](int *count) { return *count == 0; }, &count_);
|
||
|
//
|
||
|
// mu_.LockWhen(count_is_zero);
|
||
|
// // ...
|
||
|
// mu_.Unlock();
|
||
|
//
|
||
|
// Example using a scope guard:
|
||
|
//
|
||
|
// {
|
||
|
// MutexLock lock(&mu_, count_is_zero);
|
||
|
// // ...
|
||
|
// }
|
||
|
//
|
||
|
// When multiple threads are waiting on exactly the same condition, make sure
|
||
|
// that they are constructed with the same parameters (same pointer to function
|
||
|
// + arg, or same pointer to object + method), so that the mutex implementation
|
||
|
// can avoid redundantly evaluating the same condition for each thread.
|
||
|
class Condition {
|
||
|
public:
|
||
|
// A Condition that returns the result of "(*func)(arg)"
|
||
|
Condition(bool (*func)(void *), void *arg);
|
||
|
|
||
|
// Templated version for people who are averse to casts.
|
||
|
//
|
||
|
// To use a lambda, prepend it with unary plus, which converts the lambda
|
||
|
// into a function pointer:
|
||
|
// Condition(+[](T* t) { return ...; }, arg).
|
||
|
//
|
||
|
// Note: lambdas in this case must contain no bound variables.
|
||
|
//
|
||
|
// See class comment for performance advice.
|
||
|
template<typename T>
|
||
|
Condition(bool (*func)(T *), T *arg);
|
||
|
|
||
|
// Templated version for invoking a method that returns a `bool`.
|
||
|
//
|
||
|
// `Condition(object, &Class::Method)` constructs a `Condition` that evaluates
|
||
|
// `object->Method()`.
|
||
|
//
|
||
|
// Implementation Note: `absl::internal::identity` is used to allow methods to
|
||
|
// come from base classes. A simpler signature like
|
||
|
// `Condition(T*, bool (T::*)())` does not suffice.
|
||
|
template<typename T>
|
||
|
Condition(T *object, bool (absl::internal::identity<T>::type::* method)());
|
||
|
|
||
|
// Same as above, for const members
|
||
|
template<typename T>
|
||
|
Condition(const T *object,
|
||
|
bool (absl::internal::identity<T>::type::* method)() const);
|
||
|
|
||
|
// A Condition that returns the value of `*cond`
|
||
|
explicit Condition(const bool *cond);
|
||
|
|
||
|
// Templated version for invoking a functor that returns a `bool`.
|
||
|
// This approach accepts pointers to non-mutable lambdas, `std::function`,
|
||
|
// the result of` std::bind` and user-defined functors that define
|
||
|
// `bool F::operator()() const`.
|
||
|
//
|
||
|
// Example:
|
||
|
//
|
||
|
// auto reached = [this, current]() {
|
||
|
// mu_.AssertReaderHeld(); // For annotalysis.
|
||
|
// return processed_ >= current;
|
||
|
// };
|
||
|
// mu_.Await(Condition(&reached));
|
||
|
//
|
||
|
// NOTE: never use "mu_.AssertHeld()" instead of "mu_.AssertReaderHeld()" in
|
||
|
// the lambda as it may be called when the mutex is being unlocked from a
|
||
|
// scope holding only a reader lock, which will make the assertion not
|
||
|
// fulfilled and crash the binary.
|
||
|
|
||
|
// See class comment for performance advice. In particular, if there
|
||
|
// might be more than one waiter for the same condition, make sure
|
||
|
// that all waiters construct the condition with the same pointers.
|
||
|
|
||
|
// Implementation note: The second template parameter ensures that this
|
||
|
// constructor doesn't participate in overload resolution if T doesn't have
|
||
|
// `bool operator() const`.
|
||
|
template <typename T, typename E = decltype(
|
||
|
static_cast<bool (T::*)() const>(&T::operator()))>
|
||
|
explicit Condition(const T *obj)
|
||
|
: Condition(obj, static_cast<bool (T::*)() const>(&T::operator())) {}
|
||
|
|
||
|
// A Condition that always returns `true`.
|
||
|
static const Condition kTrue;
|
||
|
|
||
|
// Evaluates the condition.
|
||
|
bool Eval() const;
|
||
|
|
||
|
// Returns `true` if the two conditions are guaranteed to return the same
|
||
|
// value if evaluated at the same time, `false` if the evaluation *may* return
|
||
|
// different results.
|
||
|
//
|
||
|
// Two `Condition` values are guaranteed equal if both their `func` and `arg`
|
||
|
// components are the same. A null pointer is equivalent to a `true`
|
||
|
// condition.
|
||
|
static bool GuaranteedEqual(const Condition *a, const Condition *b);
|
||
|
|
||
|
private:
|
||
|
typedef bool (*InternalFunctionType)(void * arg);
|
||
|
typedef bool (Condition::*InternalMethodType)();
|
||
|
typedef bool (*InternalMethodCallerType)(void * arg,
|
||
|
InternalMethodType internal_method);
|
||
|
|
||
|
bool (*eval_)(const Condition*); // Actual evaluator
|
||
|
InternalFunctionType function_; // function taking pointer returning bool
|
||
|
InternalMethodType method_; // method returning bool
|
||
|
void *arg_; // arg of function_ or object of method_
|
||
|
|
||
|
Condition(); // null constructor used only to create kTrue
|
||
|
|
||
|
// Various functions eval_ can point to:
|
||
|
static bool CallVoidPtrFunction(const Condition*);
|
||
|
template <typename T> static bool CastAndCallFunction(const Condition* c);
|
||
|
template <typename T> static bool CastAndCallMethod(const Condition* c);
|
||
|
};
|
||
|
|
||
|
// -----------------------------------------------------------------------------
|
||
|
// CondVar
|
||
|
// -----------------------------------------------------------------------------
|
||
|
//
|
||
|
// A condition variable, reflecting state evaluated separately outside of the
|
||
|
// `Mutex` object, which can be signaled to wake callers.
|
||
|
// This class is not normally needed; use `Mutex` member functions such as
|
||
|
// `Mutex::Await()` and intrinsic `Condition` abstractions. In rare cases
|
||
|
// with many threads and many conditions, `CondVar` may be faster.
|
||
|
//
|
||
|
// The implementation may deliver signals to any condition variable at
|
||
|
// any time, even when no call to `Signal()` or `SignalAll()` is made; as a
|
||
|
// result, upon being awoken, you must check the logical condition you have
|
||
|
// been waiting upon.
|
||
|
//
|
||
|
// Examples:
|
||
|
//
|
||
|
// Usage for a thread waiting for some condition C protected by mutex mu:
|
||
|
// mu.Lock();
|
||
|
// while (!C) { cv->Wait(&mu); } // releases and reacquires mu
|
||
|
// // C holds; process data
|
||
|
// mu.Unlock();
|
||
|
//
|
||
|
// Usage to wake T is:
|
||
|
// mu.Lock();
|
||
|
// // process data, possibly establishing C
|
||
|
// if (C) { cv->Signal(); }
|
||
|
// mu.Unlock();
|
||
|
//
|
||
|
// If C may be useful to more than one waiter, use `SignalAll()` instead of
|
||
|
// `Signal()`.
|
||
|
//
|
||
|
// With this implementation it is efficient to use `Signal()/SignalAll()` inside
|
||
|
// the locked region; this usage can make reasoning about your program easier.
|
||
|
//
|
||
|
class CondVar {
|
||
|
public:
|
||
|
// A `CondVar` allocated on the heap or on the stack can use the this
|
||
|
// constructor.
|
||
|
CondVar();
|
||
|
~CondVar();
|
||
|
|
||
|
// CondVar::Wait()
|
||
|
//
|
||
|
// Atomically releases a `Mutex` and blocks on this condition variable.
|
||
|
// Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
|
||
|
// spurious wakeup), then reacquires the `Mutex` and returns.
|
||
|
//
|
||
|
// Requires and ensures that the current thread holds the `Mutex`.
|
||
|
void Wait(Mutex *mu);
|
||
|
|
||
|
// CondVar::WaitWithTimeout()
|
||
|
//
|
||
|
// Atomically releases a `Mutex` and blocks on this condition variable.
|
||
|
// Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
|
||
|
// spurious wakeup), or until the timeout has expired, then reacquires
|
||
|
// the `Mutex` and returns.
|
||
|
//
|
||
|
// Returns true if the timeout has expired without this `CondVar`
|
||
|
// being signalled in any manner. If both the timeout has expired
|
||
|
// and this `CondVar` has been signalled, the implementation is free
|
||
|
// to return `true` or `false`.
|
||
|
//
|
||
|
// Requires and ensures that the current thread holds the `Mutex`.
|
||
|
bool WaitWithTimeout(Mutex *mu, absl::Duration timeout);
|
||
|
|
||
|
// CondVar::WaitWithDeadline()
|
||
|
//
|
||
|
// Atomically releases a `Mutex` and blocks on this condition variable.
|
||
|
// Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
|
||
|
// spurious wakeup), or until the deadline has passed, then reacquires
|
||
|
// the `Mutex` and returns.
|
||
|
//
|
||
|
// Deadlines in the past are equivalent to an immediate deadline.
|
||
|
//
|
||
|
// Returns true if the deadline has passed without this `CondVar`
|
||
|
// being signalled in any manner. If both the deadline has passed
|
||
|
// and this `CondVar` has been signalled, the implementation is free
|
||
|
// to return `true` or `false`.
|
||
|
//
|
||
|
// Requires and ensures that the current thread holds the `Mutex`.
|
||
|
bool WaitWithDeadline(Mutex *mu, absl::Time deadline);
|
||
|
|
||
|
// CondVar::Signal()
|
||
|
//
|
||
|
// Signal this `CondVar`; wake at least one waiter if one exists.
|
||
|
void Signal();
|
||
|
|
||
|
// CondVar::SignalAll()
|
||
|
//
|
||
|
// Signal this `CondVar`; wake all waiters.
|
||
|
void SignalAll();
|
||
|
|
||
|
// CondVar::EnableDebugLog()
|
||
|
//
|
||
|
// Causes all subsequent uses of this `CondVar` to be logged via
|
||
|
// `ABSL_RAW_LOG(INFO)`. Log entries are tagged with `name` if `name != 0`.
|
||
|
// Note: this method substantially reduces `CondVar` performance.
|
||
|
void EnableDebugLog(const char *name);
|
||
|
|
||
|
private:
|
||
|
bool WaitCommon(Mutex *mutex, synchronization_internal::KernelTimeout t);
|
||
|
void Remove(base_internal::PerThreadSynch *s);
|
||
|
void Wakeup(base_internal::PerThreadSynch *w);
|
||
|
std::atomic<intptr_t> cv_; // Condition variable state.
|
||
|
CondVar(const CondVar&) = delete;
|
||
|
CondVar& operator=(const CondVar&) = delete;
|
||
|
};
|
||
|
|
||
|
|
||
|
// Variants of MutexLock.
|
||
|
//
|
||
|
// If you find yourself using one of these, consider instead using
|
||
|
// Mutex::Unlock() and/or if-statements for clarity.
|
||
|
|
||
|
// MutexLockMaybe
|
||
|
//
|
||
|
// MutexLockMaybe is like MutexLock, but is a no-op when mu is null.
|
||
|
class ABSL_SCOPED_LOCKABLE MutexLockMaybe {
|
||
|
public:
|
||
|
explicit MutexLockMaybe(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
if (this->mu_ != nullptr) {
|
||
|
this->mu_->Lock();
|
||
|
}
|
||
|
}
|
||
|
|
||
|
explicit MutexLockMaybe(Mutex *mu, const Condition &cond)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
if (this->mu_ != nullptr) {
|
||
|
this->mu_->LockWhen(cond);
|
||
|
}
|
||
|
}
|
||
|
|
||
|
~MutexLockMaybe() ABSL_UNLOCK_FUNCTION() {
|
||
|
if (this->mu_ != nullptr) { this->mu_->Unlock(); }
|
||
|
}
|
||
|
|
||
|
private:
|
||
|
Mutex *const mu_;
|
||
|
MutexLockMaybe(const MutexLockMaybe&) = delete;
|
||
|
MutexLockMaybe(MutexLockMaybe&&) = delete;
|
||
|
MutexLockMaybe& operator=(const MutexLockMaybe&) = delete;
|
||
|
MutexLockMaybe& operator=(MutexLockMaybe&&) = delete;
|
||
|
};
|
||
|
|
||
|
// ReleasableMutexLock
|
||
|
//
|
||
|
// ReleasableMutexLock is like MutexLock, but permits `Release()` of its
|
||
|
// mutex before destruction. `Release()` may be called at most once.
|
||
|
class ABSL_SCOPED_LOCKABLE ReleasableMutexLock {
|
||
|
public:
|
||
|
explicit ReleasableMutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
this->mu_->Lock();
|
||
|
}
|
||
|
|
||
|
explicit ReleasableMutexLock(Mutex *mu, const Condition &cond)
|
||
|
ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
|
||
|
: mu_(mu) {
|
||
|
this->mu_->LockWhen(cond);
|
||
|
}
|
||
|
|
||
|
~ReleasableMutexLock() ABSL_UNLOCK_FUNCTION() {
|
||
|
if (this->mu_ != nullptr) { this->mu_->Unlock(); }
|
||
|
}
|
||
|
|
||
|
void Release() ABSL_UNLOCK_FUNCTION();
|
||
|
|
||
|
private:
|
||
|
Mutex *mu_;
|
||
|
ReleasableMutexLock(const ReleasableMutexLock&) = delete;
|
||
|
ReleasableMutexLock(ReleasableMutexLock&&) = delete;
|
||
|
ReleasableMutexLock& operator=(const ReleasableMutexLock&) = delete;
|
||
|
ReleasableMutexLock& operator=(ReleasableMutexLock&&) = delete;
|
||
|
};
|
||
|
|
||
|
inline Mutex::Mutex() : mu_(0) {
|
||
|
ABSL_TSAN_MUTEX_CREATE(this, __tsan_mutex_not_static);
|
||
|
}
|
||
|
|
||
|
inline constexpr Mutex::Mutex(absl::ConstInitType) : mu_(0) {}
|
||
|
|
||
|
inline CondVar::CondVar() : cv_(0) {}
|
||
|
|
||
|
// static
|
||
|
template <typename T>
|
||
|
bool Condition::CastAndCallMethod(const Condition *c) {
|
||
|
typedef bool (T::*MemberType)();
|
||
|
MemberType rm = reinterpret_cast<MemberType>(c->method_);
|
||
|
T *x = static_cast<T *>(c->arg_);
|
||
|
return (x->*rm)();
|
||
|
}
|
||
|
|
||
|
// static
|
||
|
template <typename T>
|
||
|
bool Condition::CastAndCallFunction(const Condition *c) {
|
||
|
typedef bool (*FuncType)(T *);
|
||
|
FuncType fn = reinterpret_cast<FuncType>(c->function_);
|
||
|
T *x = static_cast<T *>(c->arg_);
|
||
|
return (*fn)(x);
|
||
|
}
|
||
|
|
||
|
template <typename T>
|
||
|
inline Condition::Condition(bool (*func)(T *), T *arg)
|
||
|
: eval_(&CastAndCallFunction<T>),
|
||
|
function_(reinterpret_cast<InternalFunctionType>(func)),
|
||
|
method_(nullptr),
|
||
|
arg_(const_cast<void *>(static_cast<const void *>(arg))) {}
|
||
|
|
||
|
template <typename T>
|
||
|
inline Condition::Condition(T *object,
|
||
|
bool (absl::internal::identity<T>::type::*method)())
|
||
|
: eval_(&CastAndCallMethod<T>),
|
||
|
function_(nullptr),
|
||
|
method_(reinterpret_cast<InternalMethodType>(method)),
|
||
|
arg_(object) {}
|
||
|
|
||
|
template <typename T>
|
||
|
inline Condition::Condition(const T *object,
|
||
|
bool (absl::internal::identity<T>::type::*method)()
|
||
|
const)
|
||
|
: eval_(&CastAndCallMethod<T>),
|
||
|
function_(nullptr),
|
||
|
method_(reinterpret_cast<InternalMethodType>(method)),
|
||
|
arg_(reinterpret_cast<void *>(const_cast<T *>(object))) {}
|
||
|
|
||
|
// Register a hook for profiling support.
|
||
|
//
|
||
|
// The function pointer registered here will be called whenever a mutex is
|
||
|
// contended. The callback is given the cycles for which waiting happened (as
|
||
|
// measured by //absl/base/internal/cycleclock.h, and which may not
|
||
|
// be real "cycle" counts.)
|
||
|
//
|
||
|
// Calls to this function do not race or block, but there is no ordering
|
||
|
// guaranteed between calls to this function and call to the provided hook.
|
||
|
// In particular, the previously registered hook may still be called for some
|
||
|
// time after this function returns.
|
||
|
void RegisterMutexProfiler(void (*fn)(int64_t wait_cycles));
|
||
|
|
||
|
// Register a hook for Mutex tracing.
|
||
|
//
|
||
|
// The function pointer registered here will be called whenever a mutex is
|
||
|
// contended. The callback is given an opaque handle to the contended mutex,
|
||
|
// an event name, and the number of wait cycles (as measured by
|
||
|
// //absl/base/internal/cycleclock.h, and which may not be real
|
||
|
// "cycle" counts.)
|
||
|
//
|
||
|
// The only event name currently sent is "slow release".
|
||
|
//
|
||
|
// This has the same memory ordering concerns as RegisterMutexProfiler() above.
|
||
|
void RegisterMutexTracer(void (*fn)(const char *msg, const void *obj,
|
||
|
int64_t wait_cycles));
|
||
|
|
||
|
// TODO(gfalcon): Combine RegisterMutexProfiler() and RegisterMutexTracer()
|
||
|
// into a single interface, since they are only ever called in pairs.
|
||
|
|
||
|
// Register a hook for CondVar tracing.
|
||
|
//
|
||
|
// The function pointer registered here will be called here on various CondVar
|
||
|
// events. The callback is given an opaque handle to the CondVar object and
|
||
|
// a string identifying the event. This is thread-safe, but only a single
|
||
|
// tracer can be registered.
|
||
|
//
|
||
|
// Events that can be sent are "Wait", "Unwait", "Signal wakeup", and
|
||
|
// "SignalAll wakeup".
|
||
|
//
|
||
|
// This has the same memory ordering concerns as RegisterMutexProfiler() above.
|
||
|
void RegisterCondVarTracer(void (*fn)(const char *msg, const void *cv));
|
||
|
|
||
|
// Register a hook for symbolizing stack traces in deadlock detector reports.
|
||
|
//
|
||
|
// 'pc' is the program counter being symbolized, 'out' is the buffer to write
|
||
|
// into, and 'out_size' is the size of the buffer. This function can return
|
||
|
// false if symbolizing failed, or true if a NUL-terminated symbol was written
|
||
|
// to 'out.'
|
||
|
//
|
||
|
// This has the same memory ordering concerns as RegisterMutexProfiler() above.
|
||
|
//
|
||
|
// DEPRECATED: The default symbolizer function is absl::Symbolize() and the
|
||
|
// ability to register a different hook for symbolizing stack traces will be
|
||
|
// removed on or after 2023-05-01.
|
||
|
ABSL_DEPRECATED("absl::RegisterSymbolizer() is deprecated and will be removed "
|
||
|
"on or after 2023-05-01")
|
||
|
void RegisterSymbolizer(bool (*fn)(const void *pc, char *out, int out_size));
|
||
|
|
||
|
// EnableMutexInvariantDebugging()
|
||
|
//
|
||
|
// Enable or disable global support for Mutex invariant debugging. If enabled,
|
||
|
// then invariant predicates can be registered per-Mutex for debug checking.
|
||
|
// See Mutex::EnableInvariantDebugging().
|
||
|
void EnableMutexInvariantDebugging(bool enabled);
|
||
|
|
||
|
// When in debug mode, and when the feature has been enabled globally, the
|
||
|
// implementation will keep track of lock ordering and complain (or optionally
|
||
|
// crash) if a cycle is detected in the acquired-before graph.
|
||
|
|
||
|
// Possible modes of operation for the deadlock detector in debug mode.
|
||
|
enum class OnDeadlockCycle {
|
||
|
kIgnore, // Neither report on nor attempt to track cycles in lock ordering
|
||
|
kReport, // Report lock cycles to stderr when detected
|
||
|
kAbort, // Report lock cycles to stderr when detected, then abort
|
||
|
};
|
||
|
|
||
|
// SetMutexDeadlockDetectionMode()
|
||
|
//
|
||
|
// Enable or disable global support for detection of potential deadlocks
|
||
|
// due to Mutex lock ordering inversions. When set to 'kIgnore', tracking of
|
||
|
// lock ordering is disabled. Otherwise, in debug builds, a lock ordering graph
|
||
|
// will be maintained internally, and detected cycles will be reported in
|
||
|
// the manner chosen here.
|
||
|
void SetMutexDeadlockDetectionMode(OnDeadlockCycle mode);
|
||
|
|
||
|
ABSL_NAMESPACE_END
|
||
|
} // namespace absl
|
||
|
|
||
|
// In some build configurations we pass --detect-odr-violations to the
|
||
|
// gold linker. This causes it to flag weak symbol overrides as ODR
|
||
|
// violations. Because ODR only applies to C++ and not C,
|
||
|
// --detect-odr-violations ignores symbols not mangled with C++ names.
|
||
|
// By changing our extension points to be extern "C", we dodge this
|
||
|
// check.
|
||
|
extern "C" {
|
||
|
void ABSL_INTERNAL_C_SYMBOL(AbslInternalMutexYield)();
|
||
|
} // extern "C"
|
||
|
|
||
|
#endif // ABSL_SYNCHRONIZATION_MUTEX_H_
|