Module runtime 

nuclei’s own runtime: shards, tasks, block_on, spawn and the blocking pool. nuclei’s own runtime: thread-per-core shards that run tasks, a blocking pool, and the functions that place work on them.

A Runtime runs one shard per worker thread. A shard owns its run queue, its timers and its poller, and a task stays on the shard it was placed on: spawn keeps it near the spawning thread’s other tasks within a margin of load (see Builder::local_spawn_margin), spawn_local keeps it on the calling thread. block_on runs a future on the calling thread and nests: called from a task, it keeps the shard running its other tasks until the future completes.

RuntimeHandle::spawn_on_worker, RuntimeHandle::on_each_worker and task::Builder::worker place a task on a worker the caller names, where it stays; shard_local! keeps a ShardLocal value per worker, which moves with the worker’s shard when a handoff gives the shard to another thread.

The free functions use the runtime the calling thread is inside, or the process default runtime, which starts on first use with no configuration (one worker per core). Builder sets everything else, and Runtime::stats reads one runtime’s counters.

use nuclei::runtime::{Runtime, spawn};

let runtime = Runtime::builder().worker_threads(2).build().unwrap();
let sum = runtime.block_on(async {
    let tasks: Vec<_> = (0..4u64).map(|n| spawn(async move { n * n })).collect();
    let mut sum = 0;
    for task in tasks {
        sum += task.await;
    }
    sum
});
assert_eq!(sum, 14);

Structs

Builder

Builds a Runtime. Every setting is optional: an unset one takes the default, which needs no configuration to work well.

EnterGuard

The runtime Runtime::enter set on this thread, until it drops: the free functions (spawn, …) use that runtime meanwhile. It stays on the thread that made it.

FallibleTask

A spawned task whose output is None when the task ended without one.

RngSeed

A seed for a runtime’s random choices: where a task spawned from outside its workers goes, and which branch of a fair select! is polled first.

Runtime

A runtime: worker shards and a blocking pool. Dropping it stops the workers, drops the tasks they still hold, and waits for the threads to exit; then, on the dropping thread, for what the handles those tasks held left behind (the bytes a socket’s write-behind holds, a file’s writes) to land, each for at most a minute, so nothing they accepted is lost.

RuntimeHandle

A cloneable handle to a Runtime, to spawn on it from anywhere. It does not keep the runtime running.

RuntimeId

A runtime’s id, distinct among the runtimes of the process.

ShardAccessError

A ShardLocal was used where it has no value: off a worker, or by its own initializer.

ShardLocal

A value per worker shard, declared with shard_local!.

Task

A spawned task.

TaskMeta

What a task hook is told about the task.

TryCurrentError

RuntimeHandle::try_current found no runtime set on this thread.

Enums

UnhandledPanic

What a runtime does when one of its tasks panics (Builder::unhandled_panic).

Functions

block_on

Runs future to its end on the calling thread, running other tasks of the thread’s shard meanwhile.

spawn

Spawns a task on the runtime this thread is inside, or on the default runtime. Spawned on a worker, the task stays on that worker unless it holds more live tasks than another shard by the runtime’s local_spawn_margin; spawned anywhere else, it goes to the spawning thread’s home shard by the same rule (the first spawn takes the less loaded of two shards picked at random). The task stays on its shard.

spawn_blocking

Runs f on the blocking pool of the runtime this thread is inside, or of the default runtime, so it never holds a shard up.

spawn_local

Spawns a task that stays on the calling thread: a worker’s shard, or the thread’s own (where it runs while the thread is inside block_on). The future need not be Send.

worker_index

The index of the worker this code runs on (0, 1, … among the workers of its runtime), None off the workers (in block_on’s own thread, on the blocking pool, outside any runtime).