absl/base/dynamic_annotations.h - external/github.com/abseil/abseil-cpp - Git at Google

 // 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_
	// 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_