Crate nuclei 

Nuclei

A proactive async runtime: thread-per-core shards that run tasks and drive their own IO, timers and buffers. Every operation is completed for the task that asked for it; no task waits for readiness and then makes the call itself. IO runs on io_uring on Linux where the kernel allows it, else on epoll; on kqueue on macOS and the BSDs; and on I/O completion ports on Windows.

spawn, block_on and the rest place work on the process default Runtime, which starts on first use with no configuration; a Builder sets every setting for a runtime of one’s own.

What is where

• runtime: runtimes, their builder and handles, block_on, tasks placed on a worker one names (RuntimeHandle::spawn_on_worker, RuntimeHandle::on_each_worker) and values kept per worker (shard_local!).
• task: spawning, JoinSet, abort handles, ids and names, task-local values and yielding.
• net: TCP, UDP and Unix sockets, names, socket options and builders, stream halves, shut and abort, and pipes.
• io: Handle, async operations on std’s own IO objects, and the helpers every stream gets: reads and writes as futures, copies, buffers, in-memory pipes, the standard streams and readiness; and the buffers the owned calls lend the driver (io::IoBuf, io::AlignedBuf, io::IoVecBuf).
• fs: files, whole-file calls, metadata and directories; IO at an offset, direct IO, syncs, the space calls and advisory locks.
• time: sleeps on a millisecond wheel or to the microsecond, timeouts, intervals and a clock tests can pause.
• sync: locks, semaphores, notifications, once-cells, channels and cancellation tokens, for any executor; sync::local, their cheaper twins for the tasks of one shard; and sync::mesh, channels between every pair of a set of parties.
• process and signal: child processes, signals and console events.
• stats(): a snapshot of what every shard is doing, with poll times when recorded and, with the io-stats feature, its IO counts and latencies.
• select!, join! and try_join! wait on several futures in one task; #[nuclei::main], #[nuclei::test] and #[nuclei::bench] run an async function in the runtime.

A call that needs the default runtime or the calling thread’s shard panics if that cannot start (the system refused its poller: no descriptors or memory left); Builder::build and task::Builder answer the error instead. Builder::build also checks every setting first, and answers one out of range as InvalidInput naming it.

The guide, a path from the first program to production with an example that runs for every idea, is at https://nuclei.rs/learn/.

use nuclei::net::TcpListener;

#[nuclei::main]
async fn main() -> std::io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:7000").await?;
    loop {
        let (stream, _) = listener.accept().await?;
        nuclei::spawn(async move {
            let mut buf = [0u8; 1024];
            while let Ok(n @ 1..) = stream.recv(&mut buf).await {
                if stream.send(&buf[..n]).await.is_err() {
                    break;
                }
            }
        })
        .detach();
    }
}

Re-exports

pub use io::Handle;

pub use io::IoObject;

pub use net::TcpStreamGenerator;

pub use runtime::Builder;

pub use runtime::FallibleTask;

pub use runtime::Runtime;

pub use runtime::RuntimeHandle;

pub use runtime::Task;

pub use runtime::block_on;

pub use runtime::spawn;

pub use runtime::spawn_blocking;

pub use runtime::spawn_local;

pub use stats::stats;

pub use time::sleep;

pub use time::timeout;

Modules

config

The proactor’s configuration: the io_uring settings of every shard and the default backend.

fs

The file system: files as File (std’s file in a Handle), OpenOptions, the calls by path (read, write, metadata, rename, copy, …), directories (create_dir_all, DirBuilder, read_dir streamed a page at a time) and links. Calls by path, and a regular file’s calls beside its reads, writes, syncs and Handle::allocate, run on the blocking pool; Handle::try_lock_file, which never waits, runs on the calling thread, and so does File::open on Linux for a regular file on a local file system whose path the kernel’s caches resolve at once.

io

IO: Handle (async operations on std’s sockets and files), the futures-io traits, and the utilities every stream gets: the reads and writes of AsyncReadExt, AsyncWriteExt, AsyncBufReadExt and AsyncSeekExt as futures, ReadBuf, copy and copy_bidirectional, BufReader, BufWriter and BufStream, the in-memory pipes duplex and simplex, split, empty, repeat and sink, the process’s stdin, stdout and stderr, what the sockets’ readiness calls take and answer (Interest, Ready), the caller’s own buffers the owned calls take and give back (IoBuf, IoBufMut, IoVecBuf, IoVecBufMut, AlignedBuf), and on unix AsyncFd, a caller’s own descriptor driven by readiness.

net

Sockets: TCP, UDP and Unix domain, as Handles.

process

Child processes: spawn one, wait for its exit and talk to it through async pipes. Child processes: a Command spawns one, and its Child waits for the exit without holding a thread and talks to it through async pipes.

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.

signal

Signals (unix) and console control events (Windows), as streams. Signals: a stream of the deliveries of one signal (unix) or console control event (Windows), and ctrl_c.

stats

What the runtime is doing: a snapshot of every shard’s counters, taken by stats(), or of one runtime’s by Runtime::stats. A runtime built with Builder::record_latencies adds a Histogram of its poll times, and with the io-stats feature each worker’s IO counts and latencies.

sync

Runtime-independent synchronization primitives: futures and wakers only, usable from any executor. Nuclei’s runtime-independent synchronization primitives: locks, a semaphore, events, a barrier, once-cells and channels that never block a thread.

task

Tasks: spawning, their handles and ids, cancellation from anywhere, and yielding. Tasks: spawning (named, or on a worker the caller names, or neither), their handles and ids, cancellation from anywhere, and yielding to the other tasks of the shard.

time

Time: sleeping, timeouts and intervals on the shard’s timer wheel. Time: sleeping, timeouts and intervals, on the timer wheel of the shard that polls them, and the runtime’s clock they read.

Macros

join

Waits on every future given, all at once, and gives their outputs as a tuple in the order written.

select

Waits on several branches at once and runs the handler of the first to finish, dropping the others.

shard_local

Declares shard-local statics, each a ShardLocal made with the expression given on its first use on each worker.

task_local

Declares task-local keys, each a LocalKey.

try_join

Waits on every future given, all at once, each giving a Result with the same error type, and gives Ok with their outputs as a tuple in the order written, or the first error.

Structs

GlobalExecutorConfig

How the process default runtime is set up by init_with_config.

Proactor

The process’s proactor: its configuration, and the IO of the calling thread’s shard.

Enums

IoBackend

Which kernel interface nuclei’s IO runs on.

Functions

drive

Runs future to its end on the calling thread, driving its shard’s IO meanwhile: block_on.

init

Starts the process default runtime now, with every setting at its default, unless it is running already.

init_with_config

Starts the process default runtime now, as config says, unless it is running already (then config is not used).

spawn_more_threads

Starts up to count more workers on the runtime this thread is inside (or the default one), within its maximum; returns how many started.

stop_current_thread

Stops the worker this task runs on, as stop_thread stops one: false on a thread that is not a worker of its runtime, or when only the minimum runs.

stop_thread

Stops one worker of the runtime this thread is inside (or the default one), unless only the runtime’s minimum runs: it takes no new task from now on and exits once the tasks it has are done. The task completes with whether a worker was stopped, once it takes no new task.

Attribute Macros

bench

Enables an async benchmark function.

main

Enables an async main function.

test

Enables an async test function.