From 7a0f9106f16395701ea821193113d5762281e6f1 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 17:56:21 +0800 Subject: [PATCH 1/7] refactor(semaphore): encode the two permit queueing modes Pair the waiting future with its waker in the acquisition request. Each request now determines where to queue its shortfall, so reduction debt takes priority over pending acquisitions. --- asyncband/src/internal/semaphore.rs | 83 ++++++++++++++--------------- 1 file changed, 41 insertions(+), 42 deletions(-) diff --git a/asyncband/src/internal/semaphore.rs b/asyncband/src/internal/semaphore.rs index d3627065..4414fca4 100644 --- a/asyncband/src/internal/semaphore.rs +++ b/asyncband/src/internal/semaphore.rs @@ -123,14 +123,14 @@ impl Semaphore { /// /// If fewer than `n` permits are available, a queue-head debt node consumes future releases. pub fn reduce_permits(&self, n: usize) { - acquired_or_enqueue(self, n, None, None, false); + acquire_or_enqueue(self, n, PermitRequest::Debt); } /// Returns a future that acquires `n` permits from the semaphore. pub fn acquire(&self, n: usize) -> Acquire<'_> { Acquire { requested_permits: n, - index: None, + waiter_id: None, semaphore: self, } } @@ -272,21 +272,21 @@ impl Semaphore { #[must_use = "futures do nothing unless you `.await` or poll them"] pub struct Acquire<'a> { requested_permits: usize, - index: Option, + waiter_id: Option, semaphore: &'a Semaphore, } impl Drop for Acquire<'_> { fn drop(&mut self) { - if let Some(index) = self.index.take() { + if let Some(id) = self.waiter_id.take() { let mut waiters = self.semaphore.waiters.lock(); let mut acquired = 0; - waiters.unlink_waiter(index, |node| { + waiters.unlink_waiter(id, |node| { acquired = self.requested_permits - node.needed_permits; node.needed_permits = 0; true }); - let waiter = waiters.remove_unlinked_waiter(index); + let waiter = waiters.remove_unlinked_waiter(id); if acquired > 0 { self.semaphore.distribute_permits(acquired, waiters); } else { @@ -301,16 +301,16 @@ impl Acquire<'_> { pub fn poll_once(&mut self, waker: &Waker) -> Poll<()> { let Self { requested_permits, - index, + waiter_id, semaphore, } = self; let mut old_waker = None; - match index { - Some(idx) => { + match waiter_id { + Some(id) => { let mut waiters = semaphore.waiters.lock(); let ready = { - let node = waiters.waiter_mut(*idx); + let node = waiters.waiter_mut(*id); if node.needed_permits > 0 { old_waker = register_waker(&mut node.waker, waker); false @@ -319,15 +319,14 @@ impl Acquire<'_> { } }; if ready { - waiters.remove_unlinked_waiter(*idx); - *index = None; + waiters.remove_unlinked_waiter(*id); + *waiter_id = None; return Poll::Ready(()); } } None => { - let requested = *requested_permits; - - if acquired_or_enqueue(semaphore, requested, Some(index), Some(waker), true) { + let request = PermitRequest::Acquire { waiter_id, waker }; + if acquire_or_enqueue(semaphore, *requested_permits, request) { return Poll::Ready(()); } } @@ -347,19 +346,16 @@ impl Future for Acquire<'_> { } } -/// Returns `true` if successfully acquired the semaphore; `false` otherwise. -fn acquired_or_enqueue( - sem: &Semaphore, - requested: usize, - index: Option<&mut Option>, - waker: Option<&Waker>, - enqueue_last: bool, -) -> bool { - assert_eq!( - index.is_some(), - waker.is_some(), - "only acquire waiters have a future owner" - ); +enum PermitRequest<'a> { + Debt, + Acquire { + waiter_id: &'a mut Option, + waker: &'a Waker, + }, +} + +/// Returns true when all permits were available and no node was queued. +fn acquire_or_enqueue(sem: &Semaphore, requested: usize, request: PermitRequest<'_>) -> bool { let mut available = sem.available_permits.load(Ordering::Acquire); let mut lock = None; @@ -396,20 +392,23 @@ fn acquired_or_enqueue( unreachable!("lock must be acquired when needed {needed} > 0"); }); - let node = WaitNode { - needed_permits: needed, - waker: waker.cloned(), - }; - let id = if enqueue_last { - waiters.push_back(node) - } else { - waiters.push_front(node) - }; - if let Some(index) = index { - assert!( - index.replace(id).is_none(), - "waiter must not be registered twice" - ); + match request { + PermitRequest::Debt => { + waiters.push_front(WaitNode { + needed_permits: needed, + waker: None, + }); + } + PermitRequest::Acquire { waiter_id, waker } => { + let id = waiters.push_back(WaitNode { + needed_permits: needed, + waker: Some(waker.clone()), + }); + assert!( + waiter_id.replace(id).is_none(), + "waiter must not be registered twice" + ); + } } return false; From cc7b37ed7ed29b758586ef0b9677274f8f18fb29 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 17:56:43 +0800 Subject: [PATCH 2/7] refactor(waitlist): centralize removal of linked and detached waiters Let cancellation take ownership of a waiter by ID. Callers can then return its permits or pass on its notification, while notification alone still leaves a detached node for the future to claim. --- asyncband/src/condvar/mod.rs | 3 +-- asyncband/src/event/auto_reset.rs | 3 +-- asyncband/src/event/manual_reset.rs | 3 +-- asyncband/src/internal/semaphore.rs | 9 ++------- asyncband/src/internal/waitlist.rs | 8 +++++++- asyncband/src/mpmc/queue.rs | 17 ++++------------- asyncband/src/mpsc/bounded/sender.rs | 3 +-- asyncband/src/spmc/queue.rs | 22 +++++----------------- 8 files changed, 22 insertions(+), 46 deletions(-) diff --git a/asyncband/src/condvar/mod.rs b/asyncband/src/condvar/mod.rs index 3e6d80c7..f8de04f3 100644 --- a/asyncband/src/condvar/mod.rs +++ b/asyncband/src/condvar/mod.rs @@ -396,8 +396,7 @@ impl Drop for Wait<'_, G> { let (waiter, waker) = { let mut waiters = self.condvar.waiters.lock(); - waiters.unlink_waiter(index, |_| true); - let waiter = waiters.remove_unlinked_waiter(index); + let waiter = waiters.remove(index); let waker = match &waiter { WaitState::NotifiedOne => notify_one_locked(&mut waiters), diff --git a/asyncband/src/event/auto_reset.rs b/asyncband/src/event/auto_reset.rs index b047273e..0365fa58 100644 --- a/asyncband/src/event/auto_reset.rs +++ b/asyncband/src/event/auto_reset.rs @@ -239,8 +239,7 @@ impl AutoResetEvent { let (waiter, waker) = { let mut state = self.state.lock(); // A selected waiter is already detached, but still owns its signal until removal. - state.waiters.unlink_waiter(id, |_| true); - let waiter = state.waiters.remove_unlinked_waiter(id); + let waiter = state.waiters.remove(id); let waker = match &waiter { Waiter::Notified => state.signal(), Waiter::Waiting(_) => None, diff --git a/asyncband/src/event/manual_reset.rs b/asyncband/src/event/manual_reset.rs index 683131fa..7a7ec588 100644 --- a/asyncband/src/event/manual_reset.rs +++ b/asyncband/src/event/manual_reset.rs @@ -262,8 +262,7 @@ impl ManualResetEvent { let waiter = { let mut waiters = self.waiters.lock(); // Released waits retain their detached nodes until repolled or cancelled. - waiters.unlink_waiter(id, |_| true); - waiters.remove_unlinked_waiter(id) + waiters.remove(id) }; drop(waiter); } diff --git a/asyncband/src/internal/semaphore.rs b/asyncband/src/internal/semaphore.rs index 4414fca4..020fb4ea 100644 --- a/asyncband/src/internal/semaphore.rs +++ b/asyncband/src/internal/semaphore.rs @@ -280,13 +280,8 @@ impl Drop for Acquire<'_> { fn drop(&mut self) { if let Some(id) = self.waiter_id.take() { let mut waiters = self.semaphore.waiters.lock(); - let mut acquired = 0; - waiters.unlink_waiter(id, |node| { - acquired = self.requested_permits - node.needed_permits; - node.needed_permits = 0; - true - }); - let waiter = waiters.remove_unlinked_waiter(id); + let waiter = waiters.remove(id); + let acquired = self.requested_permits - waiter.needed_permits; if acquired > 0 { self.semaphore.distribute_permits(acquired, waiters); } else { diff --git a/asyncband/src/internal/waitlist.rs b/asyncband/src/internal/waitlist.rs index d26062ee..d2c3a5ea 100644 --- a/asyncband/src/internal/waitlist.rs +++ b/asyncband/src/internal/waitlist.rs @@ -100,7 +100,7 @@ impl WaitList { /// The node and its value remain available until /// [`remove_unlinked_waiter`](Self::remove_unlinked_waiter) is called. If the waiter is already /// detached, the predicate still runs but the list links are unchanged. - pub fn unlink_waiter( + fn unlink_waiter( &mut self, id: WaiterId, should_unlink: impl FnOnce(&mut T) -> bool, @@ -150,6 +150,12 @@ impl WaitList { &mut self.node_mut(id).value } + /// Removes a waiter by ID, whether it is still linked or already detached. + pub fn remove(&mut self, id: WaiterId) -> T { + self.unlink_waiter(id, |_| true); + self.remove_unlinked_waiter(id) + } + pub fn remove_unlinked_waiter(&mut self, id: WaiterId) -> T { assert!( self.node(id).links.is_none(), diff --git a/asyncband/src/mpmc/queue.rs b/asyncband/src/mpmc/queue.rs index 2196eab5..76f60e50 100644 --- a/asyncband/src/mpmc/queue.rs +++ b/asyncband/src/mpmc/queue.rs @@ -111,12 +111,6 @@ enum SendWaiter { Granted, } -fn remove_waiter(waiters: &mut WaitList, id: WaiterId) -> W { - // Unlinking is idempotent, so detached waiters are removed the same way as linked ones. - waiters.unlink_waiter(id, |_| true); - waiters.remove_unlinked_waiter(id) -} - impl WaitList { fn notify_one(&mut self) -> Option { let (_, waiter) = self.unlink_first_waiter(|_| true)?; @@ -141,7 +135,7 @@ impl WaitList { } if let Some(notified) = id.take() { // The notification already took this node's waker, so nothing is retired. - remove_waiter(self, notified); + self.remove_unlinked_waiter(notified); } *id = Some(self.push_back(RecvWaiter::Waiting(current.clone()))); None @@ -428,7 +422,7 @@ impl Drop for Reserve<'_, T> { if state.receivers == 0 { return; } - let retired = remove_waiter(&mut state.send_waiters, id); + let retired = state.send_waiters.remove(id); // A grant already owns a slot, so returning it does not require a capacity check. let waker = if matches!(retired, SendWaiter::Granted) { state.release() @@ -466,10 +460,7 @@ impl Recv<'_, T> { return Poll::Pending; } }; - let retired = self - .waiter - .take() - .map(|id| remove_waiter(&mut state.recv_waiters, id)); + let retired = self.waiter.take().map(|id| state.recv_waiters.remove(id)); drop(state); let result = outcome.map(|(value, waker)| { if let Some(waker) = waker { @@ -492,7 +483,7 @@ impl Drop for Recv<'_, T> { if state.senders == 0 { return; } - let retired = remove_waiter(&mut state.recv_waiters, id); + let retired = state.recv_waiters.remove(id); // Hand an unconsumed notification to the next receiver while a value still waits. let waker = if matches!(retired, RecvWaiter::Notified) && !state.values.is_empty() { state.recv_waiters.notify_one() diff --git a/asyncband/src/mpsc/bounded/sender.rs b/asyncband/src/mpsc/bounded/sender.rs index db56c5a7..8fa7a836 100644 --- a/asyncband/src/mpsc/bounded/sender.rs +++ b/asyncband/src/mpsc/bounded/sender.rs @@ -322,8 +322,7 @@ impl Drop for Reserve<'_, T> { if !state.receiver { return; } - state.send_waiters.unlink_waiter(index, |_| true); - let waiter = state.send_waiters.remove_unlinked_waiter(index); + let waiter = state.send_waiters.remove(index); let wake = if waiter.grant { state.release() } else { None }; (waiter, wake) }; diff --git a/asyncband/src/spmc/queue.rs b/asyncband/src/spmc/queue.rs index 9c8ce74d..37038e71 100644 --- a/asyncband/src/spmc/queue.rs +++ b/asyncband/src/spmc/queue.rs @@ -90,12 +90,6 @@ impl WaitList { Some(waker) } - fn remove_waiter(&mut self, id: WaiterId) -> Waiter { - // Unlinking is idempotent, so notified waiters are removed the same way as linked ones. - self.unlink_waiter(id, |_| true); - self.remove_unlinked_waiter(id) - } - /// Registers a pending operation's waker or refreshes an existing registration. /// /// If the future finds no value or slot after notification, its waiter rejoins the queue. @@ -111,7 +105,7 @@ impl WaitList { } if let Some(notified) = id.take() { // The notification already took this node's waker, so nothing is retired. - self.remove_waiter(notified); + self.remove_unlinked_waiter(notified); } *id = Some(self.push_back(Waiter::Waiting(current.clone()))); None @@ -253,10 +247,7 @@ impl Send<'_, T> { drop(retired); return Poll::Pending; }; - let retired = self - .waiter - .take() - .map(|id| state.send_waiters.remove_waiter(id)); + let retired = self.waiter.take().map(|id| state.send_waiters.remove(id)); drop(state); let result = outcome .map(|waker| { @@ -280,7 +271,7 @@ impl Drop for Send<'_, T> { if state.receivers == 0 { return; } - state.send_waiters.remove_waiter(id) + state.send_waiters.remove(id) }; drop(retired); } @@ -308,10 +299,7 @@ impl Recv<'_, T> { return Poll::Pending; } }; - let retired = self - .waiter - .take() - .map(|id| state.recv_waiters.remove_waiter(id)); + let retired = self.waiter.take().map(|id| state.recv_waiters.remove(id)); drop(state); let result = outcome.map(|(value, waker)| { if let Some(waker) = waker { @@ -334,7 +322,7 @@ impl Drop for Recv<'_, T> { if !state.sender_alive { return; } - let retired = state.recv_waiters.remove_waiter(id); + let retired = state.recv_waiters.remove(id); // Hand an unconsumed notification to the next receiver while a value still waits. let waker = if matches!(retired, Waiter::Notified) && !state.values.is_empty() { state.recv_waiters.notify_one() From 2be6e4d518a291a6bda1bdc45f15c6acaf2f84f4 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 17:57:23 +0800 Subject: [PATCH 3/7] refactor(mpsc): represent waiting and granted reservations explicitly A queued reservation owns a waker until it receives capacity. Represent that transition with two states so cancellation can distinguish an unclaimed grant from a sender still waiting for a slot. --- asyncband/src/mpsc/bounded/mod.rs | 13 ++++--- asyncband/src/mpsc/bounded/receiver.rs | 10 +++--- asyncband/src/mpsc/bounded/sender.rs | 48 +++++++++++--------------- 3 files changed, 35 insertions(+), 36 deletions(-) diff --git a/asyncband/src/mpsc/bounded/mod.rs b/asyncband/src/mpsc/bounded/mod.rs index d9accbc5..f100a57b 100644 --- a/asyncband/src/mpsc/bounded/mod.rs +++ b/asyncband/src/mpsc/bounded/mod.rs @@ -18,6 +18,7 @@ //! Bounded multi-producer, single-consumer channel with capacity backpressure. use std::collections::VecDeque; +use std::mem; use std::sync::Arc; use std::task::Waker; @@ -98,15 +99,17 @@ impl State { } if let Some((_, waiter)) = self.send_waiters.unlink_first_waiter(|_| true) { // The detached node owns capacity until its future claims or cancels the grant. - waiter.grant = true; - return waiter.waker.take(); + let Waiter::Waiting(waker) = mem::replace(waiter, Waiter::Granted) else { + unreachable!("only waiting senders remain linked"); + }; + return Some(waker); } self.available += 1; None } } -struct Waiter { - grant: bool, - waker: Option, +enum Waiter { + Waiting(Waker), + Granted, } diff --git a/asyncband/src/mpsc/bounded/receiver.rs b/asyncband/src/mpsc/bounded/receiver.rs index 92402978..76d4a81a 100644 --- a/asyncband/src/mpsc/bounded/receiver.rs +++ b/asyncband/src/mpsc/bounded/receiver.rs @@ -28,6 +28,7 @@ use crate::internal::waitlist::WaitList; use crate::mpsc::RecvError; use crate::mpsc::TryRecvError; use crate::mpsc::bounded::State; +use crate::mpsc::bounded::Waiter; /// The receiving endpoint of a bounded mpsc channel. /// @@ -55,10 +56,11 @@ impl Drop for BoundedReceiver { (queue, recv_waker, waiters) }; // Notify blocked senders before destroying buffered values, whose destructors may panic. - while let Some((_, waiter)) = waiters.unlink_first_waiter(|_| true) { - if let Some(waker) = waiter.waker.take() { - waker.wake(); - } + while let Some((id, _)) = waiters.unlink_first_waiter(|_| true) { + let Waiter::Waiting(waker) = waiters.remove_unlinked_waiter(id) else { + unreachable!("only waiting senders remain linked"); + }; + waker.wake(); } drop(recv_waker); drop(queue); diff --git a/asyncband/src/mpsc/bounded/sender.rs b/asyncband/src/mpsc/bounded/sender.rs index 8fa7a836..621f3886 100644 --- a/asyncband/src/mpsc/bounded/sender.rs +++ b/asyncband/src/mpsc/bounded/sender.rs @@ -23,7 +23,6 @@ use std::task::Context; use std::task::Poll; use crate::internal::mutex::Mutex; -use crate::internal::register_waker; use crate::internal::waitlist::WaiterId; use crate::mpsc::SendError; use crate::mpsc::TrySendError; @@ -283,34 +282,26 @@ impl<'a, T> Reserve<'a, T> { } if let Some(index) = self.waiter { let waiter = state.send_waiters.waiter_mut(index); - if waiter.grant { - let waiter = state.send_waiters.remove_unlinked_waiter(index); - self.waiter = None; - let permit = Permit { - shared: self.shared, - }; - drop(state); - drop(waiter); - return Poll::Ready(Ok(permit)); + if let Waiter::Waiting(waker) = waiter { + if !waker.will_wake(cx.waker()) { + let old = mem::replace(waker, cx.waker().clone()); + drop(state); + drop(old); + } + return Poll::Pending; } - let old = register_waker(&mut waiter.waker, cx.waker()); - drop(state); - drop(old); - return Poll::Pending; - } - if state.available != 0 { + state.send_waiters.remove_unlinked_waiter(index); + self.waiter = None; + } else if state.available != 0 { state.available -= 1; - let permit = Permit { - shared: self.shared, - }; - drop(state); - return Poll::Ready(Ok(permit)); + } else { + let waiter = Waiter::Waiting(cx.waker().clone()); + self.waiter = Some(state.send_waiters.push_back(waiter)); + return Poll::Pending; } - self.waiter = Some(state.send_waiters.push_back(Waiter { - grant: false, - waker: Some(cx.waker().clone()), - })); - Poll::Pending + Poll::Ready(Ok(Permit { + shared: self.shared, + })) } } @@ -323,7 +314,10 @@ impl Drop for Reserve<'_, T> { return; } let waiter = state.send_waiters.remove(index); - let wake = if waiter.grant { state.release() } else { None }; + let wake = match waiter { + Waiter::Granted => state.release(), + Waiter::Waiting(_) => None, + }; (waiter, wake) }; if let Some(waker) = wake { From f82a4eff204c5faca70dc61ecd6e07a8f8b10998 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 17:57:39 +0800 Subject: [PATCH 4/7] refactor(once-map): name the ready-entry lookup used by get Keep the initialized-entry filter under the table lock and clone the value in get after unlocking. The lookup also owns the borrowed-key hash and comparison used by the cancellation regression test. --- asyncband/src/once/once_map/mod.rs | 27 +++++++++------------------ asyncband/src/once/once_map/tests.rs | 2 +- 2 files changed, 10 insertions(+), 19 deletions(-) diff --git a/asyncband/src/once/once_map/mod.rs b/asyncband/src/once/once_map/mod.rs index 0d30b27d..896fd470 100644 --- a/asyncband/src/once/once_map/mod.rs +++ b/asyncband/src/once/once_map/mod.rs @@ -114,28 +114,18 @@ where } } - fn find_entry( - &self, - hash: u64, - matches: impl Fn(&Entry) -> bool, - ) -> Option>> { - // A reader holding a pending entry would stop an abandoned computation from reclaiming it. - self.entries - .lock() - .find(hash, |entry| matches(entry)) - .filter(|entry| entry.cell.initialized()) - .cloned() - } - - fn get_value(&self, key: &Q) -> Option + fn find_ready_entry(&self, key: &Q) -> Option>> where K: Borrow, Q: Eq + Hash + ?Sized, - V: Clone, { let hash = self.hasher.hash_one(key); - let entry = self.find_entry(hash, |entry| entry.key.borrow() == key)?; - entry.cell.get().cloned() + // A reader holding a pending entry would stop an abandoned computation from reclaiming it. + self.entries + .lock() + .find(hash, |entry| entry.key.borrow() == key) + .filter(|entry| entry.cell.initialized()) + .cloned() } fn remove_entry(&self, key: &Q) -> Option>> @@ -383,7 +373,8 @@ where K: Borrow, Q: Hash + Eq + ?Sized, { - self.get_value(key) + let entry = self.find_ready_entry(key)?; + entry.cell.get().cloned() } /// Evicts `key` from the map without cloning any stored value. diff --git a/asyncband/src/once/once_map/tests.rs b/asyncband/src/once/once_map/tests.rs index 54532e9c..32823e93 100644 --- a/asyncband/src/once/once_map/tests.rs +++ b/asyncband/src/once/once_map/tests.rs @@ -96,7 +96,7 @@ fn cancelled_compute_removes_empty_entry_during_get() { // A concurrent `get` holds its lookup result after releasing the table lock. Cancel the // computation inside that window. - let held_by_get = map.find_entry(map.hasher.hash_one("key"), |entry| entry.key == "key"); + let held_by_get = map.find_ready_entry("key"); drop(compute); drop(held_by_get); From 5ad7fca786a4278ce27ebcb6c018458ff94d03c4 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 17:57:52 +0800 Subject: [PATCH 5/7] refactor(mutex): name the permit count held by each guard Use a single count for acquisition and release across borrowed, owned, and mapped guards, and derive the initial balance from that count plus one spare permit. --- asyncband/src/mutex/mod.rs | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/asyncband/src/mutex/mod.rs b/asyncband/src/mutex/mod.rs index f8b19639..b50029a2 100644 --- a/asyncband/src/mutex/mod.rs +++ b/asyncband/src/mutex/mod.rs @@ -75,6 +75,8 @@ use std::sync::Arc; use crate::internal::semaphore; +const PERMITS_PER_LOCK: usize = 2; + /// An asynchronous mutex that grants exclusive access in request order. /// /// See the [module level documentation](self) for more. @@ -120,9 +122,9 @@ impl Mutex { /// let mutex = Mutex::new(5); /// ``` pub const fn new(t: T) -> Self { - // Each lock takes two of three permits, so only one can run at a time. The spare - // permit lets an uncontended release avoid locking the semaphore's wait queue. - let s = semaphore::Semaphore::new(3); + // One spare permit lets an uncontended release bypass the semaphore's wait queue + // while leaving too few permits for another acquisition. + let s = semaphore::Semaphore::new(PERMITS_PER_LOCK + 1); let c = UnsafeCell::new(t); Self { s, c } } @@ -166,7 +168,7 @@ impl Mutex { /// # } /// ``` pub async fn lock(&self) -> MutexGuard<'_, T> { - self.s.acquire(2).await; + self.s.acquire(PERMITS_PER_LOCK).await; MutexGuard { lock: self } } @@ -186,7 +188,7 @@ impl Mutex { /// assert_eq!(count.into_inner(), 8); /// ``` pub fn try_lock(&self) -> Option> { - if self.s.try_acquire(2) { + if self.s.try_acquire(PERMITS_PER_LOCK) { let guard = MutexGuard { lock: self }; Some(guard) } else { @@ -228,7 +230,7 @@ impl Mutex { /// # } /// ``` pub async fn lock_owned(self: Arc) -> OwnedMutexGuard { - self.s.acquire(2).await; + self.s.acquire(PERMITS_PER_LOCK).await; OwnedMutexGuard { lock: self } } @@ -251,7 +253,7 @@ impl Mutex { /// assert_eq!(shared.try_lock_owned().unwrap().len(), 2); /// ``` pub fn try_lock_owned(self: Arc) -> Option> { - if self.s.try_acquire(2) { + if self.s.try_acquire(PERMITS_PER_LOCK) { let guard = OwnedMutexGuard { lock: self }; Some(guard) } else { @@ -296,7 +298,7 @@ unsafe impl Sync for MutexGuard<'_, T> {} impl Drop for MutexGuard<'_, T> { fn drop(&mut self) { - self.lock.s.release(2); + self.lock.s.release(PERMITS_PER_LOCK); } } @@ -450,7 +452,7 @@ unsafe impl Sync for OwnedMutexGuard {} impl Drop for OwnedMutexGuard { fn drop(&mut self) { - self.lock.s.release(2); + self.lock.s.release(PERMITS_PER_LOCK); } } @@ -648,7 +650,7 @@ unsafe impl Sync for MappedMutexGuard<'_, T> {} impl Drop for MappedMutexGuard<'_, T> { fn drop(&mut self) { - self.s.release(2); + self.s.release(PERMITS_PER_LOCK); } } @@ -841,7 +843,7 @@ unsafe impl Sync for OwnedMapp impl Drop for OwnedMappedMutexGuard { fn drop(&mut self) { - self.lock.s.release(2); + self.lock.s.release(PERMITS_PER_LOCK); } } From 37455399da3609bcd202b0de4083be37561dfd54 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 17:58:02 +0800 Subject: [PATCH 6/7] refactor(waitgroup): trim unused internal lock methods The waitgroup takes exclusive access to its waiter list. Remove the unused read and get_mut methods from its lock wrapper and let dead-code checks apply to the module. --- asyncband/src/internal/mod.rs | 2 -- asyncband/src/internal/rwlock.rs | 8 -------- 2 files changed, 10 deletions(-) diff --git a/asyncband/src/internal/mod.rs b/asyncband/src/internal/mod.rs index 29a3e73c..65b65a4a 100644 --- a/asyncband/src/internal/mod.rs +++ b/asyncband/src/internal/mod.rs @@ -83,8 +83,6 @@ pub(crate) mod value_cell; pub(crate) mod mutex; #[cfg(feature = "waitgroup")] -// Some primitives use only exclusive access, leaving `read` and `get_mut` unused. -#[allow(dead_code)] pub(crate) mod rwlock; #[cfg(any( diff --git a/asyncband/src/internal/rwlock.rs b/asyncband/src/internal/rwlock.rs index a4c06c83..75f03d4a 100644 --- a/asyncband/src/internal/rwlock.rs +++ b/asyncband/src/internal/rwlock.rs @@ -31,15 +31,7 @@ impl RwLock { Self(std::sync::RwLock::new(t)) } - pub fn read(&self) -> std::sync::RwLockReadGuard<'_, T> { - self.0.read().unwrap_or_else(PoisonError::into_inner) - } - pub fn write(&self) -> std::sync::RwLockWriteGuard<'_, T> { self.0.write().unwrap_or_else(PoisonError::into_inner) } - - pub fn get_mut(&mut self) -> &mut T { - self.0.get_mut().unwrap_or_else(PoisonError::into_inner) - } } From c4e7dc32e260feeeabac12865e46a898bffdb9fc Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 18:20:08 +0800 Subject: [PATCH 7/7] refactor(once-cell): name the permits held by an initializer Derive the semaphore capacity in both constructors from the initializer permit count plus one spare. This keeps the capacity and acquisition paths tied to the same exclusivity rule. --- asyncband/src/once/once_cell/mod.rs | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/asyncband/src/once/once_cell/mod.rs b/asyncband/src/once/once_cell/mod.rs index e652dae5..4a537055 100644 --- a/asyncband/src/once/once_cell/mod.rs +++ b/asyncband/src/once/once_cell/mod.rs @@ -31,6 +31,10 @@ use crate::internal::value_cell::ValueCell; use crate::semaphore::Semaphore; use crate::semaphore::SemaphorePermit; +// One spare permit lets an uncontended release bypass the wait queue while leaving too few +// permits for a second initializer. +const PERMITS_PER_INITIALIZER: usize = 2; + /// A thread-safe cell that stores one value from an initializer supplied at access time. /// /// Callers provide an initializer when accessing an empty cell. An initializer that returns an @@ -59,8 +63,6 @@ use crate::semaphore::SemaphorePermit; /// ``` pub struct OnceCell { value: ValueCell, - // Each initializer takes two of three permits, so only one can run at a time. The spare - // permit lets an uncontended release avoid locking the semaphore's wait queue. semaphore: Semaphore, } @@ -75,7 +77,7 @@ impl OnceCell { pub const fn new() -> Self { Self { value: ValueCell::empty(), - semaphore: Semaphore::new(3), + semaphore: Semaphore::new(PERMITS_PER_INITIALIZER + 1), } } @@ -83,7 +85,7 @@ impl OnceCell { pub const fn from_value(value: T) -> Self { Self { value: ValueCell::with_value(value), - semaphore: Semaphore::new(3), + semaphore: Semaphore::new(PERMITS_PER_INITIALIZER + 1), } } @@ -179,7 +181,7 @@ impl OnceCell { return Ok(v); } - let permit = self.semaphore.acquire(2).await; + let permit = self.semaphore.acquire(PERMITS_PER_INITIALIZER).await; if let Some(v) = self.get() { // Another task initialized the cell while we waited for permits. @@ -408,7 +410,8 @@ impl OnceCell { } fn set_value(&self, value: T, _permit: SemaphorePermit<'_>) -> &T { - // SAFETY: Holding two of the three semaphore permits serializes initialization. + // SAFETY: The caller checked that the cell was empty while holding the initializer's + // permits. Holding them through publication excludes other initializers. unsafe { self.value.publish(value) } }