Skip to main content

vthread_stack/
lib.rs

1//! Private, unsupported stack backend for `vthread`; not an independent public API.
2//!
3//! Direct downstream use has no compatibility contract. Cleanup mount callbacks are
4//! runtime integration hooks and must succeed. A persistent mount failure during lexical
5//! scope exit aborts: borrowed executable stacks cannot safely escape their environment.
6//!
7//! Layers, lowest first:
8//!
9//! - `stack_unix` and `stack`: guard-page-backed mappings stamped with a pool identity.
10//! - `arch`: per-target context switch and first-frame fabrication, nothing more.
11//! - `entry` and `context`: the entry closure and control block at the top of each
12//!   stack, and the command and outcome protocol between a carrier and its fiber.
13//! - `engine`: the fiber lifecycle state machine, including forced reclamation.
14//! - `mount`, `fiber`, `lease`, `scoped`, and `pool`: the carrier-facing ownership
15//!   model the scheduler consumes.
16
17#![deny(unsafe_op_in_unsafe_fn)]
18
19#[cfg(panic = "abort")]
20const _: () = {
21    compile_error!("vthread-stack requires panic=unwind");
22};
23
24#[cfg(not(any(
25    all(target_os = "linux", target_arch = "x86_64"),
26    all(target_os = "macos", target_arch = "aarch64"),
27)))]
28const _: () = {
29    compile_error!("vthread-stack supports Linux x86_64 and macOS ARM64");
30};
31
32mod arch;
33mod context;
34mod engine;
35mod entry;
36mod fiber;
37mod lease;
38mod mount;
39#[doc(hidden)]
40pub mod panic_payload;
41mod pool;
42mod scoped;
43mod stack;
44mod stack_unix;
45mod suspension;
46
47pub use fiber::Fiber;
48pub use lease::FiberLease;
49pub use mount::suspend;
50#[doc(hidden)]
51pub use mount::{ContextKey, check_suspend};
52pub use pool::{StackPool, StackPoolSnapshot};
53pub use scoped::{FiberScope, fiber_scope};
54pub use stack::{MappedStack, STACK_ALIGNMENT};
55pub use suspension::{FiberState, ParkRequest, ParkToken, Resume, SuspendError, Suspension};
56
57#[cfg(test)]
58#[path = "lib_test.rs"]
59mod lib_test;
60#[cfg(test)]
61#[path = "terminal_test.rs"]
62mod terminal_test;
63#[cfg(test)]
64#[path = "trace_test.rs"]
65mod trace_test;