Crate aiur

Expand description

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:

Create a crate mega_runtime that depends aiur
Implement aiur::Reactor in MegaReactor and API to schedule I/O
Now I can have a type MegaRuntime = aiur::Runtime<MegaReactor>, which is now a complete runtime with both executor and reactor.
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

Re-exports§

pub use toy_rt::ToyReactor;

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.
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.

Crate aiurCopy item path