Skip to main content

Crate vthread

Crate vthread 

Source
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§

pub use error::Error;
pub use error::Result;

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§

CancellationToken
A cooperative cancellation request, inherited by child scopes.
JoinHandle
A typed result handle whose completion follows carrier-side stack reclamation.
LocalJoinHandle
A non-Send borrowed child’s result, usable only inside its local scope.
LocalScope
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 + 2 OS threads (five by default), plus one process-shared lifecycle owner. See RuntimeBuilder for thread/stack costs and crate::lifecycle::LIFECYCLE_CAPACITY for the fixed process admission bound.
RuntimeBuilder
Builder for a bounded multicarrier runtime.
RuntimeConfig
Immutable runtime configuration.
Scope
A lexical owner for transferable tasks dispatched to persistent carriers.
ScopeOptions
Optional policy for a root scope or supervisor.
SpawnOptions
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.
TaskLocal
A typed, lazily initialized virtual-thread-local value.

Enums§

StallPolicy
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::RunFailure preserves both causes in Error::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::SuspensionDuringPanic without switching tasks while the carrier is running a panic hook or unwinding a panic.