1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
//! Carrier-local stackful fiber.
use crate::{
FiberState, MappedStack, Resume, engine,
mount::{ContextSlot, CoreMount, MountGuard},
};
/// One carrier-local stackful execution context.
///
/// ```compile_fail
/// fn require_send<T: Send>() {}
/// require_send::<vthread_stack::Fiber>();
/// ```
pub struct Fiber {
execution: Option<engine::Execution>,
}
impl Fiber {
/// Creates a fiber on an already allocated stack.
pub fn new<F>(stack: MappedStack, entry: F) -> Self
where
F: FnOnce() + 'static,
{
// SAFETY: a static entry has no borrowed environment to outlive.
unsafe { Self::borrowed(stack, entry) }
}
/// The caller must reclaim this fiber before the entry's borrows expire.
pub(crate) unsafe fn borrowed<F: FnOnce()>(stack: MappedStack, entry: F) -> Self {
// SAFETY: the caller owns the entry's lifetime and guarantees reclamation.
let execution = unsafe { engine::Execution::start(stack, entry) };
Self {
execution: Some(execution),
}
}
/// Mounts the fiber until it suspends or completes.
///
/// Panics if the fiber has already completed, without mounting its old control block.
#[inline]
pub fn resume(&mut self) -> FiberState {
self.resume_with(Resume::Continue)
}
/// Mounts the fiber and delivers a decision to its last suspension point.
#[inline]
pub fn resume_with(&mut self, resume: Resume) -> FiberState {
self.resume_mounted(resume, None)
}
/// Mounts the fiber with typed runtime context for this resume only.
#[doc(hidden)]
#[inline]
pub fn resume_with_context<T>(
&mut self,
resume: Resume,
key: &'static crate::ContextKey<T>,
value: &T,
) -> FiberState {
let context = ContextSlot::new(key, value);
self.resume_mounted(resume, Some(&context))
}
#[inline]
fn resume_mounted(&mut self, resume: Resume, context: Option<&ContextSlot<'_>>) -> FiberState {
// Reject the transition before a panic hook can observe a stale mount.
assert!(!self.is_complete(), "a completed fiber cannot be resumed");
let execution = self
.execution
.as_mut()
.expect("a completed fiber cannot be resumed");
let _mount = MountGuard::install(execution.core_ptr(), context);
execution.resume(resume)
}
/// Returns whether the entry function has completed.
pub fn is_complete(&self) -> bool {
self.execution
.as_ref()
.is_none_or(|execution| execution.is_complete())
}
/// Reclaims the stack after completion so it can be reused.
///
/// Panics if incomplete; suspended frames unwind on their fiber, while an
/// unstarted entry is reclaimed on the caller's stack.
pub fn into_stack(mut self) -> MappedStack {
// Keep ownership here on failure so Drop selects the correct reclamation context.
assert!(
self.is_complete(),
"an incomplete fiber cannot be extracted"
);
self.execution
.take()
.expect("fiber stack already extracted")
.into_stack()
}
}
impl Drop for Fiber {
fn drop(&mut self) {
if let Some(execution) = self.execution.take() {
// An unstarted entry is dropped on the caller's stack. Its destructors
// must retain that caller's suspension context, if any.
let _mount = execution
.is_suspended()
.then(|| CoreMount::install(execution.core_ptr()));
drop(execution);
}
}
}
#[cfg(test)]
#[path = "fiber_test.rs"]
mod fiber_test;
#[cfg(test)]
#[path = "fiber_drop_test.rs"]
mod fiber_drop_test;