Skip to main content

vthread_stack/
lease.rs

1//! Explicit lease transitions keep metadata borrows off executing fiber stacks.
2
3use crate::{Fiber, FiberState, MappedStack, Resume, panic_payload};
4use std::{any::Any, cell::RefCell, rc::Rc};
5
6type Cleanup = Rc<dyn Fn() -> Box<dyn Any>>;
7
8#[derive(Clone, Copy, PartialEq, Eq)]
9enum Phase {
10    Ready,
11    Running,
12    Complete,
13    Reclaiming,
14    Reclaimed,
15}
16
17struct State {
18    phase: Phase,
19    fiber: Option<Fiber>,
20    cleanup: Option<Cleanup>,
21}
22
23/// An internal carrier-local lease; scope exit revokes its executable stack.
24#[derive(Clone)]
25pub struct FiberLease(Rc<RefCell<State>>);
26
27impl FiberLease {
28    pub(crate) fn new(fiber: Fiber) -> Self {
29        Self(Rc::new(RefCell::new(State {
30            phase: Phase::Ready,
31            fiber: Some(fiber),
32            cleanup: None,
33        })))
34    }
35
36    /// Resumes a ready stack. Reclaimed leases return None; reentrant resumes panic.
37    pub fn resume(&self) -> Option<FiberState> {
38        self.resume_with(Resume::Continue)
39    }
40
41    /// Resumes a ready stack and delivers a decision to its last suspension point.
42    pub fn resume_with(&self, resume: Resume) -> Option<FiberState> {
43        self.resume_using(|fiber| fiber.resume_with(resume))
44    }
45
46    /// Resumes a ready stack with typed runtime context for this resume only.
47    #[doc(hidden)]
48    pub fn resume_with_context<T>(
49        &self,
50        resume: Resume,
51        key: &'static crate::ContextKey<T>,
52        value: &T,
53    ) -> Option<FiberState> {
54        self.resume_using(|fiber| fiber.resume_with_context(resume, key, value))
55    }
56
57    fn resume_using(&self, mount: impl FnOnce(&mut Fiber) -> FiberState) -> Option<FiberState> {
58        let fiber = {
59            let mut state = self.0.borrow_mut();
60            if state.phase == Phase::Reclaimed {
61                return None;
62            }
63            assert!(state.phase == Phase::Ready, "lease is not ready to resume");
64            state.phase = Phase::Running;
65            state.fiber.take().expect("ready fiber")
66        };
67        let mut running = Running {
68            lease: self,
69            fiber: Some(fiber),
70        };
71        Some(mount(running.fiber.as_mut().expect("running fiber")))
72    }
73
74    /// Takes a completed stack. Every other phase retains ownership and returns None.
75    pub fn take_stack(&self) -> Option<MappedStack> {
76        let (fiber, cleanup) = {
77            let mut state = self.0.borrow_mut();
78            if state.phase != Phase::Complete {
79                return None;
80            }
81            state.phase = Phase::Reclaimed;
82            (state.fiber.take(), state.cleanup.take())
83        };
84        let stack = fiber.map(Fiber::into_stack);
85        drop(cleanup);
86        stack
87    }
88
89    /// Reclaims a ready/completed stack. Failed mount setup leaves ownership intact.
90    /// A running or already reclaiming stack cannot be reclaimed reentrantly.
91    pub fn reclaim(&self) {
92        let (previous, cleanup) = {
93            let mut state = self.0.borrow_mut();
94            if state.phase == Phase::Reclaimed {
95                return;
96            }
97            assert!(
98                matches!(state.phase, Phase::Ready | Phase::Complete),
99                "lease is executing or reclaiming"
100            );
101            let previous = state.phase;
102            state.phase = Phase::Reclaiming;
103            (previous, state.cleanup.clone())
104        };
105        let _restore = Reclaiming {
106            lease: self,
107            previous,
108        };
109        // Do not take the fiber until its cleanup context has been mounted successfully.
110        let context = cleanup.as_ref().map(|mount| mount());
111        let (fiber, retained) = {
112            let mut state = self.0.borrow_mut();
113            state.phase = Phase::Reclaimed;
114            (state.fiber.take(), state.cleanup.take())
115        };
116        let mut failure = None;
117        panic_payload::dispose(fiber, &mut failure);
118        panic_payload::dispose(retained, &mut failure);
119        panic_payload::dispose(cleanup, &mut failure);
120        panic_payload::dispose(context, &mut failure);
121        if let Some(failure) = failure {
122            std::panic::resume_unwind(Box::new(failure));
123        }
124    }
125
126    /// Whether the scope retains this fiber, including while it is executing.
127    pub fn live(&self) -> bool {
128        self.0.borrow().phase != Phase::Reclaimed
129    }
130
131    /// Installs the runtime's cleanup mount. Mutating an executing lease panics.
132    pub fn cleanup_context(&self, mount: impl Fn() -> Box<dyn Any> + 'static) {
133        let replaced = {
134            let mut state = self.0.borrow_mut();
135            assert!(
136                matches!(state.phase, Phase::Ready | Phase::Complete),
137                "lease is not idle"
138            );
139            state.cleanup.replace(Rc::new(mount))
140        };
141        drop(replaced);
142    }
143}
144
145struct Running<'a> {
146    lease: &'a FiberLease,
147    fiber: Option<Fiber>,
148}
149impl Drop for Running<'_> {
150    fn drop(&mut self) {
151        let fiber = self.fiber.take().expect("owned running fiber");
152        let mut state = self.lease.0.borrow_mut();
153        state.phase = if fiber.is_complete() {
154            Phase::Complete
155        } else {
156            Phase::Ready
157        };
158        state.fiber = Some(fiber);
159    }
160}
161
162struct Reclaiming<'a> {
163    lease: &'a FiberLease,
164    previous: Phase,
165}
166impl Drop for Reclaiming<'_> {
167    fn drop(&mut self) {
168        let mut state = self.lease.0.borrow_mut();
169        if state.phase == Phase::Reclaiming {
170            state.phase = self.previous;
171        }
172    }
173}
174
175#[cfg(test)]
176#[path = "lease_test.rs"]
177mod lease_test;