summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGravatar Greg Falcon <gfalcon@google.com>2022-12-15 13:48:40 -0800
committerGravatar Copybara-Service <copybara-worker@google.com>2022-12-15 13:49:17 -0800
commitd241d91992905a24efe0a0d4ca3561d592e54159 (patch)
tree85bfdc6d265ae880350e53f5e5c29b0d19f6f7a1
parente2416566660e1892274a56b34504b8b8c6c76101 (diff)
Fix the documentation of the atomic_hook.h registration functions to correctly state that only the first registered hook will be honored.
The comments that imply otherwise were never true, and were a leftover artifact during initial development of the feature. Also remove a TODO() I gave myself years ago; this is never going to happen and isn't worth the bother. PiperOrigin-RevId: 495687371 Change-Id: I63f8ef57d659075bf290caae0617ea61ceb2c1db
-rw-r--r--absl/synchronization/mutex.h21
1 files changed, 11 insertions, 10 deletions
diff --git a/absl/synchronization/mutex.h b/absl/synchronization/mutex.h
index c6a85100..f793cc0e 100644
--- a/absl/synchronization/mutex.h
+++ b/absl/synchronization/mutex.h
@@ -1033,10 +1033,11 @@ inline Condition::Condition(const T *object,
// measured by //absl/base/internal/cycleclock.h, and which may not
// be real "cycle" counts.)
//
-// Calls to this function do not race or block, but there is no ordering
-// guaranteed between calls to this function and call to the provided hook.
-// In particular, the previously registered hook may still be called for some
-// time after this function returns.
+// There is no ordering guarantee between when the hook is registered and when
+// callbacks will begin. Only a single profiler can be installed in a running
+// binary; if this function is called a second time with a different function
+// pointer, the value is ignored (and will cause an assertion failure in debug
+// mode.)
void RegisterMutexProfiler(void (*fn)(int64_t wait_cycles));
// Register a hook for Mutex tracing.
@@ -1049,13 +1050,11 @@ void RegisterMutexProfiler(void (*fn)(int64_t wait_cycles));
//
// The only event name currently sent is "slow release".
//
-// This has the same memory ordering concerns as RegisterMutexProfiler() above.
+// This has the same ordering and single-use limitations as
+// RegisterMutexProfiler() above.
void RegisterMutexTracer(void (*fn)(const char *msg, const void *obj,
int64_t wait_cycles));
-// TODO(gfalcon): Combine RegisterMutexProfiler() and RegisterMutexTracer()
-// into a single interface, since they are only ever called in pairs.
-
// Register a hook for CondVar tracing.
//
// The function pointer registered here will be called here on various CondVar
@@ -1066,7 +1065,8 @@ void RegisterMutexTracer(void (*fn)(const char *msg, const void *obj,
// Events that can be sent are "Wait", "Unwait", "Signal wakeup", and
// "SignalAll wakeup".
//
-// This has the same memory ordering concerns as RegisterMutexProfiler() above.
+// This has the same ordering and single-use limitations as
+// RegisterMutexProfiler() above.
void RegisterCondVarTracer(void (*fn)(const char *msg, const void *cv));
// Register a hook for symbolizing stack traces in deadlock detector reports.
@@ -1076,7 +1076,8 @@ void RegisterCondVarTracer(void (*fn)(const char *msg, const void *cv));
// false if symbolizing failed, or true if a NUL-terminated symbol was written
// to 'out.'
//
-// This has the same memory ordering concerns as RegisterMutexProfiler() above.
+// This has the same ordering and single-use limitations as
+// RegisterMutexProfiler() above.
//
// DEPRECATED: The default symbolizer function is absl::Symbolize() and the
// ability to register a different hook for symbolizing stack traces will be