vthread 0.1.0

Bounded carrier-affine virtual threads for Rust
Documentation
//! Public one-permit parking and wake handles.
//!
//! ```
//! use std::{rc::Rc, thread, time::Duration};
//! use vthread::{Runtime, parking::{ParkOutcome, park_pair}};
//!
//! fn main() -> vthread::Result<()> {
//!     let runtime = Runtime::builder().carriers(2).build()?;
//!     runtime.run_scope(|scope| {
//!         let (parker, unparker) = park_pair();
//!         let mut waiter = scope.spawn("waiter", move || {
//!             let owner = thread::current().id();
//!             let local = Rc::new(52);
//!             let outcome = parker.park_timeout(Duration::from_secs(5))?;
//!             assert_eq!(thread::current().id(), owner);
//!             Ok::<_, vthread::Error>((*local, outcome))
//!         })?;
//!         thread::spawn(move || unparker.unpark()).join().expect("remote waker");
//!         assert_eq!(waiter.join()??, (52, ParkOutcome::Ready));
//!         Ok(())
//!     })?;
//!     runtime.shutdown().map(|_| ())
//! }
//! ```

use std::{
    fmt,
    time::{Duration, Instant},
};

use crate::{
    Error, Result,
    context::{self, Execution},
    wait::{NotifyResult, WaitBegin, WaitCell, WaitRegistration, WakeCause},
};
use vthread_stack::ParkToken;

#[path = "parking_wait.rs"]
mod parking_wait;

/// The exact selected winner for one parking generation.
///
/// Once a winner is selected, later inherited cancellation or deadline expiry
/// cannot replace it. Policy is observed at the next cooperative boundary.
/// Inherited cancellation selecting first returns [`Error::Cancelled`]; inherited
/// deadline selection returns [`Error::DeadlineExceeded`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ParkOutcome {
    /// Readiness or an explicit unpark operation won.
    Ready,
    /// The monotonic deadline won.
    TimedOut,
    /// Explicit [`Unparker::cancel`] won; this is distinct from inherited cancellation.
    Cancelled,
    /// The parking pair was permanently closed.
    Closed,
}

/// The effect of an `Unparker::unpark` call.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum UnparkResult {
    /// An active parked task was selected for wakeup.
    Woke,
    /// A single permit was stored for the next park operation.
    Stored,
    /// The pair was already closed.
    Closed,
}

/// The single-consumer side of a bounded one-permit wake primitive.
///
/// A park operation that reaches its suspension preflight while the carrier is
/// handling a panic returns [`Error::SuspensionDuringPanic`] before consuming a
/// stored permit or publishing wait state.
pub struct Parker {
    pub(crate) wait: WaitCell,
}

impl Parker {
    /// Parks the current virtual thread until readiness, cancellation, or close.
    pub fn park(&self) -> Result<ParkOutcome> {
        self.park_deadline(None)
    }

    /// Parks until a relative monotonic timeout expires.
    pub fn park_timeout(&self, timeout: Duration) -> Result<ParkOutcome> {
        let deadline = Instant::now()
            .checked_add(timeout)
            .ok_or(Error::DeadlineOverflow)?;
        self.park_deadline(Some(deadline))
    }

    /// Parks until an absolute monotonic deadline.
    pub fn park_until(&self, deadline: Instant) -> Result<ParkOutcome> {
        self.park_deadline(Some(deadline))
    }

    fn park_deadline(&self, deadline: Option<Instant>) -> Result<ParkOutcome> {
        self.park_with(deadline, |_, _| Ok(()))
    }

    pub(crate) fn park_after_checkpoint(&self, execution: &Execution) -> Result<ParkOutcome> {
        let handoff = if execution.owns_synchronization_wait(&self.wait) {
            WaitHandoff::TaskResident
        } else {
            WaitHandoff::Shared
        };
        park_wait::<false, false, _>(execution, &self.wait, None, handoff, |_, _| Ok(()))
    }

    pub(crate) fn park_registered<G>(
        &self,
        register: impl FnOnce(ParkToken, &WaitRegistration) -> Result<G>,
    ) -> Result<ParkOutcome> {
        self.park_with(None, register)
    }

    fn park_with<G>(
        &self,
        deadline: Option<Instant>,
        register: impl FnOnce(ParkToken, &WaitRegistration) -> Result<G>,
    ) -> Result<ParkOutcome> {
        let mounted = context::current().ok_or(Error::OutsideVThread)?;
        let execution = mounted.execution()?;
        execution.data.check()?;
        park_wait::<true, false, _>(
            execution,
            &self.wait,
            deadline,
            WaitHandoff::Shared,
            |token, registration| register(token, registration.expect("shared wait registration")),
        )
    }
}

pub(crate) fn park_wait_after_checkpoint<const PLAIN_READY: bool, const PERMIT_READY: bool>(
    wait: &WaitCell,
    execution: &Execution,
) -> Result<ParkOutcome> {
    park_wait::<PLAIN_READY, PERMIT_READY, _>(
        execution,
        wait,
        None,
        WaitHandoff::TaskResident,
        |_, _| Ok(()),
    )
}
#[derive(Clone, Copy)]
enum WaitHandoff {
    Shared,
    TaskResident,
}

fn park_wait<const PLAIN_READY: bool, const PERMIT_READY: bool, G>(
    execution: &Execution,
    wait: &WaitCell,
    deadline: Option<Instant>,
    handoff: WaitHandoff,
    register: impl FnOnce(ParkToken, Option<&WaitRegistration>) -> Result<G>,
) -> Result<ParkOutcome> {
    // Reject before consuming a permit or publishing a wait generation. The stack
    // boundary checks again immediately before every context switch.
    vthread_stack::check_suspend().map_err(Error::from)?;
    let policy = &execution.data;
    let unmasked = policy.masked() == 0;
    let inherited_deadline = policy.deadline().filter(|_| unmasked);
    let inherited_timeout = inherited_deadline
        .is_some_and(|inherited| deadline.is_none_or(|explicit| inherited <= explicit));
    let deadline = deadline.into_iter().chain(inherited_deadline).min();
    let begin = match handoff {
        WaitHandoff::Shared => wait
            .begin(
                execution.id,
                execution.task_key(),
                execution.hub(),
                deadline,
            )?
            .map_registration(Some),
        WaitHandoff::TaskResident => wait
            .begin_resident(
                execution.id,
                execution.task_key(),
                execution.hub(),
                deadline,
            )?
            .map_registration(|()| None),
    };
    match begin {
        WaitBegin::Immediate(cause) => selected(cause, inherited_timeout),
        WaitBegin::Park {
            request,
            registration,
        } => selected(
            parking_wait::park::<PLAIN_READY, PERMIT_READY, _>(
                execution,
                wait,
                request,
                registration,
                register,
            )?,
            inherited_timeout,
        ),
    }
}

impl fmt::Debug for Parker {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.debug_struct("Parker").finish_non_exhaustive()
    }
}

/// Cloneable control side of a parking pair.
#[derive(Clone)]
pub struct Unparker {
    wait: WaitCell,
}

impl Unparker {
    /// Wakes the active generation or stores one future permit.
    pub fn unpark(&self) -> UnparkResult {
        match self.wait.notify() {
            NotifyResult::Woke => UnparkResult::Woke,
            NotifyResult::Stored => UnparkResult::Stored,
            NotifyResult::Closed => UnparkResult::Closed,
        }
    }

    /// Cancels the active generation without closing the pair.
    pub fn cancel(&self) -> bool {
        self.wait.cancel()
    }

    /// Permanently closes the pair and wakes an active generation.
    pub fn close(&self) -> bool {
        self.wait.close()
    }

    /// Returns whether the pair is permanently closed.
    pub fn is_closed(&self) -> bool {
        self.wait.is_closed()
    }
}

impl fmt::Debug for Unparker {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Unparker")
            .field("closed", &self.is_closed())
            .finish_non_exhaustive()
    }
}

/// Creates a single-consumer parker and cloneable wake handle.
pub fn park_pair() -> (Parker, Unparker) {
    let wait = WaitCell::new();
    (Parker { wait: wait.clone() }, Unparker { wait })
}

fn selected(cause: WakeCause, inherited_timeout: bool) -> Result<ParkOutcome> {
    match cause {
        WakeCause::Ready => Ok(ParkOutcome::Ready),
        WakeCause::TimedOut if inherited_timeout => Err(Error::DeadlineExceeded),
        WakeCause::TimedOut => Ok(ParkOutcome::TimedOut),
        WakeCause::Cancelled => Ok(ParkOutcome::Cancelled),
        WakeCause::InheritedCancelled => Err(Error::Cancelled),
        WakeCause::Closed => Ok(ParkOutcome::Closed),
    }
}

#[cfg(test)]
#[path = "parking_test.rs"]
mod parking_test;

#[cfg(test)]
#[path = "parking_deadline_test.rs"]
mod parking_deadline_test;