Export of internal Abseil changes

--
874f906d2b90d4c74b0edeac52811efc10323422 by Todd Lipcon <tlipcon@google.com>:

Internal change

PiperOrigin-RevId: 352140672
GitOrigin-RevId: 874f906d2b90d4c74b0edeac52811efc10323422
Change-Id: I151299caff75d404309f059dd0e5971f5a71655d

1 files changed, 13 insertions, 1 deletions

diff --git a/absl/base/internal/spinlock.h b/absl/base/internal/spinlock.h
index dce1c854..c73b5e09 100644
--- a/absl/base/internal/spinlock.h
+++ b/absl/base/internal/spinlock.h
@@ -137,8 +137,20 @@ class ABSL_LOCKABLE SpinLock {
   //
   // bit[0] encodes whether a lock is being held.
   // bit[1] encodes whether a lock uses cooperative scheduling.
-  // bit[2] encodes whether a lock disables scheduling.
+  // bit[2] encodes whether the current lock holder disabled scheduling when
+  //        acquiring the lock. Only set when kSpinLockHeld is also set.
   // bit[3:31] encodes time a lock spent on waiting as a 29-bit unsigned int.
+  //        This is set by the lock holder to indicate how long it waited on
+  //        the lock before eventually acquiring it. The number of cycles is
+  //        encoded as a 29-bit unsigned int, or in the case that the current
+  //        holder did not wait but another waiter is queued, the LSB
+  //        (kSpinLockSleeper) is set. The implementation does not explicitly
+  //        track the number of queued waiters beyond this. It must always be
+  //        assumed that waiters may exist if the current holder was required to
+  //        queue.
+  //
+  // Invariant: if the lock is not held, the value is either 0 or
+  // kSpinLockCooperative.
   static constexpr uint32_t kSpinLockHeld = 1;
   static constexpr uint32_t kSpinLockCooperative = 2;
   static constexpr uint32_t kSpinLockDisabledScheduling = 4;