// 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 // // https://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. // This file defines dynamic annotations for use with dynamic analysis tool // such as valgrind, PIN, etc. // // Dynamic annotation is a source code annotation that affects the generated // code (that is, the annotation is not a comment). Each such annotation is // attached to a particular instruction and/or to a particular object (address) // in the program. // // The annotations that should be used by users are macros in all upper-case // (e.g., ABSL_ANNOTATE_THREAD_NAME). // // Actual implementation of these macros may differ depending on the dynamic // analysis tool being used. // // This file supports the following configurations: // - Dynamic Annotations enabled (with static thread-safety warnings disabled). // In this case, macros expand to functions implemented by Thread Sanitizer, // when building with TSan. When not provided an external implementation, // dynamic_annotations.cc provides no-op implementations. // // - Static Clang thread-safety warnings enabled. // When building with a Clang compiler that supports thread-safety warnings, // a subset of annotations can be statically-checked at compile-time. We // expand these macros to static-inline functions that can be analyzed for // thread-safety, but afterwards elided when building the final binary. // // - All annotations are disabled. // If neither Dynamic Annotations nor Clang thread-safety warnings are // enabled, then all annotation-macros expand to empty. #ifndef ABSL_BASE_DYNAMIC_ANNOTATIONS_H_ #define ABSL_BASE_DYNAMIC_ANNOTATIONS_H_ #include <stddef.h> #include "absl/base/attributes.h" #include "absl/base/config.h" #ifdef __cplusplus #include "absl/base/macros.h" #endif // TODO(rogeeff): Remove after the backward compatibility period. #include "absl/base/internal/dynamic_annotations.h" // IWYU pragma: export // ------------------------------------------------------------------------- // Decide which features are enabled. #ifdef ABSL_HAVE_THREAD_SANITIZER #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 1 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 1 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 1 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 0 #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED 1 #else #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 0 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 0 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 0 // Clang provides limited support for static thread-safety analysis through a // feature called Annotalysis. We configure macro-definitions according to // whether Annotalysis support is available. When running in opt-mode, GCC // will issue a warning, if these attributes are compiled. Only include them // when compiling using Clang. #if defined(__clang__) #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 1 #if !defined(SWIG) #define ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED 1 #endif #else #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 0 #endif // Read/write annotations are enabled in Annotalysis mode; disabled otherwise. #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED \ ABSL_INTERNAL_ANNOTALYSIS_ENABLED #endif // ABSL_HAVE_THREAD_SANITIZER #ifdef __cplusplus #define ABSL_INTERNAL_BEGIN_EXTERN_C extern "C" { #define ABSL_INTERNAL_END_EXTERN_C } // extern "C" #define ABSL_INTERNAL_GLOBAL_SCOPED(F) ::F #define ABSL_INTERNAL_STATIC_INLINE inline #else #define ABSL_INTERNAL_BEGIN_EXTERN_C // empty #define ABSL_INTERNAL_END_EXTERN_C // empty #define ABSL_INTERNAL_GLOBAL_SCOPED(F) F #define ABSL_INTERNAL_STATIC_INLINE static inline #endif // ------------------------------------------------------------------------- // Define race annotations. #if ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 1 // Some of the symbols used in this section (e.g. AnnotateBenignRaceSized) are // defined by the compiler-based santizer implementation, not by the Abseil // library. Therefore they do not use ABSL_INTERNAL_C_SYMBOL. // ------------------------------------------------------------- // Annotations that suppress errors. It is usually better to express the // program's synchronization using the other annotations, but these can be used // when all else fails. // Report that we may have a benign race at `pointer`, with size // "sizeof(*(pointer))". `pointer` must be a non-void* pointer. Insert at the // point where `pointer` has been allocated, preferably close to the point // where the race happens. See also ABSL_ANNOTATE_BENIGN_RACE_STATIC. #define ABSL_ANNOTATE_BENIGN_RACE(pointer, description) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \ (__FILE__, __LINE__, pointer, sizeof(*(pointer)), description) // Same as ABSL_ANNOTATE_BENIGN_RACE(`address`, `description`), but applies to // the memory range [`address`, `address`+`size`). #define ABSL_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \ (__FILE__, __LINE__, address, size, description) // Enable (`enable`!=0) or disable (`enable`==0) race detection for all threads. // This annotation could be useful if you want to skip expensive race analysis // during some period of program execution, e.g. during initialization. #define ABSL_ANNOTATE_ENABLE_RACE_DETECTION(enable) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateEnableRaceDetection) \ (__FILE__, __LINE__, enable) // ------------------------------------------------------------- // Annotations useful for debugging. // Report the current thread `name` to a race detector. #define ABSL_ANNOTATE_THREAD_NAME(name) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateThreadName)(__FILE__, __LINE__, name) // ------------------------------------------------------------- // Annotations useful when implementing locks. They are not normally needed by // modules that merely use locks. The `lock` argument is a pointer to the lock // object. // Report that a lock has been created at address `lock`. #define ABSL_ANNOTATE_RWLOCK_CREATE(lock) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreate)(__FILE__, __LINE__, lock) // Report that a linker initialized lock has been created at address `lock`. #ifdef ABSL_HAVE_THREAD_SANITIZER #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreateStatic) \ (__FILE__, __LINE__, lock) #else #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) \ ABSL_ANNOTATE_RWLOCK_CREATE(lock) #endif // Report that the lock at address `lock` is about to be destroyed. #define ABSL_ANNOTATE_RWLOCK_DESTROY(lock) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockDestroy)(__FILE__, __LINE__, lock) // Report that the lock at address `lock` has been acquired. // `is_w`=1 for writer lock, `is_w`=0 for reader lock. #define ABSL_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockAcquired) \ (__FILE__, __LINE__, lock, is_w) // Report that the lock at address `lock` is about to be released. // `is_w`=1 for writer lock, `is_w`=0 for reader lock. #define ABSL_ANNOTATE_RWLOCK_RELEASED(lock, is_w) \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockReleased) \ (__FILE__, __LINE__, lock, is_w) // Apply ABSL_ANNOTATE_BENIGN_RACE_SIZED to a static variable `static_var`. #define ABSL_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) \ namespace { \ class static_var##_annotator { \ public: \ static_var##_annotator() { \ ABSL_ANNOTATE_BENIGN_RACE_SIZED(&static_var, sizeof(static_var), \ #static_var ": " description); \ } \ }; \ static static_var##_annotator the##static_var##_annotator; \ } // namespace // Function prototypes of annotations provided by the compiler-based sanitizer // implementation. ABSL_INTERNAL_BEGIN_EXTERN_C void AnnotateRWLockCreate(const char* file, int line, const volatile void* lock); void AnnotateRWLockCreateStatic(const char* file, int line, const volatile void* lock); void AnnotateRWLockDestroy(const char* file, int line, const volatile void* lock); void AnnotateRWLockAcquired(const char* file, int line, const volatile void* lock, long is_w); // NOLINT void AnnotateRWLockReleased(const char* file, int line, const volatile void* lock, long is_w); // NOLINT void AnnotateBenignRace(const char* file, int line, const volatile void* address, const char* description); void AnnotateBenignRaceSized(const char* file, int line, const volatile void* address, size_t size, const char* description); void AnnotateThreadName(const char* file, int line, const char* name); void AnnotateEnableRaceDetection(const char* file, int line, int enable); ABSL_INTERNAL_END_EXTERN_C #else // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 0 #define ABSL_ANNOTATE_RWLOCK_CREATE(lock) // empty #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) // empty #define ABSL_ANNOTATE_RWLOCK_DESTROY(lock) // empty #define ABSL_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) // empty #define ABSL_ANNOTATE_RWLOCK_RELEASED(lock, is_w) // empty #define ABSL_ANNOTATE_BENIGN_RACE(address, description) // empty #define ABSL_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) // empty #define ABSL_ANNOTATE_THREAD_NAME(name) // empty #define ABSL_ANNOTATE_ENABLE_RACE_DETECTION(enable) // empty #define ABSL_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) // empty #endif // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED // ------------------------------------------------------------------------- // Define memory annotations. #ifdef ABSL_HAVE_MEMORY_SANITIZER #include <sanitizer/msan_interface.h> #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \ __msan_unpoison(address, size) #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \ __msan_allocated_memory(address, size) #else // !defined(ABSL_HAVE_MEMORY_SANITIZER) // TODO(rogeeff): remove this branch #ifdef ABSL_HAVE_THREAD_SANITIZER #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \ do { \ (void)(address); \ (void)(size); \ } while (0) #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \ do { \ (void)(address); \ (void)(size); \ } while (0) #else #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) // empty #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) // empty #endif #endif // ABSL_HAVE_MEMORY_SANITIZER // ------------------------------------------------------------------------- // Define IGNORE_READS_BEGIN/_END attributes. #if defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE \ __attribute((exclusive_lock_function("*"))) #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE \ __attribute((unlock_function("*"))) #else // !defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE // empty #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE // empty #endif // defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) // ------------------------------------------------------------------------- // Define IGNORE_READS_BEGIN/_END annotations. #if ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED == 1 // Some of the symbols used in this section (e.g. AnnotateIgnoreReadsBegin) are // defined by the compiler-based implementation, not by the Abseil // library. Therefore they do not use ABSL_INTERNAL_C_SYMBOL. // Request the analysis tool to ignore all reads in the current thread until // ABSL_ANNOTATE_IGNORE_READS_END is called. Useful to ignore intentional racey // reads, while still checking other reads and all writes. // See also ABSL_ANNOTATE_UNPROTECTED_READ. #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsBegin) \ (__FILE__, __LINE__) // Stop ignoring reads. #define ABSL_ANNOTATE_IGNORE_READS_END() \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsEnd) \ (__FILE__, __LINE__) // Function prototypes of annotations provided by the compiler-based sanitizer // implementation. ABSL_INTERNAL_BEGIN_EXTERN_C void AnnotateIgnoreReadsBegin(const char* file, int line) ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE; void AnnotateIgnoreReadsEnd(const char* file, int line) ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE; ABSL_INTERNAL_END_EXTERN_C #elif defined(ABSL_INTERNAL_ANNOTALYSIS_ENABLED) // When Annotalysis is enabled without Dynamic Annotations, the use of // static-inline functions allows the annotations to be read at compile-time, // while still letting the compiler elide the functions from the final build. // // TODO(delesley) -- The exclusive lock here ignores writes as well, but // allows IGNORE_READS_AND_WRITES to work properly. #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() \ ABSL_INTERNAL_GLOBAL_SCOPED( \ ABSL_INTERNAL_C_SYMBOL(AbslInternalAnnotateIgnoreReadsBegin)) \ () #define ABSL_ANNOTATE_IGNORE_READS_END() \ ABSL_INTERNAL_GLOBAL_SCOPED( \ ABSL_INTERNAL_C_SYMBOL(AbslInternalAnnotateIgnoreReadsEnd)) \ () ABSL_INTERNAL_STATIC_INLINE void ABSL_INTERNAL_C_SYMBOL( AbslInternalAnnotateIgnoreReadsBegin)() ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE {} ABSL_INTERNAL_STATIC_INLINE void ABSL_INTERNAL_C_SYMBOL( AbslInternalAnnotateIgnoreReadsEnd)() ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE {} #else #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() // empty #define ABSL_ANNOTATE_IGNORE_READS_END() // empty #endif // ------------------------------------------------------------------------- // Define IGNORE_WRITES_BEGIN/_END annotations. #if ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED == 1 // Similar to ABSL_ANNOTATE_IGNORE_READS_BEGIN, but ignore writes instead. #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesBegin)(__FILE__, __LINE__) // Stop ignoring writes. #define ABSL_ANNOTATE_IGNORE_WRITES_END() \ ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesEnd)(__FILE__, __LINE__) // Function prototypes of annotations provided by the compiler-based sanitizer // implementation. ABSL_INTERNAL_BEGIN_EXTERN_C void AnnotateIgnoreWritesBegin(const char* file, int line); void AnnotateIgnoreWritesEnd(const char* file, int line); ABSL_INTERNAL_END_EXTERN_C #else #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() // empty #define ABSL_ANNOTATE_IGNORE_WRITES_END() // empty #endif // ------------------------------------------------------------------------- // Define the ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_* annotations using the more // primitive annotations defined above. // // Instead of doing // ABSL_ANNOTATE_IGNORE_READS_BEGIN(); // ... = x; // ABSL_ANNOTATE_IGNORE_READS_END(); // one can use // ... = ABSL_ANNOTATE_UNPROTECTED_READ(x); #if defined(ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED) // Start ignoring all memory accesses (both reads and writes). #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \ do { \ ABSL_ANNOTATE_IGNORE_READS_BEGIN(); \ ABSL_ANNOTATE_IGNORE_WRITES_BEGIN(); \ } while (0) // Stop ignoring both reads and writes. #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_END() \ do { \ ABSL_ANNOTATE_IGNORE_WRITES_END(); \ ABSL_ANNOTATE_IGNORE_READS_END(); \ } while (0) #ifdef __cplusplus // ABSL_ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads. #define ABSL_ANNOTATE_UNPROTECTED_READ(x) \ absl::base_internal::AnnotateUnprotectedRead(x) namespace absl { ABSL_NAMESPACE_BEGIN namespace base_internal { template <typename T> inline T AnnotateUnprotectedRead(const volatile T& x) { // NOLINT ABSL_ANNOTATE_IGNORE_READS_BEGIN(); T res = x; ABSL_ANNOTATE_IGNORE_READS_END(); return res; } } // namespace base_internal ABSL_NAMESPACE_END } // namespace absl #endif #else #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() // empty #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_END() // empty #define ABSL_ANNOTATE_UNPROTECTED_READ(x) (x) #endif // ------------------------------------------------------------------------- // Address sanitizer annotations #ifdef ABSL_HAVE_ADDRESS_SANITIZER // Describe the current state of a contiguous container such as e.g. // std::vector or std::string. For more details see // sanitizer/common_interface_defs.h, which is provided by the compiler. #include <sanitizer/common_interface_defs.h> #define ABSL_ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) \ __sanitizer_annotate_contiguous_container(beg, end, old_mid, new_mid) #define ABSL_ADDRESS_SANITIZER_REDZONE(name) \ struct { \ alignas(8) char x[8]; \ } name #else #define ABSL_ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) // empty #define ABSL_ADDRESS_SANITIZER_REDZONE(name) static_assert(true, "") #endif // ABSL_HAVE_ADDRESS_SANITIZER // ------------------------------------------------------------------------- // Undefine the macros intended only for this file. #undef ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED #undef ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED #undef ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED #undef ABSL_INTERNAL_ANNOTALYSIS_ENABLED #undef ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED #undef ABSL_INTERNAL_BEGIN_EXTERN_C #undef ABSL_INTERNAL_END_EXTERN_C #undef ABSL_INTERNAL_STATIC_INLINE #endif // ABSL_BASE_DYNAMIC_ANNOTATIONS_H_