1 // Copyright (c) 2018 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // This header file contains macro definitions for thread safety annotations
6 // that allow developers to document the locking policies of multi-threaded
7 // code. The annotations can also help program analysis tools to identify
8 // potential thread safety issues.
10 // Note that the annotations we use are described as deprecated in the Clang
11 // documentation, linked below. E.g. we use EXCLUSIVE_LOCKS_REQUIRED where the
12 // Clang docs use REQUIRES.
14 // http://clang.llvm.org/docs/ThreadSafetyAnalysis.html
16 // We use the deprecated Clang annotations to match Abseil (relevant header
17 // linked below) and its ecosystem of libraries. We will follow Abseil with
18 // respect to upgrading to more modern annotations.
20 // https://github.com/abseil/abseil-cpp/blob/master/absl/base/thread_annotations.h
22 // These annotations are implemented using compiler attributes. Using the macros
23 // defined here instead of raw attributes allow for portability and future
26 // When referring to mutexes in the arguments of the attributes, you should
27 // use variable names or more complex expressions (e.g. my_object->mutex_)
28 // that evaluate to a concrete mutex object whenever possible. If the mutex
29 // you want to refer to is not in scope, you may use a member pointer
30 // (e.g. &MyClass::mutex_) to refer to a mutex in some (unknown) object.
32 #ifndef BASE_THREAD_ANNOTATIONS_H_
33 #define BASE_THREAD_ANNOTATIONS_H_
35 #include "base/check_op.h"
36 #include "build/build_config.h"
38 #if defined(__clang__)
39 #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
41 #define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
46 // Documents if a shared field or global variable needs to be protected by a
47 // mutex. GUARDED_BY() allows the user to specify a particular mutex that
48 // should be held when accessing the annotated variable.
53 // int p1 GUARDED_BY(mu);
54 #define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
58 // Documents if the memory location pointed to by a pointer should be guarded
59 // by a mutex when dereferencing the pointer.
63 // int *p1 PT_GUARDED_BY(mu);
65 // Note that a pointer variable to a shared memory location could itself be a
70 // // `q`, guarded by `mu1`, points to a shared memory location that is
71 // // guarded by `mu2`:
72 // int *q GUARDED_BY(mu1) PT_GUARDED_BY(mu2);
73 #define PT_GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
75 // ACQUIRED_AFTER() / ACQUIRED_BEFORE()
77 // Documents the acquisition order between locks that can be held
78 // simultaneously by a thread. For any two locks that need to be annotated
79 // to establish an acquisition order, only one of them needs the annotation.
80 // (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER
81 // and ACQUIRED_BEFORE.)
86 // Mutex m2 ACQUIRED_AFTER(m1);
87 #define ACQUIRED_AFTER(...) \
88 THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
90 #define ACQUIRED_BEFORE(...) \
91 THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
93 // EXCLUSIVE_LOCKS_REQUIRED() / SHARED_LOCKS_REQUIRED()
95 // Documents a function that expects a mutex to be held prior to entry.
96 // The mutex is expected to be held both on entry to, and exit from, the
102 // int a GUARDED_BY(mu1);
103 // int b GUARDED_BY(mu2);
105 // void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... };
106 #define EXCLUSIVE_LOCKS_REQUIRED(...) \
107 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
109 #define SHARED_LOCKS_REQUIRED(...) \
110 THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
114 // Documents the locks acquired in the body of the function. These locks
115 // cannot be held when calling this function (as Abseil's `Mutex` locks are
117 #define LOCKS_EXCLUDED(...) \
118 THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
122 // Documents a function that returns a mutex without acquiring it. For example,
123 // a public getter method that returns a pointer to a private mutex should
124 // be annotated with LOCK_RETURNED.
125 #define LOCK_RETURNED(x) THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
129 // Documents if a class/type is a lockable type (such as the `Mutex` class).
130 #define LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(lockable)
134 // Documents if a class does RAII locking (such as the `MutexLock` class).
135 // The constructor should use `LOCK_FUNCTION()` to specify the mutex that is
136 // acquired, and the destructor should use `UNLOCK_FUNCTION()` with no
137 // arguments; the analysis will assume that the destructor unlocks whatever the
138 // constructor locked.
139 #define SCOPED_LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
141 // EXCLUSIVE_LOCK_FUNCTION()
143 // Documents functions that acquire a lock in the body of a function, and do
145 #define EXCLUSIVE_LOCK_FUNCTION(...) \
146 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
148 // SHARED_LOCK_FUNCTION()
150 // Documents functions that acquire a shared (reader) lock in the body of a
151 // function, and do not release it.
152 #define SHARED_LOCK_FUNCTION(...) \
153 THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
157 // Documents functions that expect a lock to be held on entry to the function,
158 // and release it in the body of the function.
159 #define UNLOCK_FUNCTION(...) \
160 THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
162 // EXCLUSIVE_TRYLOCK_FUNCTION() / SHARED_TRYLOCK_FUNCTION()
164 // Documents functions that try to acquire a lock, and return success or failure
165 // (or a non-boolean value that can be interpreted as a boolean).
166 // The first argument should be `true` for functions that return `true` on
167 // success, or `false` for functions that return `false` on success. The second
168 // argument specifies the mutex that is locked on success. If unspecified, this
169 // mutex is assumed to be `this`.
170 #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
171 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
173 #define SHARED_TRYLOCK_FUNCTION(...) \
174 THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
176 // ASSERT_EXCLUSIVE_LOCK() / ASSERT_SHARED_LOCK()
178 // Documents functions that dynamically check to see if a lock is held, and fail
179 // if it is not held.
180 #define ASSERT_EXCLUSIVE_LOCK(...) \
181 THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
183 #define ASSERT_SHARED_LOCK(...) \
184 THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
186 // NO_THREAD_SAFETY_ANALYSIS
188 // Turns off thread safety checking within the body of a particular function.
189 // This annotation is used to mark functions that are known to be correct, but
190 // the locking behavior is more complicated than the analyzer can handle.
191 #define NO_THREAD_SAFETY_ANALYSIS \
192 THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
194 //------------------------------------------------------------------------------
195 // Tool-Supplied Annotations
196 //------------------------------------------------------------------------------
198 // TS_UNCHECKED should be placed around lock expressions that are not valid
199 // C++ syntax, but which are present for documentation purposes. These
200 // annotations will be ignored by the analysis.
201 #define TS_UNCHECKED(x) ""
203 // TS_FIXME is used to mark lock expressions that are not valid C++ syntax.
204 // It is used by automated tools to mark and disable invalid expressions.
205 // The annotation should either be fixed, or changed to TS_UNCHECKED.
206 #define TS_FIXME(x) ""
208 // Like NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body of
209 // a particular function. However, this attribute is used to mark functions
210 // that are incorrect and need to be fixed. It is used by automated tools to
211 // avoid breaking the build when the analysis is updated.
212 // Code owners are expected to eventually fix the routine.
213 #define NO_THREAD_SAFETY_ANALYSIS_FIXME NO_THREAD_SAFETY_ANALYSIS
215 // Similar to NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a GUARDED_BY
216 // annotation that needs to be fixed, because it is producing thread safety
217 // warning. It disables the GUARDED_BY.
218 #define GUARDED_BY_FIXME(x)
220 // Disables warnings for a single read operation. This can be used to avoid
221 // warnings when it is known that the read is not actually involved in a race,
222 // but the compiler cannot confirm that.
223 #define TS_UNCHECKED_READ(x) thread_safety_analysis::ts_unchecked_read(x)
225 namespace thread_safety_analysis {
227 // Takes a reference to a guarded data member, and returns an unguarded
229 template <typename T>
230 inline const T& ts_unchecked_read(const T& v) NO_THREAD_SAFETY_ANALYSIS {
234 template <typename T>
235 inline T& ts_unchecked_read(T& v) NO_THREAD_SAFETY_ANALYSIS {
239 } // namespace thread_safety_analysis
241 // The above is imported as-is from abseil-cpp. The following Chromium-specific
242 // synonyms are added for Chromium concepts (SequenceChecker/ThreadChecker).
245 // Equivalent to GUARDED_BY for SequenceChecker/ThreadChecker. Currently,
246 // clang's error message "requires holding mutex" is misleading. Usage of this
247 // macro is discouraged until the message is updated.
248 // TODO(etiennep): Update comment above once clang's error message is updated.
249 #define GUARDED_BY_CONTEXT(name) GUARDED_BY(name)
251 // Equivalent to EXCLUSIVE_LOCKS_REQUIRED for SequenceChecker/ThreadChecker.
252 // Currently, clang's error message "requires holding mutex" is misleading.
253 // Usage of this macro is discouraged until the message is updated.
254 // TODO(etiennep): Update comment above once clang's error message is updated.
255 #define VALID_CONTEXT_REQUIRED(name) EXCLUSIVE_LOCKS_REQUIRED(name)
257 #else // DCHECK_IS_ON()
259 #define GUARDED_BY_CONTEXT(name)
260 #define VALID_CONTEXT_REQUIRED(name)
262 #endif // DCHECK_IS_ON()
264 #endif // BASE_THREAD_ANNOTATIONS_H_