Crate aiur

Single thread executor library for building async runtimes.

Note: as for now it is more a research project rather then production ready library.

The async/await machinery in Rust compiler in a nutshell provides a transformation of a synchronous looking code into the struct that impls std::future::Future and then user need a library to run such future (or “poll the future to completion”). Popular async runtime libraries are tokio, async-std, smol.

The library that runs the future (usually with something called block_on() function) can have two distinct parts in its API:

• executor - something that organizes the futures from user into a set of tasks for execution (like spawn(), JoinHandle)

• reactor - schedule I/O using OS API (epoll, io_uring, completion port) and be able awake a task when certain I/O event occurs.

This library implements the executor part of the async runtime. Suppose I would like to create async runtime named Mega. I can do it using the aiur crate:

1. Create a crate mega_runtime that depends aiur
2. Implement aiur::Reactor in MegaReactor and API to schedule I/O
3. Now I can have a type MegaRuntime = aiur::Runtime<MegaReactor>, which is now a complete runtime with both executor and reactor.
4. Apps are using MegaRuntime not knowing anything that there is some aiur used under the hood.

As aiur does not have anything OS-specific, it can be used on any OS with std. For testing purposes it has toy reactor that only supports async sleeping.

Major distinction from popular libraries that aiur only provides a single thread executor. It seems to be a lager topic and can be discussed later.

There other ideas where ongoing research happens:

• structured concurrency
• async destruction
• nostd

Modules

toy_rt

Macros

export_runtime

This is a help macro to create API for your own runtime based on re-exporting aiur runtime and specialize it with your reactor.

join

Waits concurrently until all futures are completed.

join_tasks

Waits concurrently until all futures are completed as tasks.

make_any_of

Creates AnyOfN stream from supplied futures.

pin_local

Pins the stack variable.

pinned_any_of

Makes a pinned version of AnyOfN stream.

Structs

AnyOfN

Stream to poll several futures concurrently.

EventId

EventId is a reactor’s id for the event that was awoken.

EventNode

Data structure required to schedule IO in reactor. In order to schedule any event in reactor the EventId is required and the only way to create EventId is to create it from this structure.

Recver

The receiving half of the channel created by channel() function.

RecverOnce

The receiving half of the oneshot channel created by oneshot() function.

Runtime

The owner of the reactor (I/O event queue) and executor (task management) data structures.

Sender

The sending half of the channel created by channel() function.

SenderOnce

The sending half of the oneshot channel created by oneshot() function.

ToyReactor

ToyReactor is reactor that can only schedule timers.

Tracer

A C-like callback which is a pointer to logger function and data.

Enums

OneOf2

Used as result of AnyOfN::next() for two futures.

OneOf3

Used as result of AnyOfN::next() for three futures.

OneOf4

Used as result of AnyOfN::next() for four futures.

OneOf5

Used as result of AnyOfN::next() for five futures.

OneOf6

Used as result of AnyOfN::next() for six futures.

OneOf7

Used as result of AnyOfN::next() for seven futures.

OneOf8

Used as result of AnyOfN::next() for eight futures.

Traits

LifetimeLinkerFn

A helper trait to solve the lifetime problem for with_runtime().

Reactor

Reactor API for Executor.

TemporalReactor

Reactor with a very basic timers.

Functions

any_of2

Creates the AnyOfN stream to poll two futures.

any_of3

Creates the AnyOfN stream to poll three futures.

any_of4

Creates the AnyOfN stream to poll four futures.

any_of5

Creates the AnyOfN stream to poll five futures.

any_of6

Creates the AnyOfN stream to poll six futures.

any_of7

Creates the AnyOfN stream to poll seven futures.

any_of8

Creates the AnyOfN stream to poll eigth futures.

channel

Creates a new asynchronous channel returning the pair of (Sender, Receiver).

join2

Polls two futures concurrently until both are completed.

join3

Polls three futures concurrently until all are completed.

join4

Polls four futures concurrently until all are completed.

join5

Polls five futures concurrently until all are completed.

join6

Polls six futures concurrently until all are completed.

join7

Polls seven futures concurrently until all are completed.

join8

Polls eight futures concurrently until all are completed.

join_tasks2

Polls two futures concurrently as tasks until both are completed.

join_tasks3

Polls three futures concurrently as tasks until both are completed.

join_tasks4

Polls four futures concurrently as tasks until both are completed.

join_tasks5

Polls five futures concurrently as tasks until both are completed.

join_tasks6

Polls six futures concurrently as tasks until both are completed.

join_tasks7

Polls seven futures concurrently as tasks until both are completed.

join_tasks8

Polls eight futures concurrently as tasks until both are completed.

oneshot

Creates a new oneshot channel and returns the pair of (sender, receiver).

sleep

Performs the async sleep.

with_runtime_base

This is how you run an async function with aiur.