Expand description
Carrier-affine virtual threads with explicit suspension boundaries.
fn main() -> vthread::Result<()> {
vthread::run(|scope| {
let mut answer = scope.spawn("answer", || 52)?;
println!("{}", answer.join()?);
Ok(())
})
}Re-exports§
Modules§
- blocking
- Explicit delegation of owned native work to a bounded runtime worker pool.
- channel
- Bounded MPMC channels with FIFO send/receive waits and explicit disconnection.
- diagnostics
- Runtime and stack-pool diagnostics.
- error
- Public runtime errors and panic reports.
- fs
- Owned filesystem requests delegated to the bounded native pool.
- lifecycle
- Explicit runtime and supervisor shutdown ownership and reports.
- net
- Explicit nonblocking socket I/O backed by zio readiness waits.
- parking
- Public one-permit parking and wake handles.
- sync
- Bounded synchronization that parks virtual threads instead of their carriers.
Structs§
- Cancellation
Token - A cooperative cancellation request, inherited by child scopes.
- Join
Handle - A typed result handle whose completion follows carrier-side stack reclamation.
- Local
Join Handle - A non-Send borrowed child’s result, usable only inside its local scope.
- Local
Scope - A lexical owner of borrowed, non-Send children on the current carrier.
- Runtime
- An application lifecycle owner with one active root scope and persistent affine carriers.
Explicit supervisors may coexist with that root; independent roots use separate runtimes.
Task groups and supervisors share this runtime’s workers, rather than creating new ones.
Each runtime owns
carriers + blocking_threads + 2OS threads (five by default), plus one process-shared lifecycle owner. SeeRuntimeBuilderfor thread/stack costs andcrate::lifecycle::LIFECYCLE_CAPACITYfor the fixed process admission bound. - Runtime
Builder - Builder for a bounded multicarrier runtime.
- Runtime
Config - Immutable runtime configuration.
- Scope
- A lexical owner for transferable tasks dispatched to persistent carriers.
- Scope
Options - Optional policy for a root scope or supervisor.
- Spawn
Options - Optional policy for one child; omitted policy inherits its owner and spawning task.
- Spawner
- A cloneable, Send + Sync capability to spawn children of one scope or supervisor.
- Task
Local - A typed, lazily initialized virtual-thread-local value.
Enums§
- Stall
Policy - Response to a timerless, entirely parked root scope while an OS owner waits. External wake ownership cannot be inferred from quiescence. Disabled is the safe default.
Functions§
- cancellation_
token - Returns the current task’s inherited cancellation token.
- checkpoint
- Checks inherited cancellation and the earliest deadline at a cooperative boundary.
- deadline
- Returns the current task’s earliest inherited deadline.
- local_
scope - Runs borrowed work on the current carrier, reclaiming all children before returning. ScopeFailure preserves the body, inherited policy, cleanup and representative child failure with additional counts. Representative order matches run_scope: body, policy, cleanup, then child. A body panic is rethrown unchanged after retaining scope diagnostics.
- local_
scope_ with_ deadline - Adds a local deadline; it cannot extend an inherited parent deadline.
- run
- Runs one structured scope and explicitly shuts down its default runtime.
Returns a shutdown error even when the scope succeeds. If both fail,
error::RunFailurepreserves both causes inError::RunFailed. - sleep
- Parks the current virtual thread for at least
duration. - sleep_
until - Parks the current virtual thread until a monotonic deadline.
- try_
local_ scope - Runs borrowed children with an application-specific, caller-owned body error. Body failure cancels and reclaims children before returning; diagnostics never retain or format the application error.
- try_
local_ scope_ with_ deadline - Adds a local deadline to a generic-error scope without extending its parent deadline.
- try_run
- Runs an application-error scope and explicitly shuts down its default runtime.
- yield_
now - Cooperatively yields the current virtual thread to the carrier scheduler.
Runtime policy is checked before the yield commits and again immediately before resumption.
Returns
Error::SuspensionDuringPanicwithout switching tasks while the carrier is running a panic hook or unwinding a panic.