borrower: update rendezvous comments for Exclusion waiter parking

Exclusion contenders now park on the lock's waiter list and wake on
final release, not on the owning Task's post-exec queue.  Update the
Borrower documentation that described the old mechanism.

Assisted-by: Claude-Code:claude-fable-5

diff --git a/src/bees-borrower.h b/src/bees-borrower.h
index 39d2fcb89425e59d7fc55a6e5ee6daf099afd0e8..d5705c4ae81fc9ecd9fa8fb0b543aa3b461f2c67 100644 (file)
--- a/src/bees-borrower.h
+++ b/src/bees-borrower.h
@@ -9,8 +9,9 @@
 /// try-or-restart locking.
 ///
 /// On contention, the Borrower releases all held locks and throws Dead,
-/// unwinding the entire planning pass.  The Task infrastructure re-queues
-/// the work item on the conflicting Task's post-exec list.
+/// unwinding the entire planning pass.  The Task is parked on the
+/// conflicting Exclusion's waiter list and rescheduled when that lock
+/// is released.
 
 #include "bees-fwd.h"
 
@@ -33,12 +34,11 @@ using namespace std;
 /// clears it and releases all held locks.
 ///
 /// Locking uses the Task/Exclusion rendezvous mechanism: when
-/// try_lock() fails, Exclusion appends the current Task to the
-/// winning Task's post-exec queue.  When the winner finishes
-/// (i.e. its Borrower is destroyed and locks are released), the
-/// Task infrastructure automatically reschedules the losing Task.
-/// This is why Dead is safe as flow control — the planning pass
-/// will be retried once the contended resource is available.
+/// try_lock() fails, Exclusion parks the current Task on its
+/// waiter list.  When the winner releases the lock (i.e. its
+/// Borrower is destroyed), the waiters are rescheduled.  This is
+/// why Dead is safe as flow control — the planning pass will be
+/// retried once the contended resource is available.
 class Borrower {
 public:
        /// Thrown when try_lock() fails due to contention.
@@ -120,8 +120,8 @@ public:
        /// the NamedPtr entry alive for the lifetime of the lock.
        ///
        /// On failure (the Exclusion is held by another Task):
-       ///   1. Exclusion::try_lock appends current Task to the
-       ///      winning Task's post-exec queue (rendezvous)
+       ///   1. Exclusion::try_lock parks the current Task on the
+       ///      Exclusion's waiter list (rendezvous)
        ///   2. m_dead is set to true
        ///   3. All previously held locks are released
        ///   4. Dead is thrown — caller unwinds the planning pass