vthread
Carrier-affine virtual threads for Rust.
Write ordinary Rust functions with structured ownership, bounded resources, and explicit suspension points. The public runtime crate forbids unsafe Rust.
Supported targets are Linux x86_64 and macOS ARM64, with Rust 1.96 or newer and
panic = "unwind". Builds with panic = "abort" are rejected.
See release notes
for verification coverage and known limitations.
vthread 0.1.0 is production ready within the documented supported workloads and
platforms, with a deliberately limited feature set. Public APIs and supported
contracts remain compatible throughout 0.1.x; breaking changes require 0.2.
A first task
Add vthread to your project:
[]
= "=0.1.0"
Runtime contract
- A started task stays on its carrier thread for its lifetime.
- Scopes own their children. Dropping a handle never detaches work.
- Admission, queues, stacks, timers, wake permits, native work, and channels have explicit bounds.
- Every parked or yielded task has an observable reason. Each park generation selects one winner; timers and remote wakes carry the generation they target.
- An operation that reaches a suspension boundary returns
Error::SuspensionDuringPanicinstead of switching tasks while its carrier is handling a panic.
The runtime includes cancellation, deadlines, virtual synchronization, bounded channels, readiness networking, native blocking delegation, diagnostics, and controlled shutdown.
Standard-library blocking calls are not automatically virtualized. Use vthread operations or
blocking::run when work may block an OS thread. Cancellation is cooperative and cannot
preempt arbitrary Rust code, native calls, or destructors.
Runtime evidence
Enable runtime-evidence and set a positive Runtime::builder().evidence_capacity(...) to
record a bounded, typed event stream. Recording is disabled without that explicit capacity.
- Events cover owned root scopes and supervisors, task and wait lifecycles, wake origins, stacks, timers, queues, and shutdown. Borrowed local scopes share their containing owned scope.
- A single consumer can wait for a bounded batch without polling. This blocking wait belongs on an ordinary OS or monitoring thread; loss counters report full or disconnected buffers.
- The
qualificationfeature adds wake probes bound to one exact wait identity and generation for stale-wake testing.