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

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