From d241d91992905a24efe0a0d4ca3561d592e54159 Mon Sep 17 00:00:00 2001 From: Greg Falcon Date: Thu, 15 Dec 2022 13:48:40 -0800 Subject: 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 --- absl/synchronization/mutex.h | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'absl/synchronization') 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 -- cgit v1.2.3