/* * 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_ #ifndef ABSL_DYNAMIC_ANNOTATIONS_ENABLED # define ABSL_DYNAMIC_ANNOTATIONS_ENABLED 0 #endif #if ABSL_DYNAMIC_ANNOTATIONS_ENABLED != 0 /* ------------------------------------------------------------- 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) \ AbslAnnotateBenignRaceSized(__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) \ AbslAnnotateBenignRaceSized(__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) \ AbslAnnotateEnableRaceDetection(__FILE__, __LINE__, enable) /* ------------------------------------------------------------- Annotations useful for debugging. */ /* Report the current thread name to a race detector. */ #define ABSL_ANNOTATE_THREAD_NAME(name) \ AbslAnnotateThreadName(__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) \ AbslAnnotateRWLockCreate(__FILE__, __LINE__, lock) /* Report that a linker initialized lock has been created at address "lock". */ #ifdef THREAD_SANITIZER #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) \ AbslAnnotateRWLockCreateStatic(__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) \ AbslAnnotateRWLockDestroy(__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) \ AbslAnnotateRWLockAcquired(__FILE__, __LINE__, lock, is_w) /* Report that the lock at address "lock" is about to be released. */ #define ABSL_ANNOTATE_RWLOCK_RELEASED(lock, is_w) \ AbslAnnotateRWLockReleased(__FILE__, __LINE__, lock, is_w) #else /* ABSL_DYNAMIC_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 */ #endif /* ABSL_DYNAMIC_ANNOTATIONS_ENABLED */ /* These annotations are also made available to LLVM's Memory Sanitizer */ #if ABSL_DYNAMIC_ANNOTATIONS_ENABLED == 1 || defined(MEMORY_SANITIZER) #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \ AbslAnnotateMemoryIsInitialized(__FILE__, __LINE__, address, size) #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \ AbslAnnotateMemoryIsUninitialized(__FILE__, __LINE__, address, size) #else #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) /* empty */ #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) /* empty */ #endif /* ABSL_DYNAMIC_ANNOTATIONS_ENABLED || MEMORY_SANITIZER */ /* TODO(delesley) -- Replace __CLANG_SUPPORT_DYN_ANNOTATION__ with the appropriate feature ID. */ #if defined(__clang__) && (!defined(SWIG)) \ && defined(__CLANG_SUPPORT_DYN_ANNOTATION__) #if ABSL_DYNAMIC_ANNOTATIONS_ENABLED == 0 #define ABSL_ANNOTALYSIS_ENABLED #endif /* When running in opt-mode, GCC will issue a warning, if these attributes are compiled. Only include them when compiling using Clang. */ #define ABSL_ATTRIBUTE_IGNORE_READS_BEGIN \ __attribute((exclusive_lock_function("*"))) #define ABSL_ATTRIBUTE_IGNORE_READS_END \ __attribute((unlock_function("*"))) #else #define ABSL_ATTRIBUTE_IGNORE_READS_BEGIN /* empty */ #define ABSL_ATTRIBUTE_IGNORE_READS_END /* empty */ #endif /* defined(__clang__) && ... */ #if (ABSL_DYNAMIC_ANNOTATIONS_ENABLED != 0) || defined(ABSL_ANNOTALYSIS_ENABLED) #define ABSL_ANNOTATIONS_ENABLED #endif #if (ABSL_DYNAMIC_ANNOTATIONS_ENABLED != 0) /* 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() \ AbslAnnotateIgnoreReadsBegin(__FILE__, __LINE__) /* Stop ignoring reads. */ #define ABSL_ANNOTATE_IGNORE_READS_END() \ AbslAnnotateIgnoreReadsEnd(__FILE__, __LINE__) /* Similar to ABSL_ANNOTATE_IGNORE_READS_BEGIN, but ignore writes instead. */ #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() \ AbslAnnotateIgnoreWritesBegin(__FILE__, __LINE__) /* Stop ignoring writes. */ #define ABSL_ANNOTATE_IGNORE_WRITES_END() \ AbslAnnotateIgnoreWritesEnd(__FILE__, __LINE__) /* 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. */ #elif defined(ABSL_ANNOTALYSIS_ENABLED) #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() \ AbslStaticAnnotateIgnoreReadsBegin(__FILE__, __LINE__) #define ABSL_ANNOTATE_IGNORE_READS_END() \ AbslStaticAnnotateIgnoreReadsEnd(__FILE__, __LINE__) #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() \ AbslStaticAnnotateIgnoreWritesBegin(__FILE__, __LINE__) #define ABSL_ANNOTATE_IGNORE_WRITES_END() \ AbslStaticAnnotateIgnoreWritesEnd(__FILE__, __LINE__) #else #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() /* empty */ #define ABSL_ANNOTATE_IGNORE_READS_END() /* empty */ #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() /* empty */ #define ABSL_ANNOTATE_IGNORE_WRITES_END() /* empty */ #endif /* Implement the ANNOTATE_IGNORE_READS_AND_WRITES_* annotations using the more primitive annotations defined above. */ #if defined(ABSL_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) #else #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() /* empty */ #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_END() /* empty */ #endif /* Use the macros above rather than using these functions directly. */ #include #ifdef __cplusplus extern "C" { #endif void AbslAnnotateRWLockCreate(const char *file, int line, const volatile void *lock); void AbslAnnotateRWLockCreateStatic(const char *file, int line, const volatile void *lock); void AbslAnnotateRWLockDestroy(const char *file, int line, const volatile void *lock); void AbslAnnotateRWLockAcquired(const char *file, int line, const volatile void *lock, long is_w); /* NOLINT */ void AbslAnnotateRWLockReleased(const char *file, int line, const volatile void *lock, long is_w); /* NOLINT */ void AbslAnnotateBenignRace(const char *file, int line, const volatile void *address, const char *description); void AbslAnnotateBenignRaceSized(const char *file, int line, const volatile void *address, size_t size, const char *description); void AbslAnnotateThreadName(const char *file, int line, const char *name); void AbslAnnotateEnableRaceDetection(const char *file, int line, int enable); void AbslAnnotateMemoryIsInitialized(const char *file, int line, const volatile void *mem, size_t size); void AbslAnnotateMemoryIsUninitialized(const char *file, int line, const volatile void *mem, size_t size); /* Annotations expand to these functions, when Dynamic Annotations are enabled. These functions are either implemented as no-op calls, if no Sanitizer is attached, or provided with externally-linked implementations by a library like ThreadSanitizer. */ void AbslAnnotateIgnoreReadsBegin(const char *file, int line) ABSL_ATTRIBUTE_IGNORE_READS_BEGIN; void AbslAnnotateIgnoreReadsEnd(const char *file, int line) ABSL_ATTRIBUTE_IGNORE_READS_END; void AbslAnnotateIgnoreWritesBegin(const char *file, int line); void AbslAnnotateIgnoreWritesEnd(const char *file, int line); #if defined(ABSL_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. */ #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wunused-function" static inline void AbslStaticAnnotateIgnoreReadsBegin(const char *file, int line) ABSL_ATTRIBUTE_IGNORE_READS_BEGIN { (void)file; (void)line; } static inline void AbslStaticAnnotateIgnoreReadsEnd(const char *file, int line) ABSL_ATTRIBUTE_IGNORE_READS_END { (void)file; (void)line; } static inline void AbslStaticAnnotateIgnoreWritesBegin( const char *file, int line) { (void)file; (void)line; } static inline void AbslStaticAnnotateIgnoreWritesEnd( const char *file, int line) { (void)file; (void)line; } #pragma GCC diagnostic pop #endif /* Return non-zero value if running under valgrind. If "valgrind.h" is included into dynamic_annotations.cc, the regular valgrind mechanism will be used. See http://valgrind.org/docs/manual/manual-core-adv.html about RUNNING_ON_VALGRIND and other valgrind "client requests". The file "valgrind.h" may be obtained by doing svn co svn://svn.valgrind.org/valgrind/trunk/include If for some reason you can't use "valgrind.h" or want to fake valgrind, there are two ways to make this function return non-zero: - Use environment variable: export RUNNING_ON_VALGRIND=1 - Make your tool intercept the function AbslRunningOnValgrind() and change its return value. */ int AbslRunningOnValgrind(void); /* AbslValgrindSlowdown returns: * 1.0, if (AbslRunningOnValgrind() == 0) * 50.0, if (AbslRunningOnValgrind() != 0 && getenv("VALGRIND_SLOWDOWN") == NULL) * atof(getenv("VALGRIND_SLOWDOWN")) otherwise This function can be used to scale timeout values: EXAMPLE: for (;;) { DoExpensiveBackgroundTask(); SleepForSeconds(5 * AbslValgrindSlowdown()); } */ double AbslValgrindSlowdown(void); #ifdef __cplusplus } #endif /* ABSL_ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads. Instead of doing ABSL_ANNOTATE_IGNORE_READS_BEGIN(); ... = x; ABSL_ANNOTATE_IGNORE_READS_END(); one can use ... = ABSL_ANNOTATE_UNPROTECTED_READ(x); */ #if defined(__cplusplus) && defined(ABSL_ANNOTATIONS_ENABLED) template inline T ABSL_ANNOTATE_UNPROTECTED_READ(const volatile T &x) { /* NOLINT */ ABSL_ANNOTATE_IGNORE_READS_BEGIN(); T res = x; ABSL_ANNOTATE_IGNORE_READS_END(); return res; } #else #define ABSL_ANNOTATE_UNPROTECTED_READ(x) (x) #endif #if ABSL_DYNAMIC_ANNOTATIONS_ENABLED != 0 && defined(__cplusplus) /* Apply ABSL_ANNOTATE_BENIGN_RACE_SIZED to a static variable. */ #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 #else /* ABSL_DYNAMIC_ANNOTATIONS_ENABLED == 0 */ #define ABSL_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) /* empty */ #endif /* ABSL_DYNAMIC_ANNOTATIONS_ENABLED */ #ifdef 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 #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 { char x[8] __attribute__ ((aligned (8))); } name #else #define ABSL_ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) #define ABSL_ADDRESS_SANITIZER_REDZONE(name) static_assert(true, "") #endif // ADDRESS_SANITIZER /* Undefine the macros intended only in this file. */ #undef ABSL_ANNOTALYSIS_ENABLED #undef ABSL_ANNOTATIONS_ENABLED #undef ABSL_ATTRIBUTE_IGNORE_READS_BEGIN #undef ABSL_ATTRIBUTE_IGNORE_READS_END #endif /* ABSL_BASE_DYNAMIC_ANNOTATIONS_H_ */