thread_annotations.h
Go to the documentation of this file.
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 // File: thread_annotations.h
17 // -----------------------------------------------------------------------------
18 //
19 // This header file contains macro definitions for thread safety annotations
20 // that allow developers to document the locking policies of multi-threaded
21 // code. The annotations can also help program analysis tools to identify
22 // potential thread safety issues.
23 //
24 // These annotations are implemented using compiler attributes. Using the macros
25 // defined here instead of raw attributes allow for portability and future
26 // compatibility.
27 //
28 // When referring to mutexes in the arguments of the attributes, you should
29 // use variable names or more complex expressions (e.g. my_object->mutex_)
30 // that evaluate to a concrete mutex object whenever possible. If the mutex
31 // you want to refer to is not in scope, you may use a member pointer
32 // (e.g. &MyClass::mutex_) to refer to a mutex in some (unknown) object.
33 
34 #ifndef ABSL_BASE_THREAD_ANNOTATIONS_H_
35 #define ABSL_BASE_THREAD_ANNOTATIONS_H_
36 
37 #if defined(__clang__)
38 #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
39 #else
40 #define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
41 #endif
42 
43 // GUARDED_BY()
44 //
45 // Documents if a shared field or global variable needs to be protected by a
46 // mutex. GUARDED_BY() allows the user to specify a particular mutex that
47 // should be held when accessing the annotated variable.
48 //
49 // Although this annotation (and PT_GUARDED_BY, below) cannot be applied to
50 // local variables, a local variable and its associated mutex can often be
51 // combined into a small class or struct, thereby allowing the annotation.
52 //
53 // Example:
54 //
55 // class Foo {
56 // Mutex mu_;
57 // int p1_ GUARDED_BY(mu_);
58 // ...
59 // };
60 #define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
61 
62 // PT_GUARDED_BY()
63 //
64 // Documents if the memory location pointed to by a pointer should be guarded
65 // by a mutex when dereferencing the pointer.
66 //
67 // Example:
68 // class Foo {
69 // Mutex mu_;
70 // int *p1_ PT_GUARDED_BY(mu_);
71 // ...
72 // };
73 //
74 // Note that a pointer variable to a shared memory location could itself be a
75 // shared variable.
76 //
77 // Example:
78 //
79 // // `q_`, guarded by `mu1_`, points to a shared memory location that is
80 // // guarded by `mu2_`:
81 // int *q_ GUARDED_BY(mu1_) PT_GUARDED_BY(mu2_);
82 #define PT_GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
83 
84 // ACQUIRED_AFTER() / ACQUIRED_BEFORE()
85 //
86 // Documents the acquisition order between locks that can be held
87 // simultaneously by a thread. For any two locks that need to be annotated
88 // to establish an acquisition order, only one of them needs the annotation.
89 // (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER
90 // and ACQUIRED_BEFORE.)
91 //
92 // As with GUARDED_BY, this is only applicable to mutexes that are shared
93 // fields or global variables.
94 //
95 // Example:
96 //
97 // Mutex m1_;
98 // Mutex m2_ ACQUIRED_AFTER(m1_);
99 #define ACQUIRED_AFTER(...) \
100  THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
101 
102 #define ACQUIRED_BEFORE(...) \
103  THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
104 
105 // EXCLUSIVE_LOCKS_REQUIRED() / SHARED_LOCKS_REQUIRED()
106 //
107 // Documents a function that expects a mutex to be held prior to entry.
108 // The mutex is expected to be held both on entry to, and exit from, the
109 // function.
110 //
111 // An exclusive lock allows read-write access to the guarded data member(s), and
112 // only one thread can acquire a lock exclusively at any one time. A shared lock
113 // allows read-only access, and any number of threads can acquire a shared lock
114 // concurrently.
115 //
116 // Generally, non-const methods should be annotated with
117 // EXCLUSIVE_LOCKS_REQUIRED, while const methods should be annotated with
118 // SHARED_LOCKS_REQUIRED.
119 //
120 // Example:
121 //
122 // Mutex mu1, mu2;
123 // int a GUARDED_BY(mu1);
124 // int b GUARDED_BY(mu2);
125 //
126 // void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... }
127 // void bar() const SHARED_LOCKS_REQUIRED(mu1, mu2) { ... }
128 #define EXCLUSIVE_LOCKS_REQUIRED(...) \
129  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
130 
131 #define SHARED_LOCKS_REQUIRED(...) \
132  THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
133 
134 // LOCKS_EXCLUDED()
135 //
136 // Documents the locks acquired in the body of the function. These locks
137 // cannot be held when calling this function (as Abseil's `Mutex` locks are
138 // non-reentrant).
139 #define LOCKS_EXCLUDED(...) \
140  THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
141 
142 // LOCK_RETURNED()
143 //
144 // Documents a function that returns a mutex without acquiring it. For example,
145 // a public getter method that returns a pointer to a private mutex should
146 // be annotated with LOCK_RETURNED.
147 #define LOCK_RETURNED(x) \
148  THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
149 
150 // LOCKABLE
151 //
152 // Documents if a class/type is a lockable type (such as the `Mutex` class).
153 #define LOCKABLE \
154  THREAD_ANNOTATION_ATTRIBUTE__(lockable)
155 
156 // SCOPED_LOCKABLE
157 //
158 // Documents if a class does RAII locking (such as the `MutexLock` class).
159 // The constructor should use `LOCK_FUNCTION()` to specify the mutex that is
160 // acquired, and the destructor should use `UNLOCK_FUNCTION()` with no
161 // arguments; the analysis will assume that the destructor unlocks whatever the
162 // constructor locked.
163 #define SCOPED_LOCKABLE \
164  THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
165 
166 // EXCLUSIVE_LOCK_FUNCTION()
167 //
168 // Documents functions that acquire a lock in the body of a function, and do
169 // not release it.
170 #define EXCLUSIVE_LOCK_FUNCTION(...) \
171  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
172 
173 // SHARED_LOCK_FUNCTION()
174 //
175 // Documents functions that acquire a shared (reader) lock in the body of a
176 // function, and do not release it.
177 #define SHARED_LOCK_FUNCTION(...) \
178  THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
179 
180 // UNLOCK_FUNCTION()
181 //
182 // Documents functions that expect a lock to be held on entry to the function,
183 // and release it in the body of the function.
184 #define UNLOCK_FUNCTION(...) \
185  THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
186 
187 // EXCLUSIVE_TRYLOCK_FUNCTION() / SHARED_TRYLOCK_FUNCTION()
188 //
189 // Documents functions that try to acquire a lock, and return success or failure
190 // (or a non-boolean value that can be interpreted as a boolean).
191 // The first argument should be `true` for functions that return `true` on
192 // success, or `false` for functions that return `false` on success. The second
193 // argument specifies the mutex that is locked on success. If unspecified, this
194 // mutex is assumed to be `this`.
195 #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
196  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
197 
198 #define SHARED_TRYLOCK_FUNCTION(...) \
199  THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
200 
201 // ASSERT_EXCLUSIVE_LOCK() / ASSERT_SHARED_LOCK()
202 //
203 // Documents functions that dynamically check to see if a lock is held, and fail
204 // if it is not held.
205 #define ASSERT_EXCLUSIVE_LOCK(...) \
206  THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
207 
208 #define ASSERT_SHARED_LOCK(...) \
209  THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
210 
211 // NO_THREAD_SAFETY_ANALYSIS
212 //
213 // Turns off thread safety checking within the body of a particular function.
214 // This annotation is used to mark functions that are known to be correct, but
215 // the locking behavior is more complicated than the analyzer can handle.
216 #define NO_THREAD_SAFETY_ANALYSIS \
217  THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
218 
219 //------------------------------------------------------------------------------
220 // Tool-Supplied Annotations
221 //------------------------------------------------------------------------------
222 
223 // TS_UNCHECKED should be placed around lock expressions that are not valid
224 // C++ syntax, but which are present for documentation purposes. These
225 // annotations will be ignored by the analysis.
226 #define TS_UNCHECKED(x) ""
227 
228 // TS_FIXME is used to mark lock expressions that are not valid C++ syntax.
229 // It is used by automated tools to mark and disable invalid expressions.
230 // The annotation should either be fixed, or changed to TS_UNCHECKED.
231 #define TS_FIXME(x) ""
232 
233 // Like NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body of
234 // a particular function. However, this attribute is used to mark functions
235 // that are incorrect and need to be fixed. It is used by automated tools to
236 // avoid breaking the build when the analysis is updated.
237 // Code owners are expected to eventually fix the routine.
238 #define NO_THREAD_SAFETY_ANALYSIS_FIXME NO_THREAD_SAFETY_ANALYSIS
239 
240 // Similar to NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a GUARDED_BY
241 // annotation that needs to be fixed, because it is producing thread safety
242 // warning. It disables the GUARDED_BY.
243 #define GUARDED_BY_FIXME(x)
244 
245 // Disables warnings for a single read operation. This can be used to avoid
246 // warnings when it is known that the read is not actually involved in a race,
247 // but the compiler cannot confirm that.
248 #define TS_UNCHECKED_READ(x) thread_safety_analysis::ts_unchecked_read(x)
249 
250 
252 
253 // Takes a reference to a guarded data member, and returns an unguarded
254 // reference.
255 template <typename T>
256 inline const T& ts_unchecked_read(const T& v) NO_THREAD_SAFETY_ANALYSIS {
257  return v;
258 }
259 
260 template <typename T>
262  return v;
263 }
264 
265 } // namespace thread_safety_analysis
266 
267 #endif // ABSL_BASE_THREAD_ANNOTATIONS_H_
int v
Definition: variant_test.cc:81
const T & ts_unchecked_read(const T &v) NO_THREAD_SAFETY_ANALYSIS
#define NO_THREAD_SAFETY_ANALYSIS


abseil_cpp
Author(s):
autogenerated on Mon Feb 28 2022 21:31:20