absl: extend Condition::kTrue comment
Explain when kTrue may be useful.
Note that Mutex::Await/LockWhen with kTrue condition
and a timeout do not return when the timeout is reached.
PiperOrigin-RevId: 544846222
Change-Id: I7a14ae5a9314b2e500919f0c7b3a907d4d97c127
diff --git a/absl/synchronization/mutex.h b/absl/synchronization/mutex.h
index 2fd077c..645c26d 100644
--- a/absl/synchronization/mutex.h
+++ b/absl/synchronization/mutex.h
@@ -760,6 +760,16 @@
: Condition(obj, static_cast<bool (T::*)() const>(&T::operator())) {}
// A Condition that always returns `true`.
+ // kTrue is only useful in a narrow set of circumstances, mostly when
+ // it's passed conditionally. For example:
+ //
+ // mu.LockWhen(some_flag ? kTrue : SomeOtherCondition);
+ //
+ // Note: {LockWhen,Await}With{Deadline,Timeout} methods with kTrue condition
+ // don't return immediately when the timeout happens, they still block until
+ // the Mutex becomes available. The return value of these methods does
+ // not indicate if the timeout was reached; rather it indicates whether or
+ // not the condition is true.
ABSL_CONST_INIT static const Condition kTrue;
// Evaluates the condition.
