thread_annotations.h (11918B)
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 #include "absl/base/attributes.h" 38 #include "absl/base/config.h" 39 40 // ABSL_GUARDED_BY() 41 // 42 // Documents if a shared field or global variable needs to be protected by a 43 // mutex. ABSL_GUARDED_BY() allows the user to specify a particular mutex that 44 // should be held when accessing the annotated variable. 45 // 46 // Although this annotation (and ABSL_PT_GUARDED_BY, below) cannot be applied to 47 // local variables, a local variable and its associated mutex can often be 48 // combined into a small class or struct, thereby allowing the annotation. 49 // 50 // Example: 51 // 52 // class Foo { 53 // Mutex mu_; 54 // int p1_ ABSL_GUARDED_BY(mu_); 55 // ... 56 // }; 57 #if ABSL_HAVE_ATTRIBUTE(guarded_by) 58 #define ABSL_GUARDED_BY(x) __attribute__((guarded_by(x))) 59 #else 60 #define ABSL_GUARDED_BY(x) 61 #endif 62 63 // ABSL_PT_GUARDED_BY() 64 // 65 // Documents if the memory location pointed to by a pointer should be guarded 66 // by a mutex when dereferencing the pointer. 67 // 68 // Example: 69 // class Foo { 70 // Mutex mu_; 71 // int *p1_ ABSL_PT_GUARDED_BY(mu_); 72 // ... 73 // }; 74 // 75 // Note that a pointer variable to a shared memory location could itself be a 76 // shared variable. 77 // 78 // Example: 79 // 80 // // `q_`, guarded by `mu1_`, points to a shared memory location that is 81 // // guarded by `mu2_`: 82 // int *q_ ABSL_GUARDED_BY(mu1_) ABSL_PT_GUARDED_BY(mu2_); 83 #if ABSL_HAVE_ATTRIBUTE(pt_guarded_by) 84 #define ABSL_PT_GUARDED_BY(x) __attribute__((pt_guarded_by(x))) 85 #else 86 #define ABSL_PT_GUARDED_BY(x) 87 #endif 88 89 // ABSL_ACQUIRED_AFTER() / ABSL_ACQUIRED_BEFORE() 90 // 91 // Documents the acquisition order between locks that can be held 92 // simultaneously by a thread. For any two locks that need to be annotated 93 // to establish an acquisition order, only one of them needs the annotation. 94 // (i.e. You don't have to annotate both locks with both ABSL_ACQUIRED_AFTER 95 // and ABSL_ACQUIRED_BEFORE.) 96 // 97 // As with ABSL_GUARDED_BY, this is only applicable to mutexes that are shared 98 // fields or global variables. 99 // 100 // Example: 101 // 102 // Mutex m1_; 103 // Mutex m2_ ABSL_ACQUIRED_AFTER(m1_); 104 #if ABSL_HAVE_ATTRIBUTE(acquired_after) 105 #define ABSL_ACQUIRED_AFTER(...) __attribute__((acquired_after(__VA_ARGS__))) 106 #else 107 #define ABSL_ACQUIRED_AFTER(...) 108 #endif 109 110 #if ABSL_HAVE_ATTRIBUTE(acquired_before) 111 #define ABSL_ACQUIRED_BEFORE(...) __attribute__((acquired_before(__VA_ARGS__))) 112 #else 113 #define ABSL_ACQUIRED_BEFORE(...) 114 #endif 115 116 // ABSL_EXCLUSIVE_LOCKS_REQUIRED() / ABSL_SHARED_LOCKS_REQUIRED() 117 // 118 // Documents a function that expects a mutex to be held prior to entry. 119 // The mutex is expected to be held both on entry to, and exit from, the 120 // function. 121 // 122 // An exclusive lock allows read-write access to the guarded data member(s), and 123 // only one thread can acquire a lock exclusively at any one time. A shared lock 124 // allows read-only access, and any number of threads can acquire a shared lock 125 // concurrently. 126 // 127 // Generally, non-const methods should be annotated with 128 // ABSL_EXCLUSIVE_LOCKS_REQUIRED, while const methods should be annotated with 129 // ABSL_SHARED_LOCKS_REQUIRED. 130 // 131 // Example: 132 // 133 // Mutex mu1, mu2; 134 // int a ABSL_GUARDED_BY(mu1); 135 // int b ABSL_GUARDED_BY(mu2); 136 // 137 // void foo() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... } 138 // void bar() const ABSL_SHARED_LOCKS_REQUIRED(mu1, mu2) { ... } 139 #if ABSL_HAVE_ATTRIBUTE(exclusive_locks_required) 140 #define ABSL_EXCLUSIVE_LOCKS_REQUIRED(...) \ 141 __attribute__((exclusive_locks_required(__VA_ARGS__))) 142 #else 143 #define ABSL_EXCLUSIVE_LOCKS_REQUIRED(...) 144 #endif 145 146 #if ABSL_HAVE_ATTRIBUTE(shared_locks_required) 147 #define ABSL_SHARED_LOCKS_REQUIRED(...) \ 148 __attribute__((shared_locks_required(__VA_ARGS__))) 149 #else 150 #define ABSL_SHARED_LOCKS_REQUIRED(...) 151 #endif 152 153 // ABSL_LOCKS_EXCLUDED() 154 // 155 // Documents the locks that cannot be held by callers of this function, as they 156 // might be acquired by this function (Abseil's `Mutex` locks are 157 // non-reentrant). 158 #if ABSL_HAVE_ATTRIBUTE(locks_excluded) 159 #define ABSL_LOCKS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__))) 160 #else 161 #define ABSL_LOCKS_EXCLUDED(...) 162 #endif 163 164 // ABSL_LOCK_RETURNED() 165 // 166 // Documents a function that returns a mutex without acquiring it. For example, 167 // a public getter method that returns a pointer to a private mutex should 168 // be annotated with ABSL_LOCK_RETURNED. 169 #if ABSL_HAVE_ATTRIBUTE(lock_returned) 170 #define ABSL_LOCK_RETURNED(x) __attribute__((lock_returned(x))) 171 #else 172 #define ABSL_LOCK_RETURNED(x) 173 #endif 174 175 // ABSL_LOCKABLE 176 // 177 // Documents if a class/type is a lockable type (such as the `Mutex` class). 178 #if ABSL_HAVE_ATTRIBUTE(lockable) 179 #define ABSL_LOCKABLE __attribute__((lockable)) 180 #else 181 #define ABSL_LOCKABLE 182 #endif 183 184 // ABSL_SCOPED_LOCKABLE 185 // 186 // Documents if a class does RAII locking (such as the `MutexLock` class). 187 // The constructor should use `LOCK_FUNCTION()` to specify the mutex that is 188 // acquired, and the destructor should use `UNLOCK_FUNCTION()` with no 189 // arguments; the analysis will assume that the destructor unlocks whatever the 190 // constructor locked. 191 #if ABSL_HAVE_ATTRIBUTE(scoped_lockable) 192 #define ABSL_SCOPED_LOCKABLE __attribute__((scoped_lockable)) 193 #else 194 #define ABSL_SCOPED_LOCKABLE 195 #endif 196 197 // ABSL_EXCLUSIVE_LOCK_FUNCTION() 198 // 199 // Documents functions that acquire a lock in the body of a function, and do 200 // not release it. 201 #if ABSL_HAVE_ATTRIBUTE(exclusive_lock_function) 202 #define ABSL_EXCLUSIVE_LOCK_FUNCTION(...) \ 203 __attribute__((exclusive_lock_function(__VA_ARGS__))) 204 #else 205 #define ABSL_EXCLUSIVE_LOCK_FUNCTION(...) 206 #endif 207 208 // ABSL_SHARED_LOCK_FUNCTION() 209 // 210 // Documents functions that acquire a shared (reader) lock in the body of a 211 // function, and do not release it. 212 #if ABSL_HAVE_ATTRIBUTE(shared_lock_function) 213 #define ABSL_SHARED_LOCK_FUNCTION(...) \ 214 __attribute__((shared_lock_function(__VA_ARGS__))) 215 #else 216 #define ABSL_SHARED_LOCK_FUNCTION(...) 217 #endif 218 219 // ABSL_UNLOCK_FUNCTION() 220 // 221 // Documents functions that expect a lock to be held on entry to the function, 222 // and release it in the body of the function. 223 #if ABSL_HAVE_ATTRIBUTE(unlock_function) 224 #define ABSL_UNLOCK_FUNCTION(...) __attribute__((unlock_function(__VA_ARGS__))) 225 #else 226 #define ABSL_UNLOCK_FUNCTION(...) 227 #endif 228 229 // ABSL_EXCLUSIVE_TRYLOCK_FUNCTION() / ABSL_SHARED_TRYLOCK_FUNCTION() 230 // 231 // Documents functions that try to acquire a lock, and return success or failure 232 // (or a non-boolean value that can be interpreted as a boolean). 233 // The first argument should be `true` for functions that return `true` on 234 // success, or `false` for functions that return `false` on success. The second 235 // argument specifies the mutex that is locked on success. If unspecified, this 236 // mutex is assumed to be `this`. 237 #if ABSL_HAVE_ATTRIBUTE(exclusive_trylock_function) 238 #define ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(...) \ 239 __attribute__((exclusive_trylock_function(__VA_ARGS__))) 240 #else 241 #define ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(...) 242 #endif 243 244 #if ABSL_HAVE_ATTRIBUTE(shared_trylock_function) 245 #define ABSL_SHARED_TRYLOCK_FUNCTION(...) \ 246 __attribute__((shared_trylock_function(__VA_ARGS__))) 247 #else 248 #define ABSL_SHARED_TRYLOCK_FUNCTION(...) 249 #endif 250 251 // ABSL_ASSERT_EXCLUSIVE_LOCK() / ABSL_ASSERT_SHARED_LOCK() 252 // 253 // Documents functions that dynamically check to see if a lock is held, and fail 254 // if it is not held. 255 #if ABSL_HAVE_ATTRIBUTE(assert_exclusive_lock) 256 #define ABSL_ASSERT_EXCLUSIVE_LOCK(...) \ 257 __attribute__((assert_exclusive_lock(__VA_ARGS__))) 258 #else 259 #define ABSL_ASSERT_EXCLUSIVE_LOCK(...) 260 #endif 261 262 #if ABSL_HAVE_ATTRIBUTE(assert_shared_lock) 263 #define ABSL_ASSERT_SHARED_LOCK(...) \ 264 __attribute__((assert_shared_lock(__VA_ARGS__))) 265 #else 266 #define ABSL_ASSERT_SHARED_LOCK(...) 267 #endif 268 269 // ABSL_NO_THREAD_SAFETY_ANALYSIS 270 // 271 // Turns off thread safety checking within the body of a particular function. 272 // This annotation is used to mark functions that are known to be correct, but 273 // the locking behavior is more complicated than the analyzer can handle. 274 #if ABSL_HAVE_ATTRIBUTE(no_thread_safety_analysis) 275 #define ABSL_NO_THREAD_SAFETY_ANALYSIS \ 276 __attribute__((no_thread_safety_analysis)) 277 #else 278 #define ABSL_NO_THREAD_SAFETY_ANALYSIS 279 #endif 280 281 //------------------------------------------------------------------------------ 282 // Tool-Supplied Annotations 283 //------------------------------------------------------------------------------ 284 285 // ABSL_TS_UNCHECKED should be placed around lock expressions that are not valid 286 // C++ syntax, but which are present for documentation purposes. These 287 // annotations will be ignored by the analysis. 288 #define ABSL_TS_UNCHECKED(x) "" 289 290 // ABSL_TS_FIXME is used to mark lock expressions that are not valid C++ syntax. 291 // It is used by automated tools to mark and disable invalid expressions. 292 // The annotation should either be fixed, or changed to ABSL_TS_UNCHECKED. 293 #define ABSL_TS_FIXME(x) "" 294 295 // Like ABSL_NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body 296 // of a particular function. However, this attribute is used to mark functions 297 // that are incorrect and need to be fixed. It is used by automated tools to 298 // avoid breaking the build when the analysis is updated. 299 // Code owners are expected to eventually fix the routine. 300 #define ABSL_NO_THREAD_SAFETY_ANALYSIS_FIXME ABSL_NO_THREAD_SAFETY_ANALYSIS 301 302 // Similar to ABSL_NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a 303 // ABSL_GUARDED_BY annotation that needs to be fixed, because it is producing 304 // thread safety warning. It disables the ABSL_GUARDED_BY. 305 #define ABSL_GUARDED_BY_FIXME(x) 306 307 // Disables warnings for a single read operation. This can be used to avoid 308 // warnings when it is known that the read is not actually involved in a race, 309 // but the compiler cannot confirm that. 310 #define ABSL_TS_UNCHECKED_READ(x) absl::base_internal::ts_unchecked_read(x) 311 312 namespace absl { 313 ABSL_NAMESPACE_BEGIN 314 namespace base_internal { 315 316 // Takes a reference to a guarded data member, and returns an unguarded 317 // reference. 318 // Do not use this function directly, use ABSL_TS_UNCHECKED_READ instead. 319 template <typename T> 320 inline const T& ts_unchecked_read(const T& v) ABSL_NO_THREAD_SAFETY_ANALYSIS { 321 return v; 322 } 323 324 template <typename T> 325 inline T& ts_unchecked_read(T& v) ABSL_NO_THREAD_SAFETY_ANALYSIS { 326 return v; 327 } 328 329 } // namespace base_internal 330 ABSL_NAMESPACE_END 331 } // namespace absl 332 333 #endif // ABSL_BASE_THREAD_ANNOTATIONS_H_