dynamic_annotations.h (19012B)
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 // This file defines dynamic annotations for use with dynamic analysis tool 16 // such as valgrind, PIN, etc. 17 // 18 // Dynamic annotation is a source code annotation that affects the generated 19 // code (that is, the annotation is not a comment). Each such annotation is 20 // attached to a particular instruction and/or to a particular object (address) 21 // in the program. 22 // 23 // The annotations that should be used by users are macros in all upper-case 24 // (e.g., ABSL_ANNOTATE_THREAD_NAME). 25 // 26 // Actual implementation of these macros may differ depending on the dynamic 27 // analysis tool being used. 28 // 29 // This file supports the following configurations: 30 // - Dynamic Annotations enabled (with static thread-safety warnings disabled). 31 // In this case, macros expand to functions implemented by Thread Sanitizer, 32 // when building with TSan. When not provided an external implementation, 33 // dynamic_annotations.cc provides no-op implementations. 34 // 35 // - Static Clang thread-safety warnings enabled. 36 // When building with a Clang compiler that supports thread-safety warnings, 37 // a subset of annotations can be statically-checked at compile-time. We 38 // expand these macros to static-inline functions that can be analyzed for 39 // thread-safety, but afterwards elided when building the final binary. 40 // 41 // - All annotations are disabled. 42 // If neither Dynamic Annotations nor Clang thread-safety warnings are 43 // enabled, then all annotation-macros expand to empty. 44 45 #ifndef ABSL_BASE_DYNAMIC_ANNOTATIONS_H_ 46 #define ABSL_BASE_DYNAMIC_ANNOTATIONS_H_ 47 48 #include <stddef.h> 49 #include <stdint.h> 50 51 #include "absl/base/attributes.h" 52 #include "absl/base/config.h" 53 #ifdef __cplusplus 54 #include "absl/base/macros.h" 55 #endif 56 57 #ifdef ABSL_HAVE_HWADDRESS_SANITIZER 58 #include <sanitizer/hwasan_interface.h> 59 #endif 60 61 // ------------------------------------------------------------------------- 62 // Decide which features are enabled. 63 64 #ifdef ABSL_HAVE_THREAD_SANITIZER 65 66 #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 1 67 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 1 68 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 1 69 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 0 70 #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED 1 71 72 #else 73 74 #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 0 75 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 0 76 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 0 77 78 // Clang provides limited support for static thread-safety analysis through a 79 // feature called Annotalysis. We configure macro-definitions according to 80 // whether Annotalysis support is available. When running in opt-mode, GCC 81 // will issue a warning, if these attributes are compiled. Only include them 82 // when compiling using Clang. 83 84 #if defined(__clang__) 85 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 1 86 #if !defined(SWIG) 87 #define ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED 1 88 #endif 89 #else 90 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 0 91 #endif 92 93 // Read/write annotations are enabled in Annotalysis mode; disabled otherwise. 94 #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED \ 95 ABSL_INTERNAL_ANNOTALYSIS_ENABLED 96 97 #endif // ABSL_HAVE_THREAD_SANITIZER 98 99 #ifdef __cplusplus 100 #define ABSL_INTERNAL_BEGIN_EXTERN_C extern "C" { 101 #define ABSL_INTERNAL_END_EXTERN_C } // extern "C" 102 #define ABSL_INTERNAL_GLOBAL_SCOPED(F) ::F 103 #define ABSL_INTERNAL_STATIC_INLINE inline 104 #else 105 #define ABSL_INTERNAL_BEGIN_EXTERN_C // empty 106 #define ABSL_INTERNAL_END_EXTERN_C // empty 107 #define ABSL_INTERNAL_GLOBAL_SCOPED(F) F 108 #define ABSL_INTERNAL_STATIC_INLINE static inline 109 #endif 110 111 // ------------------------------------------------------------------------- 112 // Define race annotations. 113 114 #if ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 1 115 // Some of the symbols used in this section (e.g. AnnotateBenignRaceSized) are 116 // defined by the compiler-based sanitizer implementation, not by the Abseil 117 // library. Therefore they do not use ABSL_INTERNAL_C_SYMBOL. 118 119 // ------------------------------------------------------------- 120 // Annotations that suppress errors. It is usually better to express the 121 // program's synchronization using the other annotations, but these can be used 122 // when all else fails. 123 124 // Report that we may have a benign race at `pointer`, with size 125 // "sizeof(*(pointer))". `pointer` must be a non-void* pointer. Insert at the 126 // point where `pointer` has been allocated, preferably close to the point 127 // where the race happens. See also ABSL_ANNOTATE_BENIGN_RACE_STATIC. 128 #define ABSL_ANNOTATE_BENIGN_RACE(pointer, description) \ 129 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \ 130 (__FILE__, __LINE__, pointer, sizeof(*(pointer)), description) 131 132 // Same as ABSL_ANNOTATE_BENIGN_RACE(`address`, `description`), but applies to 133 // the memory range [`address`, `address`+`size`). 134 #define ABSL_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \ 135 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \ 136 (__FILE__, __LINE__, address, size, description) 137 138 // Enable (`enable`!=0) or disable (`enable`==0) race detection for all threads. 139 // This annotation could be useful if you want to skip expensive race analysis 140 // during some period of program execution, e.g. during initialization. 141 #define ABSL_ANNOTATE_ENABLE_RACE_DETECTION(enable) \ 142 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateEnableRaceDetection) \ 143 (__FILE__, __LINE__, enable) 144 145 // ------------------------------------------------------------- 146 // Annotations useful for debugging. 147 148 // Report the current thread `name` to a race detector. 149 #define ABSL_ANNOTATE_THREAD_NAME(name) \ 150 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateThreadName)(__FILE__, __LINE__, name) 151 152 // ------------------------------------------------------------- 153 // Annotations useful when implementing locks. They are not normally needed by 154 // modules that merely use locks. The `lock` argument is a pointer to the lock 155 // object. 156 157 // Report that a lock has been created at address `lock`. 158 #define ABSL_ANNOTATE_RWLOCK_CREATE(lock) \ 159 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreate)(__FILE__, __LINE__, lock) 160 161 // Report that a linker initialized lock has been created at address `lock`. 162 #ifdef ABSL_HAVE_THREAD_SANITIZER 163 #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) \ 164 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreateStatic) \ 165 (__FILE__, __LINE__, lock) 166 #else 167 #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) \ 168 ABSL_ANNOTATE_RWLOCK_CREATE(lock) 169 #endif 170 171 // Report that the lock at address `lock` is about to be destroyed. 172 #define ABSL_ANNOTATE_RWLOCK_DESTROY(lock) \ 173 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockDestroy)(__FILE__, __LINE__, lock) 174 175 // Report that the lock at address `lock` has been acquired. 176 // `is_w`=1 for writer lock, `is_w`=0 for reader lock. 177 #define ABSL_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \ 178 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockAcquired) \ 179 (__FILE__, __LINE__, lock, is_w) 180 181 // Report that the lock at address `lock` is about to be released. 182 // `is_w`=1 for writer lock, `is_w`=0 for reader lock. 183 #define ABSL_ANNOTATE_RWLOCK_RELEASED(lock, is_w) \ 184 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockReleased) \ 185 (__FILE__, __LINE__, lock, is_w) 186 187 // Apply ABSL_ANNOTATE_BENIGN_RACE_SIZED to a static variable `static_var`. 188 #define ABSL_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) \ 189 namespace { \ 190 class static_var##_annotator { \ 191 public: \ 192 static_var##_annotator() { \ 193 ABSL_ANNOTATE_BENIGN_RACE_SIZED(&static_var, sizeof(static_var), \ 194 #static_var ": " description); \ 195 } \ 196 }; \ 197 static static_var##_annotator the##static_var##_annotator; \ 198 } // namespace 199 200 // Function prototypes of annotations provided by the compiler-based sanitizer 201 // implementation. 202 ABSL_INTERNAL_BEGIN_EXTERN_C 203 void AnnotateRWLockCreate(const char* file, int line, 204 const volatile void* lock); 205 void AnnotateRWLockCreateStatic(const char* file, int line, 206 const volatile void* lock); 207 void AnnotateRWLockDestroy(const char* file, int line, 208 const volatile void* lock); 209 void AnnotateRWLockAcquired(const char* file, int line, 210 const volatile void* lock, long is_w); // NOLINT 211 void AnnotateRWLockReleased(const char* file, int line, 212 const volatile void* lock, long is_w); // NOLINT 213 void AnnotateBenignRace(const char* file, int line, 214 const volatile void* address, const char* description); 215 void AnnotateBenignRaceSized(const char* file, int line, 216 const volatile void* address, size_t size, 217 const char* description); 218 void AnnotateThreadName(const char* file, int line, const char* name); 219 void AnnotateEnableRaceDetection(const char* file, int line, int enable); 220 ABSL_INTERNAL_END_EXTERN_C 221 222 #else // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 0 223 224 #define ABSL_ANNOTATE_RWLOCK_CREATE(lock) // empty 225 #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) // empty 226 #define ABSL_ANNOTATE_RWLOCK_DESTROY(lock) // empty 227 #define ABSL_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) // empty 228 #define ABSL_ANNOTATE_RWLOCK_RELEASED(lock, is_w) // empty 229 #define ABSL_ANNOTATE_BENIGN_RACE(address, description) // empty 230 #define ABSL_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) // empty 231 #define ABSL_ANNOTATE_THREAD_NAME(name) // empty 232 #define ABSL_ANNOTATE_ENABLE_RACE_DETECTION(enable) // empty 233 #define ABSL_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) // empty 234 235 #endif // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 236 237 // ------------------------------------------------------------------------- 238 // Define memory annotations. 239 240 #ifdef ABSL_HAVE_MEMORY_SANITIZER 241 242 #include <sanitizer/msan_interface.h> 243 244 #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \ 245 __msan_unpoison(address, size) 246 247 #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \ 248 __msan_allocated_memory(address, size) 249 250 #else // !defined(ABSL_HAVE_MEMORY_SANITIZER) 251 252 #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) // empty 253 #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) // empty 254 255 #endif // ABSL_HAVE_MEMORY_SANITIZER 256 257 // ------------------------------------------------------------------------- 258 // Define IGNORE_READS_BEGIN/_END attributes. 259 260 #if defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) 261 262 #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE \ 263 __attribute((exclusive_lock_function("*"))) 264 #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE \ 265 __attribute((unlock_function("*"))) 266 267 #else // !defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) 268 269 #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE // empty 270 #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE // empty 271 272 #endif // defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) 273 274 // ------------------------------------------------------------------------- 275 // Define IGNORE_READS_BEGIN/_END annotations. 276 277 #if ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED == 1 278 // Some of the symbols used in this section (e.g. AnnotateIgnoreReadsBegin) are 279 // defined by the compiler-based implementation, not by the Abseil 280 // library. Therefore they do not use ABSL_INTERNAL_C_SYMBOL. 281 282 // Request the analysis tool to ignore all reads in the current thread until 283 // ABSL_ANNOTATE_IGNORE_READS_END is called. Useful to ignore intentional racey 284 // reads, while still checking other reads and all writes. 285 // See also ABSL_ANNOTATE_UNPROTECTED_READ. 286 #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() \ 287 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsBegin) \ 288 (__FILE__, __LINE__) 289 290 // Stop ignoring reads. 291 #define ABSL_ANNOTATE_IGNORE_READS_END() \ 292 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsEnd) \ 293 (__FILE__, __LINE__) 294 295 // Function prototypes of annotations provided by the compiler-based sanitizer 296 // implementation. 297 ABSL_INTERNAL_BEGIN_EXTERN_C 298 void AnnotateIgnoreReadsBegin(const char* file, int line) 299 ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE; 300 void AnnotateIgnoreReadsEnd(const char* file, 301 int line) ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE; 302 ABSL_INTERNAL_END_EXTERN_C 303 304 #elif defined(ABSL_INTERNAL_ANNOTALYSIS_ENABLED) 305 306 // When Annotalysis is enabled without Dynamic Annotations, the use of 307 // static-inline functions allows the annotations to be read at compile-time, 308 // while still letting the compiler elide the functions from the final build. 309 // 310 // TODO(delesley) -- The exclusive lock here ignores writes as well, but 311 // allows IGNORE_READS_AND_WRITES to work properly. 312 313 #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() \ 314 ABSL_INTERNAL_GLOBAL_SCOPED( \ 315 ABSL_INTERNAL_C_SYMBOL(AbslInternalAnnotateIgnoreReadsBegin)) \ 316 () 317 318 #define ABSL_ANNOTATE_IGNORE_READS_END() \ 319 ABSL_INTERNAL_GLOBAL_SCOPED( \ 320 ABSL_INTERNAL_C_SYMBOL(AbslInternalAnnotateIgnoreReadsEnd)) \ 321 () 322 323 ABSL_INTERNAL_STATIC_INLINE void ABSL_INTERNAL_C_SYMBOL( 324 AbslInternalAnnotateIgnoreReadsBegin)() 325 ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE {} 326 327 ABSL_INTERNAL_STATIC_INLINE void ABSL_INTERNAL_C_SYMBOL( 328 AbslInternalAnnotateIgnoreReadsEnd)() 329 ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE {} 330 331 #else 332 333 #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() // empty 334 #define ABSL_ANNOTATE_IGNORE_READS_END() // empty 335 336 #endif 337 338 // ------------------------------------------------------------------------- 339 // Define IGNORE_WRITES_BEGIN/_END annotations. 340 341 #if ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED == 1 342 343 // Similar to ABSL_ANNOTATE_IGNORE_READS_BEGIN, but ignore writes instead. 344 #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() \ 345 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesBegin)(__FILE__, __LINE__) 346 347 // Stop ignoring writes. 348 #define ABSL_ANNOTATE_IGNORE_WRITES_END() \ 349 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesEnd)(__FILE__, __LINE__) 350 351 // Function prototypes of annotations provided by the compiler-based sanitizer 352 // implementation. 353 ABSL_INTERNAL_BEGIN_EXTERN_C 354 void AnnotateIgnoreWritesBegin(const char* file, int line); 355 void AnnotateIgnoreWritesEnd(const char* file, int line); 356 ABSL_INTERNAL_END_EXTERN_C 357 358 #else 359 360 #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() // empty 361 #define ABSL_ANNOTATE_IGNORE_WRITES_END() // empty 362 363 #endif 364 365 // ------------------------------------------------------------------------- 366 // Define the ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_* annotations using the more 367 // primitive annotations defined above. 368 // 369 // Instead of doing 370 // ABSL_ANNOTATE_IGNORE_READS_BEGIN(); 371 // ... = x; 372 // ABSL_ANNOTATE_IGNORE_READS_END(); 373 // one can use 374 // ... = ABSL_ANNOTATE_UNPROTECTED_READ(x); 375 376 #if defined(ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED) 377 378 // Start ignoring all memory accesses (both reads and writes). 379 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \ 380 do { \ 381 ABSL_ANNOTATE_IGNORE_READS_BEGIN(); \ 382 ABSL_ANNOTATE_IGNORE_WRITES_BEGIN(); \ 383 } while (0) 384 385 // Stop ignoring both reads and writes. 386 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_END() \ 387 do { \ 388 ABSL_ANNOTATE_IGNORE_WRITES_END(); \ 389 ABSL_ANNOTATE_IGNORE_READS_END(); \ 390 } while (0) 391 392 #ifdef __cplusplus 393 // ABSL_ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads. 394 #define ABSL_ANNOTATE_UNPROTECTED_READ(x) \ 395 absl::base_internal::AnnotateUnprotectedRead(x) 396 397 namespace absl { 398 ABSL_NAMESPACE_BEGIN 399 namespace base_internal { 400 401 template <typename T> 402 inline T AnnotateUnprotectedRead(const volatile T& x) { // NOLINT 403 ABSL_ANNOTATE_IGNORE_READS_BEGIN(); 404 T res = x; 405 ABSL_ANNOTATE_IGNORE_READS_END(); 406 return res; 407 } 408 409 } // namespace base_internal 410 ABSL_NAMESPACE_END 411 } // namespace absl 412 #endif 413 414 #else 415 416 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() // empty 417 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_END() // empty 418 #define ABSL_ANNOTATE_UNPROTECTED_READ(x) (x) 419 420 #endif 421 422 // ------------------------------------------------------------------------- 423 // Address sanitizer annotations 424 425 #ifdef ABSL_HAVE_ADDRESS_SANITIZER 426 // Describe the current state of a contiguous container such as e.g. 427 // std::vector or std::string. For more details see 428 // sanitizer/common_interface_defs.h, which is provided by the compiler. 429 #include <sanitizer/common_interface_defs.h> 430 431 #define ABSL_ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) \ 432 __sanitizer_annotate_contiguous_container(beg, end, old_mid, new_mid) 433 #define ABSL_ADDRESS_SANITIZER_REDZONE(name) \ 434 struct { \ 435 alignas(8) char x[8]; \ 436 } name 437 438 #else 439 440 #define ABSL_ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) // empty 441 #define ABSL_ADDRESS_SANITIZER_REDZONE(name) static_assert(true, "") 442 443 #endif // ABSL_HAVE_ADDRESS_SANITIZER 444 445 // ------------------------------------------------------------------------- 446 // HWAddress sanitizer annotations 447 448 #ifdef __cplusplus 449 namespace absl { 450 #ifdef ABSL_HAVE_HWADDRESS_SANITIZER 451 // Under HWASAN changes the tag of the pointer. 452 template <typename T> 453 T* HwasanTagPointer(T* ptr, uintptr_t tag) { 454 return reinterpret_cast<T*>(__hwasan_tag_pointer(ptr, tag)); 455 } 456 #else 457 template <typename T> 458 T* HwasanTagPointer(T* ptr, uintptr_t) { 459 return ptr; 460 } 461 #endif 462 } // namespace absl 463 #endif 464 465 // ------------------------------------------------------------------------- 466 // Undefine the macros intended only for this file. 467 468 #undef ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 469 #undef ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 470 #undef ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 471 #undef ABSL_INTERNAL_ANNOTALYSIS_ENABLED 472 #undef ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED 473 #undef ABSL_INTERNAL_BEGIN_EXTERN_C 474 #undef ABSL_INTERNAL_END_EXTERN_C 475 #undef ABSL_INTERNAL_STATIC_INLINE 476 477 #endif // ABSL_BASE_DYNAMIC_ANNOTATIONS_H_