Skip to main content

vthread_stack/
lease.rs

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