- 551e205ef49682a1cb7e6e0cda46957fbcf88edd Release absl::variant. by Xiaoyi Zhang <zhangxy@google.com>

  - 01c52f640594d073c6e54c47e7853b25522cf085 Update comments in absl::variant (and minor changes to ab... by Tom Manshreck <shreck@google.com>
  - 064465e1e6b158abd8c38fd1942b4fc464b57d6a Documentation change. by Abseil Team <absl-team@google.com>
  - 58df2c8a27e80c9ea21d87c1acee8019246377c9 Relocates SetCountdown and UnsetCountdown to the exceptio... by Abseil Team <absl-team@google.com>
  - fd9d248d0948d472f2543f7fd9c0ae4a1cd60d01 Clarify thread_annotation.h documentation around local va... by Abseil Team <absl-team@google.com>
  - 0d0abaf7f0945ac5f2c5f49e78afe1b326d5aca0 Typo fix in comments. by Abseil Team <absl-team@google.com>
  - 67286d587cbd07508a81e5b8147c245a5b5538b4 Internal change. by Xiaoyi Zhang <zhangxy@google.com>

GitOrigin-RevId: 551e205ef49682a1cb7e6e0cda46957fbcf88edd
Change-Id: I1a343b080187293cb5f892a309618b5712e7aa14

1 files changed, 22 insertions, 9 deletions

diff --git a/absl/base/thread_annotations.h b/absl/base/thread_annotations.h
index 0da3badc4e2d..8d30b9324b52 100644
--- a/absl/base/thread_annotations.h
+++ b/absl/base/thread_annotations.h
@@ -47,10 +47,17 @@
 // mutex. 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
+// local variables, a local variable and its associated mutex can often be
+// combined into a small class or struct, thereby allowing the annotation.
+//
 // Example:
 //
-//   Mutex mu;
-//   int p1 GUARDED_BY(mu);
+//   class Foo {
+//     Mutex mu_;
+//     int p1_ GUARDED_BY(mu_);
+//     ...
+//   };
 #define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
 
 // PT_GUARDED_BY()
@@ -59,17 +66,20 @@
 // by a mutex when dereferencing the pointer.
 //
 // Example:
-//   Mutex mu;
-//   int *p1 PT_GUARDED_BY(mu);
+//   class Foo {
+//     Mutex mu_;
+//     int *p1_ PT_GUARDED_BY(mu_);
+//     ...
+//   };
 //
 // Note that a pointer variable to a shared memory location could itself be a
 // shared variable.
 //
 // Example:
 //
-//     // `q`, guarded by `mu1`, points to a shared memory location that is
-//     // guarded by `mu2`:
-//     int *q GUARDED_BY(mu1) PT_GUARDED_BY(mu2);
+//   // `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))
 
 // ACQUIRED_AFTER() / ACQUIRED_BEFORE()
@@ -80,10 +90,13 @@
 // (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER
 // and ACQUIRED_BEFORE.)
 //
+// As with GUARDED_BY, this is only applicable to mutexes that are shared
+// fields or global variables.
+//
 // Example:
 //
-//   Mutex m1;
-//   Mutex m2 ACQUIRED_AFTER(m1);
+//   Mutex m1_;
+//   Mutex m2_ ACQUIRED_AFTER(m1_);
 #define ACQUIRED_AFTER(...) \
   THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))