diff --git a/RELEASE-NOTES.mkdn b/RELEASE-NOTES.mkdn index 3cc8df2..6f8d0ef 100644 --- a/RELEASE-NOTES.mkdn +++ b/RELEASE-NOTES.mkdn @@ -7,6 +7,11 @@ porting existing programs, look for uses of the `sleep_*`, `with_*`, and `PeriodicGate` APIs; they have moved. +- Renamed `spsc` and `handoff` split handle types: `Push` is now `Pusher`, `Pop` + is now `Popper`. (Because their old names sounded like what you'd name the + future type for _completing_ a push or pop, and I felt like that was + misleading.) + - Totally reworked the Mutex API to further improve robustness in the face of cancellation. - The basic locking operation `lock` (and its friend `try_lock`) now return a diff --git a/os/src/handoff.rs b/os/src/handoff.rs index bba6518..849c5c1 100644 --- a/os/src/handoff.rs +++ b/os/src/handoff.rs @@ -16,9 +16,10 @@ //! # Creating and using a `Handoff` //! //! Because the `Handoff` itself contains no storage, they're cheap to create on -//! the stack. You then need to `split` then into their `Push` and `Pop` ends -- -//! these both _borrow_ the `Handoff`, so you need to keep it around. You can -//! then hand the ends off to other futures. A typical use case looks like this: +//! the stack. You then need to `split` then into their `Pusher` and `Popper` +//! ends -- these both _borrow_ the `Handoff`, so you need to keep it around. +//! You can then hand the ends off to other futures. A typical use case looks +//! like this: //! //! ```ignore //! let mut handoff = Handoff::new(); @@ -31,9 +32,9 @@ //! //! # Caveats and alternatives //! -//! Only one `Push` and `Pop` can exist at a time -- the compiler ensures this. -//! This simplifies the implementation quite a bit, but it means that if you -//! want a multi-party rendezvous this isn't the right tool. +//! Only one `Pusher` and `Popper` can exist at a time -- the compiler ensures +//! this. This simplifies the implementation quite a bit, but it means that if +//! you want a multi-party rendezvous this isn't the right tool. //! //! If you would like to be able to push data and go on about your business //! without waiting for it to be popped, you want a queue, not a handoff. See @@ -50,8 +51,8 @@ //! //! This module is currently the only part of `lilos` that has non-deprecated //! API that is not strictly cancel-safe. This is often okay, the way handoffs -//! are used (in my code at least), but please read the docs for [`Push::push`] -//! carefully. +//! are used (in my code at least), but please read the docs for +//! [`Pusher::push`] carefully. use core::cell::Cell; use core::ptr::NonNull; @@ -77,12 +78,12 @@ impl Handoff { } } - /// Borrows `self` exclusively and produces `Push` and `Pop` endpoints. The - /// endpoints are guaranteed to be unique, since they can't be cloned and - /// you can't call `split` to make new ones until both are + /// Borrows `self` exclusively and produces `Pusher` and `Popper` endpoints. + /// The endpoints are guaranteed to be unique, since they can't be cloned + /// and you can't call `split` to make new ones until both are /// dropped/forgotten. - pub fn split(&mut self) -> (Push<'_, T>, Pop<'_, T>) { - (Push(self), Pop(self)) + pub fn split(&mut self) -> (Pusher<'_, T>, Popper<'_, T>) { + (Pusher(self), Popper(self)) } } @@ -150,14 +151,14 @@ impl Clone for State { } /// Push endpoint for a `Handoff`. Holding this allows you to offer a single -/// item at a time to whoever's holding the `Pop` side. -pub struct Push<'a, T>(&'a Handoff); +/// item at a time to whoever's holding the `Popper` side. +pub struct Pusher<'a, T>(&'a Handoff); -impl Push<'_, T> { +impl Pusher<'_, T> { /// Offers `value` to our peer, if they are waiting to receive it. /// - /// If someone is blocked on the `Pop` side, `value` is transferred to them, - /// they are unblocked, and this returns `Ok(())`. + /// If someone is blocked on the `Popper` side, `value` is transferred to + /// them, they are unblocked, and this returns `Ok(())`. /// /// Otherwise, it returns `Err(value)`, giving `value` back to you. pub fn try_push(&mut self, value: T) -> Result<(), T> { @@ -250,18 +251,18 @@ impl Push<'_, T> { } /// Implement Debug by hand so it doesn't require T: Debug. -impl core::fmt::Debug for Push<'_, T> { +impl core::fmt::Debug for Pusher<'_, T> { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - f.debug_tuple("Push").field(&self.0).finish() + f.debug_tuple("Pusher").field(&self.0).finish() } } /// Pop endpoint for a `Handoff`. Holding this allows you to take a single -/// item at a time from whoever's holding the `Push` side. -pub struct Pop<'a, T>(&'a Handoff); +/// item at a time from whoever's holding the `Pusher` side. +pub struct Popper<'a, T>(&'a Handoff); -impl Pop<'_, T> { - /// Takes data from the `Push` peer if it's waiting. +impl Popper<'_, T> { + /// Takes data from the `Pusher` peer if it's waiting. /// /// If the peer is blocked offering us data, this unblocks them and returns /// `Some(value)`. @@ -292,7 +293,7 @@ impl Pop<'_, T> { /// **Cancel Safety:** Strict. /// /// If this is dropped before it resolves, no data will be lost: we have - /// either taken data from the `Push` side and resolved, or we have not + /// either taken data from the `Pusher` side and resolved, or we have not /// taken data. pub async fn pop(&mut self) -> T { let mut guard = scopeguard::guard(None, |v| { @@ -352,8 +353,8 @@ impl Pop<'_, T> { } /// Implement Debug by hand so it doesn't require T: Debug. -impl core::fmt::Debug for Pop<'_, T> { +impl core::fmt::Debug for Popper<'_, T> { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - f.debug_tuple("Pop").field(&self.0).finish() + f.debug_tuple("Popper").field(&self.0).finish() } }