| // 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 |
| // |
| // http://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. |
| // |
| // ----------------------------------------------------------------------------- |
| // File: thread_annotations.h |
| // ----------------------------------------------------------------------------- |
| // |
| // This header file contains macro definitions for thread safety annotations |
| // that allow developers to document the locking policies of multi-threaded |
| // code. The annotations can also help program analysis tools to identify |
| // potential thread safety issues. |
| // |
| // |
| // These annotations are implemented using compiler attributes. Using the macros |
| // defined here instead of raw attributes allow for portability and future |
| // compatibility. |
| // |
| // When referring to mutexes in the arguments of the attributes, you should |
| // use variable names or more complex expressions (e.g. my_object->mutex_) |
| // that evaluate to a concrete mutex object whenever possible. If the mutex |
| // you want to refer to is not in scope, you may use a member pointer |
| // (e.g. &MyClass::mutex_) to refer to a mutex in some (unknown) object. |
| |
| #ifndef ABSL_BASE_THREAD_ANNOTATIONS_H_ |
| #define ABSL_BASE_THREAD_ANNOTATIONS_H_ |
| #if defined(__clang__) |
| #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) |
| #else |
| #define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op |
| #endif |
| |
| // GUARDED_BY() |
| // |
| // Documents if a shared field or global variable needs to be protected by a |
| // mutex. GUARDED_BY() allows the user to specify a particular mutex that |
| // should be held when accessing the annotated variable. |
| // |
| // Although this annotation (and PT_GUARDED_BY, below) cannot be applied to |
| // local variables, a local variable and its associated mutex can often be |
| // combined into a small class or struct, thereby allowing the annotation. |
| // |
| // Example: |
| // |
| // class Foo { |
| // Mutex mu_; |
| // int p1_ GUARDED_BY(mu_); |
| // ... |
| // }; |
| #define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) |
| |
| // PT_GUARDED_BY() |
| // |
| // Documents if the memory location pointed to by a pointer should be guarded |
| // by a mutex when dereferencing the pointer. |
| // |
| // Example: |
| // class Foo { |
| // Mutex mu_; |
| // int *p1_ PT_GUARDED_BY(mu_); |
| // ... |
| // }; |
| // |
| // Note that a pointer variable to a shared memory location could itself be a |
| // shared variable. |
| // |
| // Example: |
| // |
| // // `q_`, guarded by `mu1_`, points to a shared memory location that is |
| // // guarded by `mu2_`: |
| // int *q_ GUARDED_BY(mu1_) PT_GUARDED_BY(mu2_); |
| #define PT_GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) |
| |
| // ACQUIRED_AFTER() / ACQUIRED_BEFORE() |
| // |
| // Documents the acquisition order between locks that can be held |
| // simultaneously by a thread. For any two locks that need to be annotated |
| // to establish an acquisition order, only one of them needs the annotation. |
| // (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER |
| // and ACQUIRED_BEFORE.) |
| // |
| // As with GUARDED_BY, this is only applicable to mutexes that are shared |
| // fields or global variables. |
| // |
| // Example: |
| // |
| // Mutex m1_; |
| // Mutex m2_ ACQUIRED_AFTER(m1_); |
| #define ACQUIRED_AFTER(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__)) |
| |
| #define ACQUIRED_BEFORE(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__)) |
| |
| // EXCLUSIVE_LOCKS_REQUIRED() / SHARED_LOCKS_REQUIRED() |
| // |
| // Documents a function that expects a mutex to be held prior to entry. |
| // The mutex is expected to be held both on entry to, and exit from, the |
| // function. |
| // |
| // An exclusive lock allows read-write access to the guarded data member(s), and |
| // only one thread can acquire a lock exclusively at any one time. A shared lock |
| // allows read-only access, and any number of threads can acquire a shared lock |
| // concurrently. |
| // |
| // Generally, non-const methods should be annotated with |
| // EXCLUSIVE_LOCKS_REQUIRED, while const methods should be annotated with |
| // SHARED_LOCKS_REQUIRED. |
| // |
| // Example: |
| // |
| // Mutex mu1, mu2; |
| // int a GUARDED_BY(mu1); |
| // int b GUARDED_BY(mu2); |
| // |
| // void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... } |
| // void bar() const SHARED_LOCKS_REQUIRED(mu1, mu2) { ... } |
| #define EXCLUSIVE_LOCKS_REQUIRED(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__)) |
| |
| #define SHARED_LOCKS_REQUIRED(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__)) |
| |
| // LOCKS_EXCLUDED() |
| // |
| // Documents the locks acquired in the body of the function. These locks |
| // cannot be held when calling this function (as Abseil's `Mutex` locks are |
| // non-reentrant). |
| #define LOCKS_EXCLUDED(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__)) |
| |
| // LOCK_RETURNED() |
| // |
| // Documents a function that returns a mutex without acquiring it. For example, |
| // a public getter method that returns a pointer to a private mutex should |
| // be annotated with LOCK_RETURNED. |
| #define LOCK_RETURNED(x) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) |
| |
| // LOCKABLE |
| // |
| // Documents if a class/type is a lockable type (such as the `Mutex` class). |
| #define LOCKABLE \ |
| THREAD_ANNOTATION_ATTRIBUTE__(lockable) |
| |
| // SCOPED_LOCKABLE |
| // |
| // Documents if a class does RAII locking (such as the `MutexLock` class). |
| // The constructor should use `LOCK_FUNCTION()` to specify the mutex that is |
| // acquired, and the destructor should use `UNLOCK_FUNCTION()` with no |
| // arguments; the analysis will assume that the destructor unlocks whatever the |
| // constructor locked. |
| #define SCOPED_LOCKABLE \ |
| THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) |
| |
| // EXCLUSIVE_LOCK_FUNCTION() |
| // |
| // Documents functions that acquire a lock in the body of a function, and do |
| // not release it. |
| #define EXCLUSIVE_LOCK_FUNCTION(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__)) |
| |
| // SHARED_LOCK_FUNCTION() |
| // |
| // Documents functions that acquire a shared (reader) lock in the body of a |
| // function, and do not release it. |
| #define SHARED_LOCK_FUNCTION(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__)) |
| |
| // UNLOCK_FUNCTION() |
| // |
| // Documents functions that expect a lock to be held on entry to the function, |
| // and release it in the body of the function. |
| #define UNLOCK_FUNCTION(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__)) |
| |
| // EXCLUSIVE_TRYLOCK_FUNCTION() / SHARED_TRYLOCK_FUNCTION() |
| // |
| // Documents functions that try to acquire a lock, and return success or failure |
| // (or a non-boolean value that can be interpreted as a boolean). |
| // The first argument should be `true` for functions that return `true` on |
| // success, or `false` for functions that return `false` on success. The second |
| // argument specifies the mutex that is locked on success. If unspecified, this |
| // mutex is assumed to be `this`. |
| #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__)) |
| |
| #define SHARED_TRYLOCK_FUNCTION(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__)) |
| |
| // ASSERT_EXCLUSIVE_LOCK() / ASSERT_SHARED_LOCK() |
| // |
| // Documents functions that dynamically check to see if a lock is held, and fail |
| // if it is not held. |
| #define ASSERT_EXCLUSIVE_LOCK(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__)) |
| |
| #define ASSERT_SHARED_LOCK(...) \ |
| THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__)) |
| |
| // NO_THREAD_SAFETY_ANALYSIS |
| // |
| // Turns off thread safety checking within the body of a particular function. |
| // This annotation is used to mark functions that are known to be correct, but |
| // the locking behavior is more complicated than the analyzer can handle. |
| #define NO_THREAD_SAFETY_ANALYSIS \ |
| THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) |
| |
| //------------------------------------------------------------------------------ |
| // Tool-Supplied Annotations |
| //------------------------------------------------------------------------------ |
| |
| // TS_UNCHECKED should be placed around lock expressions that are not valid |
| // C++ syntax, but which are present for documentation purposes. These |
| // annotations will be ignored by the analysis. |
| #define TS_UNCHECKED(x) "" |
| |
| // TS_FIXME is used to mark lock expressions that are not valid C++ syntax. |
| // It is used by automated tools to mark and disable invalid expressions. |
| // The annotation should either be fixed, or changed to TS_UNCHECKED. |
| #define TS_FIXME(x) "" |
| |
| // Like NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body of |
| // a particular function. However, this attribute is used to mark functions |
| // that are incorrect and need to be fixed. It is used by automated tools to |
| // avoid breaking the build when the analysis is updated. |
| // Code owners are expected to eventually fix the routine. |
| #define NO_THREAD_SAFETY_ANALYSIS_FIXME NO_THREAD_SAFETY_ANALYSIS |
| |
| // Similar to NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a GUARDED_BY |
| // annotation that needs to be fixed, because it is producing thread safety |
| // warning. It disables the GUARDED_BY. |
| #define GUARDED_BY_FIXME(x) |
| |
| // Disables warnings for a single read operation. This can be used to avoid |
| // warnings when it is known that the read is not actually involved in a race, |
| // but the compiler cannot confirm that. |
| #define TS_UNCHECKED_READ(x) thread_safety_analysis::ts_unchecked_read(x) |
| |
| |
| namespace thread_safety_analysis { |
| |
| // Takes a reference to a guarded data member, and returns an unguarded |
| // reference. |
| template <typename T> |
| inline const T& ts_unchecked_read(const T& v) NO_THREAD_SAFETY_ANALYSIS { |
| return v; |
| } |
| |
| template <typename T> |
| inline T& ts_unchecked_read(T& v) NO_THREAD_SAFETY_ANALYSIS { |
| return v; |
| } |
| |
| } // namespace thread_safety_analysis |
| |
| #endif // ABSL_BASE_THREAD_ANNOTATIONS_H_ |