diff options
author | anastasy888 <anastasy888@yandex-team.ru> | 2022-02-10 16:45:54 +0300 |
---|---|---|
committer | Daniil Cherednik <dcherednik@yandex-team.ru> | 2022-02-10 16:45:54 +0300 |
commit | 49f765d71da452ea93138a25559dfa68dd76c7f3 (patch) | |
tree | 1016041feb637349e401dcc0fa85217dd2c2c639 /contrib/restricted/abseil-cpp-tstring/y_absl/synchronization/mutex.h | |
parent | 7353a3fdea9c67c256980c00a2b3b67f09b23a27 (diff) | |
download | ydb-49f765d71da452ea93138a25559dfa68dd76c7f3.tar.gz |
Restoring authorship annotation for <anastasy888@yandex-team.ru>. Commit 1 of 2.
Diffstat (limited to 'contrib/restricted/abseil-cpp-tstring/y_absl/synchronization/mutex.h')
-rw-r--r-- | contrib/restricted/abseil-cpp-tstring/y_absl/synchronization/mutex.h | 1910 |
1 files changed, 955 insertions, 955 deletions
diff --git a/contrib/restricted/abseil-cpp-tstring/y_absl/synchronization/mutex.h b/contrib/restricted/abseil-cpp-tstring/y_absl/synchronization/mutex.h index 0762a852df..23ba954b1f 100644 --- a/contrib/restricted/abseil-cpp-tstring/y_absl/synchronization/mutex.h +++ b/contrib/restricted/abseil-cpp-tstring/y_absl/synchronization/mutex.h @@ -1,67 +1,67 @@ -// 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 +// 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. -// +// +// 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> +// +// 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 <util/generic/string.h> - + #include "y_absl/base/const_init.h" #include "y_absl/base/internal/identity.h" #include "y_absl/base/internal/low_level_alloc.h" @@ -72,460 +72,460 @@ #include "y_absl/synchronization/internal/kernel_timeout.h" #include "y_absl/synchronization/internal/per_thread_sem.h" #include "y_absl/time/time.h" - + namespace y_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 + +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(y_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 + 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 y_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 { + // + // 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 y_absl::Mutex mu(y_absl::kConstInit); - // } + // } explicit constexpr Mutex(y_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 + + ~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() - // - // Return immediately if this thread holds the `Mutex` exclusively (in write - // mode). Otherwise, may report an error (typically by crashing with a - // diagnostic), or may return immediately. - 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() - // - // Returns immediately if this thread holds the `Mutex` in at least shared - // mode (read mode). Otherwise, may report an error (typically by - // crashing with a diagnostic), or may return immediately. - 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() - // + 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() + // + // Return immediately if this thread holds the `Mutex` exclusively (in write + // mode). Otherwise, may report an error (typically by crashing with a + // diagnostic), or may return immediately. + 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() + // + // Returns immediately if this thread holds the `Mutex` in at least shared + // mode (read mode). Otherwise, may report an error (typically by + // crashing with a diagnostic), or may return immediately. + 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. - // + // - 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. + // 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, y_absl::Duration timeout); - + bool AwaitWithDeadline(const Condition &cond, y_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. + + // 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, y_absl::Duration timeout) - ABSL_EXCLUSIVE_LOCK_FUNCTION(); + ABSL_EXCLUSIVE_LOCK_FUNCTION(); bool ReaderLockWhenWithTimeout(const Condition &cond, y_absl::Duration timeout) - ABSL_SHARED_LOCK_FUNCTION(); + ABSL_SHARED_LOCK_FUNCTION(); bool WriterLockWhenWithTimeout(const Condition &cond, y_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. + 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, y_absl::Time deadline) - ABSL_EXCLUSIVE_LOCK_FUNCTION(); + ABSL_EXCLUSIVE_LOCK_FUNCTION(); bool ReaderLockWhenWithDeadline(const Condition &cond, y_absl::Time deadline) - ABSL_SHARED_LOCK_FUNCTION(); + ABSL_SHARED_LOCK_FUNCTION(); bool WriterLockWhenWithDeadline(const Condition &cond, y_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. + 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 { + + // 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() { +// Foo::Bar* Baz() { // MutexLock lock(&mu_); -// ... -// return bar; -// } -// -// private: +// ... +// return bar; +// } +// +// private: // Mutex mu_; -// }; -class ABSL_SCOPED_LOCKABLE MutexLock { - public: +// }; +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(); - } - + 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. @@ -535,113 +535,113 @@ class ABSL_SCOPED_LOCKABLE MutexLock { 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(); - } - + 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(); - } - + 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.) -// + 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_); +// +// // 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: // // { @@ -649,236 +649,236 @@ class ABSL_SCOPED_LOCKABLE WriterMutexLock { // // ... // } // -// 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()`. - // +// 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: `y_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> + // come from base classes. A simpler signature like + // `Condition(T*, bool (T::*)())` does not suffice. + template<typename T> Condition(T *object, bool (y_absl::internal::identity<T>::type::* method)()); - - // Same as above, for const members - template<typename T> - Condition(const T *object, + + // Same as above, for const members + template<typename T> + Condition(const T *object, bool (y_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)); + + // 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(); + + // 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: +// +// 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`. + 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, y_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`. + + // 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, y_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(); - } - } + + // 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) @@ -888,28 +888,28 @@ class ABSL_SCOPED_LOCKABLE MutexLockMaybe { } } - ~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(); - } + ~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) @@ -917,166 +917,166 @@ class ABSL_SCOPED_LOCKABLE ReleasableMutexLock { 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); -} - + ~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(y_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, + +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 (y_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, + : eval_(&CastAndCallMethod<T>), + function_(nullptr), + method_(reinterpret_cast<InternalMethodType>(method)), + arg_(object) {} + +template <typename T> +inline Condition::Condition(const T *object, bool (y_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 + 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 y_absl/base/cycleclock.h timestamp when -// waiting began. -// -// 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_timestamp)); - -// 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 +// waiting began. +// +// 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_timestamp)); + +// 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 // //y_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, +// "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 + +// 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. -// +// to 'out.' +// +// This has the same memory ordering concerns as RegisterMutexProfiler() above. +// // DEPRECATED: The default symbolizer function is y_absl::Symbolize() and the -// ability to register a different hook for symbolizing stack traces will be -// removed on or after 2023-05-01. +// ability to register a different hook for symbolizing stack traces will be +// removed on or after 2023-05-01. ABSL_DEPRECATED("y_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); - + "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 y_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" { + +// 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_ +} // extern "C" + +#endif // ABSL_SYNCHRONIZATION_MUTEX_H_ |