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