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

1 files changed, 10 insertions, 0 deletions

diff --git a/absl/synchronization/mutex.h b/absl/synchronization/mutex.h
index 2fd077c8..645c26d9 100644
--- a/absl/synchronization/mutex.h
+++ b/absl/synchronization/mutex.h
@@ -760,6 +760,16 @@ class Condition {
       : 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.