Changes imported from Abseil "staging" branch:

  - 5e874e644191fbf99f5636d6303de2b28b23392c Adds a absl::apply function, similar to c++17's std::apply. by Abseil Team <absl-team@google.com>
  - 16373c438d16a09725dace03ab7ba0f7c2337279 Add debugging_internal::StackTraceWorksForTest by Abseil Team <absl-team@google.com>
  - a623257aaaff8a5fba3377f34f92f319a104e444 Update absl::CondVar documentation in response to GitHub ... by Derek Mauro <dmauro@google.com>
  - 87d58a25bc4ecd46165dd1c417121c86cbc07be0 Add assert against uint128 negative bit shift undefined b... by Alex Strelnikov <strel@google.com>
  - af155c0d2a3556b56a9bcd6f9ee7416277185df8 Fix comment typos. by Abseil Team <absl-team@google.com>
  - 1824ae832eb75d447dea730b5968d952897e135a Rollback of: Add debugging_internal::StackTraceWorksForTest by Abseil Team <absl-team@google.com>
  - 97318f087ce63dd5acf1e0d3d697cd90a7d6ebfd Add debugging_internal::StackTraceWorksForTest by Abseil Team <absl-team@google.com>
  - 9dd1d17dca17f0ded3bda336b7521fd57d08a5cc Move log_severity.h out of internal. by Abseil Team <absl-team@google.com>
  - 2212bb56b1a8365d2303ff0983441298d08444e5 Internal change. by Alex Strelnikov <strel@google.com>

GitOrigin-RevId: 5e874e644191fbf99f5636d6303de2b28b23392c
Change-Id: Ic270393ac1f15866afb64617d28269cd829030f6

1 files changed, 13 insertions, 28 deletions

diff --git a/absl/synchronization/mutex.h b/absl/synchronization/mutex.h
index 26ac7f619bff..b09802b523bc 100644
--- a/absl/synchronization/mutex.h
+++ b/absl/synchronization/mutex.h
@@ -713,7 +713,7 @@ class Condition {
 // The implementation may deliver signals to any condition variable at
 // any time, even when no call to `Signal()` or `SignalAll()` is made; as a
 // result, upon being awoken, you must check the logical condition you have
-// been waiting upon. The implementation wakes waiters in the FIFO order.
+// been waiting upon.
 //
 // Examples:
 //
@@ -742,29 +742,19 @@ class CondVar {
 
   // CondVar::Wait()
   //
-  // Atomically releases a `Mutex` and blocks on this condition variable. After
-  // blocking, the thread will unblock, reacquire the `Mutex`, and return if
-  // either:
-  //  - this condition variable is signalled with `SignalAll()`, or
-  //  - this condition variable is signalled in any manner and this thread
-  //    was the most recently blocked thread that has not yet woken.
+  // Atomically releases a `Mutex` and blocks on this condition variable.
+  // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
+  // spurious wakeup), then reacquires the `Mutex` and returns.
+  //
   // Requires and ensures that the current thread holds the `Mutex`.
   void Wait(Mutex *mu);
 
   // CondVar::WaitWithTimeout()
   //
-  // Atomically releases a `Mutex`, blocks on this condition variable, and
-  // attempts to reacquire the mutex upon being signalled, or upon reaching the
-  // timeout.
-  //
-  // After blocking, the thread will unblock, reacquire the `Mutex`, and return
-  // for any of the following:
-  //  - this condition variable is signalled with `SignalAll()`
-  //  - the timeout has expired
-  //  - this condition variable is signalled in any manner and this thread
-  //    was the most recently blocked thread that has not yet woken.
-  //
-  // Negative timeouts are equivalent to a zero timeout.
+  // Atomically releases a `Mutex` and blocks on this condition variable.
+  // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
+  // spurious wakeup), or until the timeout has expired, then reacquires
+  // the `Mutex` and returns.
   //
   // Returns true if the timeout has expired without this `CondVar`
   // being signalled in any manner. If both the timeout has expired
@@ -776,15 +766,10 @@ class CondVar {
 
   // CondVar::WaitWithDeadline()
   //
-  // Atomically releases a `Mutex`, blocks on this condition variable, and
-  // attempts to reacquire the mutex within the provided deadline.
-  //
-  // After blocking, the thread will unblock, reacquire the `Mutex`, and return
-  // for any of the following:
-  //  - this condition variable is signalled with `SignalAll()`
-  //  - the deadline has passed
-  //  - this condition variable is signalled in any manner and this thread
-  //    was the most recently blocked thread that has not yet woken.
+  // Atomically releases a `Mutex` and blocks on this condition variable.
+  // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
+  // spurious wakeup), or until the deadline has passed, then reacquires
+  // the `Mutex` and returns.
   //
   // Deadlines in the past are equivalent to an immediate deadline.
   //