about summary refs log tree commit diff
path: root/absl/base/thread_annotations.h
diff options
context:
space:
mode:
Diffstat (limited to 'absl/base/thread_annotations.h')
-rw-r--r--absl/base/thread_annotations.h178
1 files changed, 94 insertions, 84 deletions
diff --git a/absl/base/thread_annotations.h b/absl/base/thread_annotations.h
index 0b2c306ccc57..f98af9f93d0a 100644
--- a/absl/base/thread_annotations.h
+++ b/absl/base/thread_annotations.h
@@ -34,19 +34,22 @@
 #ifndef ABSL_BASE_THREAD_ANNOTATIONS_H_
 #define ABSL_BASE_THREAD_ANNOTATIONS_H_
 
+// TODO(mbonadei): Remove after the backward compatibility period.
+#include "absl/base/internal/thread_annotations.h"  // IWYU pragma: export
+
 #if defined(__clang__)
-#define THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))
+#define ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(x) __attribute__((x))
 #else
-#define THREAD_ANNOTATION_ATTRIBUTE__(x)   // no-op
+#define ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(x)  // no-op
 #endif
 
-// GUARDED_BY()
+// ABSL_GUARDED_BY()
 //
 // Documents if a shared field or global variable needs to be protected by a
-// mutex. GUARDED_BY() allows the user to specify a particular mutex that
+// mutex. ABSL_GUARDED_BY() allows the user to specify a particular mutex that
 // should be held when accessing the annotated variable.
 //
-// Although this annotation (and PT_GUARDED_BY, below) cannot be applied to
+// Although this annotation (and ABSL_PT_GUARDED_BY, below) cannot be applied to
 // local variables, a local variable and its associated mutex can often be
 // combined into a small class or struct, thereby allowing the annotation.
 //
@@ -54,12 +57,13 @@
 //
 //   class Foo {
 //     Mutex mu_;
-//     int p1_ GUARDED_BY(mu_);
+//     int p1_ ABSL_GUARDED_BY(mu_);
 //     ...
 //   };
-#define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
+#define ABSL_GUARDED_BY(x) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(guarded_by(x))
 
-// PT_GUARDED_BY()
+// ABSL_PT_GUARDED_BY()
 //
 // Documents if the memory location pointed to by a pointer should be guarded
 // by a mutex when dereferencing the pointer.
@@ -67,7 +71,7 @@
 // Example:
 //   class Foo {
 //     Mutex mu_;
-//     int *p1_ PT_GUARDED_BY(mu_);
+//     int *p1_ ABSL_PT_GUARDED_BY(mu_);
 //     ...
 //   };
 //
@@ -78,31 +82,32 @@
 //
 //   // `q_`, guarded by `mu1_`, points to a shared memory location that is
 //   // guarded by `mu2_`:
-//   int *q_ GUARDED_BY(mu1_) PT_GUARDED_BY(mu2_);
-#define PT_GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
+//   int *q_ ABSL_GUARDED_BY(mu1_) ABSL_PT_GUARDED_BY(mu2_);
+#define ABSL_PT_GUARDED_BY(x) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(pt_guarded_by(x))
 
-// ACQUIRED_AFTER() / ACQUIRED_BEFORE()
+// ABSL_ACQUIRED_AFTER() / ABSL_ACQUIRED_BEFORE()
 //
 // Documents the acquisition order between locks that can be held
 // simultaneously by a thread. For any two locks that need to be annotated
 // to establish an acquisition order, only one of them needs the annotation.
-// (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER
-// and ACQUIRED_BEFORE.)
+// (i.e. You don't have to annotate both locks with both ABSL_ACQUIRED_AFTER
+// and ABSL_ACQUIRED_BEFORE.)
 //
-// As with GUARDED_BY, this is only applicable to mutexes that are shared
+// As with ABSL_GUARDED_BY, this is only applicable to mutexes that are shared
 // fields or global variables.
 //
 // Example:
 //
 //   Mutex m1_;
-//   Mutex m2_ ACQUIRED_AFTER(m1_);
-#define ACQUIRED_AFTER(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
+//   Mutex m2_ ABSL_ACQUIRED_AFTER(m1_);
+#define ABSL_ACQUIRED_AFTER(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(acquired_after(__VA_ARGS__))
 
-#define ACQUIRED_BEFORE(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
+#define ABSL_ACQUIRED_BEFORE(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(acquired_before(__VA_ARGS__))
 
-// EXCLUSIVE_LOCKS_REQUIRED() / SHARED_LOCKS_REQUIRED()
+// ABSL_EXCLUSIVE_LOCKS_REQUIRED() / ABSL_SHARED_LOCKS_REQUIRED()
 //
 // Documents a function that expects a mutex to be held prior to entry.
 // The mutex is expected to be held both on entry to, and exit from, the
@@ -114,77 +119,78 @@
 // concurrently.
 //
 // Generally, non-const methods should be annotated with
-// EXCLUSIVE_LOCKS_REQUIRED, while const methods should be annotated with
-// SHARED_LOCKS_REQUIRED.
+// ABSL_EXCLUSIVE_LOCKS_REQUIRED, while const methods should be annotated with
+// ABSL_SHARED_LOCKS_REQUIRED.
 //
 // Example:
 //
 //   Mutex mu1, mu2;
-//   int a GUARDED_BY(mu1);
-//   int b GUARDED_BY(mu2);
+//   int a ABSL_GUARDED_BY(mu1);
+//   int b ABSL_GUARDED_BY(mu2);
 //
-//   void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... }
-//   void bar() const SHARED_LOCKS_REQUIRED(mu1, mu2) { ... }
-#define EXCLUSIVE_LOCKS_REQUIRED(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
+//   void foo() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... }
+//   void bar() const ABSL_SHARED_LOCKS_REQUIRED(mu1, mu2) { ... }
+#define ABSL_EXCLUSIVE_LOCKS_REQUIRED(...)   \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE( \
+      exclusive_locks_required(__VA_ARGS__))
 
-#define SHARED_LOCKS_REQUIRED(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
+#define ABSL_SHARED_LOCKS_REQUIRED(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(shared_locks_required(__VA_ARGS__))
 
-// LOCKS_EXCLUDED()
+// ABSL_LOCKS_EXCLUDED()
 //
 // Documents the locks acquired in the body of the function. These locks
 // cannot be held when calling this function (as Abseil's `Mutex` locks are
 // non-reentrant).
-#define LOCKS_EXCLUDED(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
+#define ABSL_LOCKS_EXCLUDED(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(locks_excluded(__VA_ARGS__))
 
-// LOCK_RETURNED()
+// ABSL_LOCK_RETURNED()
 //
 // Documents a function that returns a mutex without acquiring it.  For example,
 // a public getter method that returns a pointer to a private mutex should
-// be annotated with LOCK_RETURNED.
-#define LOCK_RETURNED(x) \
-  THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
+// be annotated with ABSL_LOCK_RETURNED.
+#define ABSL_LOCK_RETURNED(x) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(lock_returned(x))
 
-// LOCKABLE
+// ABSL_LOCKABLE
 //
 // Documents if a class/type is a lockable type (such as the `Mutex` class).
-#define LOCKABLE \
-  THREAD_ANNOTATION_ATTRIBUTE__(lockable)
+#define ABSL_LOCKABLE ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(lockable)
 
-// SCOPED_LOCKABLE
+// ABSL_SCOPED_LOCKABLE
 //
 // Documents if a class does RAII locking (such as the `MutexLock` class).
 // The constructor should use `LOCK_FUNCTION()` to specify the mutex that is
 // acquired, and the destructor should use `UNLOCK_FUNCTION()` with no
 // arguments; the analysis will assume that the destructor unlocks whatever the
 // constructor locked.
-#define SCOPED_LOCKABLE \
-  THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
+#define ABSL_SCOPED_LOCKABLE \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(scoped_lockable)
 
-// EXCLUSIVE_LOCK_FUNCTION()
+// ABSL_EXCLUSIVE_LOCK_FUNCTION()
 //
 // Documents functions that acquire a lock in the body of a function, and do
 // not release it.
-#define EXCLUSIVE_LOCK_FUNCTION(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
+#define ABSL_EXCLUSIVE_LOCK_FUNCTION(...)    \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE( \
+      exclusive_lock_function(__VA_ARGS__))
 
-// SHARED_LOCK_FUNCTION()
+// ABSL_SHARED_LOCK_FUNCTION()
 //
 // Documents functions that acquire a shared (reader) lock in the body of a
 // function, and do not release it.
-#define SHARED_LOCK_FUNCTION(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
+#define ABSL_SHARED_LOCK_FUNCTION(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(shared_lock_function(__VA_ARGS__))
 
-// UNLOCK_FUNCTION()
+// ABSL_UNLOCK_FUNCTION()
 //
 // Documents functions that expect a lock to be held on entry to the function,
 // and release it in the body of the function.
-#define UNLOCK_FUNCTION(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
+#define ABSL_UNLOCK_FUNCTION(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(unlock_function(__VA_ARGS__))
 
-// EXCLUSIVE_TRYLOCK_FUNCTION() / SHARED_TRYLOCK_FUNCTION()
+// ABSL_EXCLUSIVE_TRYLOCK_FUNCTION() / ABSL_SHARED_TRYLOCK_FUNCTION()
 //
 // Documents functions that try to acquire a lock, and return success or failure
 // (or a non-boolean value that can be interpreted as a boolean).
@@ -192,76 +198,80 @@
 // success, or `false` for functions that return `false` on success. The second
 // argument specifies the mutex that is locked on success. If unspecified, this
 // mutex is assumed to be `this`.
-#define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
+#define ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE( \
+      exclusive_trylock_function(__VA_ARGS__))
 
-#define SHARED_TRYLOCK_FUNCTION(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
+#define ABSL_SHARED_TRYLOCK_FUNCTION(...)    \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE( \
+      shared_trylock_function(__VA_ARGS__))
 
-// ASSERT_EXCLUSIVE_LOCK() / ASSERT_SHARED_LOCK()
+// ABSL_ASSERT_EXCLUSIVE_LOCK() / ABSL_ASSERT_SHARED_LOCK()
 //
 // Documents functions that dynamically check to see if a lock is held, and fail
 // if it is not held.
-#define ASSERT_EXCLUSIVE_LOCK(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
+#define ABSL_ASSERT_EXCLUSIVE_LOCK(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(assert_exclusive_lock(__VA_ARGS__))
 
-#define ASSERT_SHARED_LOCK(...) \
-  THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
+#define ABSL_ASSERT_SHARED_LOCK(...) \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(assert_shared_lock(__VA_ARGS__))
 
-// NO_THREAD_SAFETY_ANALYSIS
+// ABSL_NO_THREAD_SAFETY_ANALYSIS
 //
 // Turns off thread safety checking within the body of a particular function.
 // This annotation is used to mark functions that are known to be correct, but
 // the locking behavior is more complicated than the analyzer can handle.
-#define NO_THREAD_SAFETY_ANALYSIS \
-  THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
+#define ABSL_NO_THREAD_SAFETY_ANALYSIS \
+  ABSL_INTERNAL_THREAD_ANNOTATION_ATTRIBUTE(no_thread_safety_analysis)
 
 //------------------------------------------------------------------------------
 // Tool-Supplied Annotations
 //------------------------------------------------------------------------------
 
-// TS_UNCHECKED should be placed around lock expressions that are not valid
+// ABSL_TS_UNCHECKED should be placed around lock expressions that are not valid
 // C++ syntax, but which are present for documentation purposes.  These
 // annotations will be ignored by the analysis.
-#define TS_UNCHECKED(x) ""
+#define ABSL_TS_UNCHECKED(x) ""
 
-// TS_FIXME is used to mark lock expressions that are not valid C++ syntax.
+// ABSL_TS_FIXME is used to mark lock expressions that are not valid C++ syntax.
 // It is used by automated tools to mark and disable invalid expressions.
-// The annotation should either be fixed, or changed to TS_UNCHECKED.
-#define TS_FIXME(x) ""
+// The annotation should either be fixed, or changed to ABSL_TS_UNCHECKED.
+#define ABSL_TS_FIXME(x) ""
 
-// Like NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body of
-// a particular function.  However, this attribute is used to mark functions
+// Like ABSL_NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body
+// of a particular function.  However, this attribute is used to mark functions
 // that are incorrect and need to be fixed.  It is used by automated tools to
 // avoid breaking the build when the analysis is updated.
 // Code owners are expected to eventually fix the routine.
-#define NO_THREAD_SAFETY_ANALYSIS_FIXME  NO_THREAD_SAFETY_ANALYSIS
+#define ABSL_NO_THREAD_SAFETY_ANALYSIS_FIXME ABSL_NO_THREAD_SAFETY_ANALYSIS
 
-// Similar to NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a GUARDED_BY
-// annotation that needs to be fixed, because it is producing thread safety
-// warning.  It disables the GUARDED_BY.
-#define GUARDED_BY_FIXME(x)
+// Similar to ABSL_NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a
+// ABSL_GUARDED_BY annotation that needs to be fixed, because it is producing
+// thread safety warning. It disables the ABSL_GUARDED_BY.
+#define ABSL_GUARDED_BY_FIXME(x)
 
 // Disables warnings for a single read operation.  This can be used to avoid
 // warnings when it is known that the read is not actually involved in a race,
 // but the compiler cannot confirm that.
-#define TS_UNCHECKED_READ(x) thread_safety_analysis::ts_unchecked_read(x)
-
+#define ABSL_TS_UNCHECKED_READ(x) absl::base_internal::ts_unchecked_read(x)
 
-namespace thread_safety_analysis {
+namespace absl {
+namespace base_internal {
 
 // Takes a reference to a guarded data member, and returns an unguarded
 // reference.
+// Do not used this function directly, use ABSL_TS_UNCHECKED_READ instead.
 template <typename T>
-inline const T& ts_unchecked_read(const T& v) NO_THREAD_SAFETY_ANALYSIS {
+inline const T& ts_unchecked_read(const T& v) ABSL_NO_THREAD_SAFETY_ANALYSIS {
   return v;
 }
 
 template <typename T>
-inline T& ts_unchecked_read(T& v) NO_THREAD_SAFETY_ANALYSIS {
+inline T& ts_unchecked_read(T& v) ABSL_NO_THREAD_SAFETY_ANALYSIS {
   return v;
 }
 
-}  // namespace thread_safety_analysis
+}  // namespace base_internal
+}  // namespace absl
 
 #endif  // ABSL_BASE_THREAD_ANNOTATIONS_H_