Skip to main content

vthread_stack/
suspension.rs

1//! Suspension, resumption, and outcome values shared by every stack engine.
2
3use std::{error::Error, fmt, time::Instant};
4
5/// Identity for one generation of a parking operation.
6#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
7pub struct ParkToken {
8    wait: u64,
9    generation: u64,
10}
11
12impl ParkToken {
13    /// Creates a scheduler-visible token.
14    pub fn new(wait: u64, generation: u64) -> Self {
15        Self { wait, generation }
16    }
17
18    /// Returns the stable parking-object identity.
19    pub fn wait(self) -> u64 {
20        self.wait
21    }
22
23    /// Returns the monotonically increasing wait generation.
24    pub fn generation(self) -> u64 {
25        self.generation
26    }
27}
28
29/// Scheduler data supplied when a task parks.
30#[derive(Clone, Debug, PartialEq, Eq)]
31pub struct ParkRequest {
32    token: ParkToken,
33    deadline: Option<Instant>,
34}
35
36impl ParkRequest {
37    /// Creates a parking request with an optional monotonic deadline.
38    pub fn new(token: ParkToken, deadline: Option<Instant>) -> Self {
39        Self { token, deadline }
40    }
41
42    /// Returns the wait token.
43    pub fn token(&self) -> ParkToken {
44        self.token
45    }
46
47    /// Returns the monotonic deadline, if one exists.
48    pub fn deadline(&self) -> Option<Instant> {
49        self.deadline
50    }
51}
52
53/// A reason a mounted fiber returned control to its carrier.
54#[derive(Clone, Debug, PartialEq, Eq)]
55pub enum Suspension {
56    /// The virtual thread cooperatively yielded its turn.
57    YieldNow,
58    /// The virtual thread parked on a modeled wait generation.
59    Park(ParkRequest),
60}
61
62/// The outcome of mounting a fiber once.
63#[derive(Clone, Debug, PartialEq, Eq)]
64pub enum FiberState {
65    /// Execution suspended with the supplied reason.
66    Suspended(Suspension),
67    /// The fiber returned from its entry function.
68    Complete,
69}
70
71/// A carrier decision delivered to the operation that suspended the fiber.
72#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
73pub enum Resume {
74    /// Continue the suspended operation normally.
75    #[default]
76    Continue,
77    /// Recheck runtime policy before the suspended operation returns.
78    Interrupt,
79}
80
81/// Why a requested fiber suspension could not safely start.
82#[derive(Clone, Copy, Debug, PartialEq, Eq)]
83pub enum SuspendError {
84    /// No virtual-thread stack is mounted on this carrier.
85    NotMounted,
86    /// The carrier is running a panic hook or unwinding a panic.
87    Panicking,
88}
89
90impl fmt::Display for SuspendError {
91    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
92        match self {
93            Self::NotMounted => {
94                formatter.write_str("no virtual-thread stack is mounted on this carrier")
95            }
96            Self::Panicking => formatter.write_str(
97                "a virtual-thread stack cannot suspend while its carrier is handling a panic",
98            ),
99        }
100    }
101}
102
103impl Error for SuspendError {}
104
105#[cfg(test)]
106#[path = "suspension_test.rs"]
107mod suspension_test;