Skip to main content

Crate nezuko

Crate nezuko 

Source
Expand description

A small async runtime you can read in an afternoon.

Writing async fn in Rust does not actually run anything. It builds a value called a future: a paused piece of work that knows how to make a little progress every time someone asks it to. Something has to do the asking, keep track of the work that is still waiting, and wake it back up at the right moment. That something is a runtime, and nezuko is a very small one.

You give it work with spawn, you wait for the result, and it takes care of running everything at the same time on a handful of threads.

§Quick start

use nezuko::{Runtime, sleep, spawn};
use std::time::Duration;

let rt = Runtime::new().unwrap();

rt.block_on(async {
    // Both tasks start right away and nap at the same time,
    // so this whole block takes ~50ms, not ~100ms.
    let a = spawn(async {
        sleep(Duration::from_millis(50)).await;
        "hello"
    });
    let b = spawn(async {
        sleep(Duration::from_millis(50)).await;
        "world"
    });

    println!("{} {}", a.await, b.await);
});

§What’s in the box

§A TCP server

The networking helpers work on the standard library’s own socket types - there is no nezuko::TcpStream. You do have to call set_nonblocking(true) yourself: that is what makes the OS answer “not ready yet” instead of parking the thread, and “not ready yet” is the moment nezuko takes over and goes to run something else.

use nezuko::{Runtime, accept, spawn, write_all};
use std::net::TcpListener;

let rt = Runtime::new().unwrap();

rt.block_on(async {
    let mut listener = TcpListener::bind("127.0.0.1:8080").unwrap();
    listener.set_nonblocking(true).unwrap();

    loop {
        let (mut socket, _addr) = accept(&mut listener).await.unwrap();
        // One task per connection, so the loop is free to take the next one.
        spawn(async move {
            write_all(b"hello\n", &mut socket).await.unwrap();
        });
    }
});

§How it fits together

A map for anyone reading the source. Follow the modules in this order:

moduleits job
taskone unit of work, plus the queue of work that is ready to run
runtimethe public entry point, the worker threads, and the shared state
reactorone thread that watches sockets and timers, and wakes tasks
wakeupthe pipe used to interrupt the reactor when something changes
timesleep, built on the reactor’s timer list
netasync TCP helpers, built on the reactor’s socket watching
channela one-shot channel used to get block_on’s result back

The short version of the loop: a task is pushed onto the ready queue, a worker thread pops it and polls it, and the task either finishes or says “not yet” and leaves behind a waker - a callback that pushes it back onto the queue. The reactor is what calls that waker once the socket is readable or the timer is up.

Structs§

Runtime
The async runtime: create one, then hand it work with block_on.

Functions§

accept
Wait for someone to connect, without blocking the thread.
print_all
Read from stream and print it to stdout until the other side hangs up.
sleep
Pause the current task for duration, letting other tasks run meanwhile.
spawn
Start future running in the background, right now.
write_all
Send every byte of buf down stream.

Type Aliases§

Result
Result with Error already filled in, so you can write nezuko::Result<T> instead of the long form.