Crate nb

Minimal and reusable non-blocking I/O layer

The ultimate goal of this crate is code reuse. With this crate you can write core I/O APIs that can then be adapted to operate in either blocking or non-blocking manner. Furthermore those APIs are not tied to a particular asynchronous model and can be adapted to work with the futures model or with the async / await model.

Core idea

The WouldBlock error variant signals that the operation can't be completed right now and would need to block to complete. WouldBlock is a special error in the sense that's not fatal; the operation can still be completed by retrying again later.

nb::Result is based on the API of std::io::Result, which has a WouldBlock variant in its ErrorKind.

We can map WouldBlock to different blocking and non-blocking models:

• In blocking mode: WouldBlock means try again right now (i.e. busy wait)
• In futures mode: WouldBlock means Async::NotReady
• In await mode: WouldBlock means yield (suspend the generator)

How to use this crate

Application specific errors can be put inside the Other variant in the nb::Error enum.

So in your API instead of returning Result<T, MyError> return nb::Result<T, MyError>

enum MyError {
    ThisError,
    ThatError,
    // ..
}

// This is a blocking function, so it returns a normal `Result`
fn before() -> Result<(), MyError> {
    // ..
}

// This is now a potentially (read: *non*) blocking function so it returns `nb::Result`
// instead of blocking
fn after() -> nb::Result<(), MyError> {
    // ..
}

You can use the never type (!) to signal that some API has no fatal errors but may block:

#![feature(never_type)]

// This returns `Ok(())` or `Err(nb::Error::WouldBlock)`
fn maybe_blocking_api() -> nb::Result<(), !> {
    // ..
}

Once your API uses nb::Result you can leverage the block!, try_nb! and await! macros to adapt it for blocking operation, or for non-blocking operation with futures or await.

NOTE Currently, both try_nb! and await! are feature gated behind the unstable Cargo feature.

Examples

A Core I/O API

Imagine the code (crate) below represents a Hardware Abstraction Layer for some microcontroller (or microcontroller family).

In this and the following examples let's assume for simplicity that peripherals are treated as global singletons and that no preemption is possible (i.e. interrupts are disabled).

#![feature(never_type)]

// This is the `hal` crate
// Note that it doesn't depend on the `futures` crate

extern crate nb;

/// An LED
pub struct Led;

impl Led {
    pub fn off(&self) {
        // ..
    }
    pub fn on(&self) {
        // ..
    }
}

/// Serial interface
pub struct Serial;
pub enum Error {
    Overrun,
    // ..
}

impl Serial {
    /// Reads a single byte from the serial interface
    pub fn read(&self) -> nb::Result<u8, Error> {
        // ..
    }

    /// Writes a single byte to the serial interface
    pub fn write(&self, byte: u8) -> nb::Result<(), Error> {
        // ..
    }
}

/// A timer used for timeouts
pub struct Timer;

impl Timer {
    /// Waits until the timer times out
    pub fn wait(&self) -> nb::Result<(), !> {
        //^ NOTE the `!` indicates that this operation can block but has no
        //  other form of error

        // ..
    }
}

Blocking mode

Turn on an LED for one second and then loops back serial data.

#[macro_use(block)]
extern crate nb;

use hal::{Led, Serial, Timer};

fn main() {
    // Turn the LED on for one second
    Led.on();
    block!(Timer.wait()).unwrap(); // NOTE(unwrap) E = !
    Led.off();

    // Serial interface loopback
    loop {
        let byte = block!(Serial.read()).unwrap();
        block!(Serial.write(byte)).unwrap();
    }
}

futures

Blinks an LED every second and loops back serial data. Both tasks run concurrently.

#![feature(conservative_impl_trait)]
#![feature(never_type)]

extern crate futures;
#[macro_use(try_nb)]
extern crate nb;

use futures::{Async, Future};
use futures::future::{self, Loop};
use hal::{Error, Led, Serial, Timer};

/// `futures` version of `Timer.wait`
///
/// This returns a future that must be polled to completion
fn wait() -> impl Future<Item = (), Error = !> {
    future::poll_fn(|| {
        Ok(Async::Ready(try_nb!(Timer.wait())))
    })
}

/// `futures` version of `Serial.read`
///
/// This returns a future that must be polled to completion
fn read() -> impl Future<Item = u8, Error = Error> {
    future::poll_fn(|| {
        Ok(Async::Ready(try_nb!(Serial.read())))
    })
}

/// `futures` version of `Serial.write`
///
/// This returns a future that must be polled to completion
fn write(byte: u8) -> impl Future<Item = (), Error = Error> {
    future::poll_fn(move || {
        Ok(Async::Ready(try_nb!(Serial.write(byte))))
    })
}

fn main() {
    // Tasks
    let mut blinky = future::loop_fn::<_, (), _, _>(true, |state| {
        wait().map(move |_| {
            if state {
                Led.on();
            } else {
                Led.off();
            }

            Loop::Continue(!state)
        })
    });

    let mut loopback = future::loop_fn::<_, (), _, _>((), |_| {
        read().and_then(|byte| {
            write(byte)
        }).map(|_| {
            Loop::Continue(())
        })
    });

    // Event loop
    loop {
        blinky.poll().unwrap(); // NOTE(unwrap) E = !
        loopback.poll().unwrap();
    }
}

await!

This is equivalent to the futures example but with much less boilerplate.

#![feature(generator_trait)]
#![feature(generators)]
#![feature(never_type)]

#[macro_use(await)]
extern crate nb;

use std::ops::Generator;

use hal::{Led, Serial, Timer};

fn main() {
    // Tasks
    let mut blinky = || {
        let mut state = false;
        loop {
            // `await!` means suspend / yield instead of blocking
            await!(Timer.wait()).unwrap(); // NOTE(unwrap) E = !

            state = !state;

            if state {
                 Led.on();
            } else {
                 Led.off();
            }
        }
    };

    let mut loopback = || {
        loop {
            let byte = await!(Serial.read()).unwrap();
            await!(Serial.write(byte)).unwrap();
        }
    };

    // Event loop
    loop {
        blinky.resume();
        loopback.resume();
    }
}

Macros

await	Await operation (won't work until the language gains support for generators)
block	Turns the non-blocking expression $e into a blocking operation.
try_nb	Future adapter

Enums

Error

A non-blocking error

Type Definitions

Result

A non-blocking result