Crate agnostic_lite

Expand description

Agnostic-Lite

agnostic-lite is an agnostic abstraction layer for any async runtime.

In order to make it trivial for others to build implementations of any async runtime, this crate provides an abstraction layer implementation.

In addition, this crate is not only no_std, but also alloc-free. This means that it can be used in environments where alloc is not available, such as embedded systems. It also has no unsafe code.

LoC

§Introduction

agnostic-lite is a lightweight, no_std-compatible, allocation-free abstraction layer for async runtimes. It provides the essential async primitives you need to write runtime-agnostic code that works in any environment - from standard applications to embedded systems.

§Key Features

no_std Compatible: Works without the standard library
Allocation-Free: No heap allocations required
No Unsafe Code: #![forbid(unsafe_code)] ensures memory safety
Modular Traits: Small, focused traits instead of one monolithic Runtime trait
Zero-Cost: Compiles to runtime-specific code
WASM Support: Works in WebAssembly environments

§Core Traits

agnostic-lite provides focused traits for specific async operations:

AsyncSpawner: Spawn tasks globally
AsyncLocalSpawner: Spawn thread-local tasks
AsyncSleep: Sleep for a duration
AsyncInterval: Create periodic intervals
AsyncTimeout: Apply timeouts to operations
RuntimeLite: Combines all traits for convenience
Yielder: Yield control back to the runtime

§Supported Runtimes

tokio - Enable with features = ["tokio"]
smol - Enable with features = ["smol"]
wasm-bindgen-futures - Enable with features = ["wasm"]

§Why agnostic-lite?

Choose agnostic-lite over agnostic when:

✅ You need no_std support for embedded systems
✅ You want minimal dependencies and compile times
✅ You only need basic async primitives (spawning, time)
✅ You’re building a library and want minimal footprint
✅ You need guaranteed memory safety (no unsafe code)

Choose agnostic when:

You need networking, DNS, or process management
You’re building standard applications with std
You want a batteries-included experience

§Installation

[dependencies]
agnostic-lite = "0.6"

§Runtime Selection

Choose one runtime feature:

# With tokio
agnostic-lite = { version = "0.6", features = ["tokio"] }

# With smol
agnostic-lite = { version = "0.6", features = ["smol"] }

# With WASM
agnostic-lite = { version = "0.6", features = ["wasm"] }

§no_std Usage

# Disable default features for no_std
agnostic-lite = { version = "0.6", default-features = false, features = ["tokio"] }

§Feature Flags

§Core Features

std (default): Standard library support
alloc: Allocation support (without std)
time: Time-related traits and types

§Runtime Features (choose one)

tokio: Tokio runtime implementations
async-io: async-io backend (used by smol)
smol: Smol runtime implementations
wasm: WebAssembly support via wasm-bindgen-futures

§Trait Reference

§AsyncSpawner

pub trait AsyncSpawner {
    type JoinHandle<T>: Future<Output = Result<T, JoinError>>;

    fn spawn<F, T>(future: F) -> Self::JoinHandle<T>
    where
        F: Future<Output = T> + Send + 'static,
        T: Send + 'static;
}

§AsyncLocalSpawner

pub trait AsyncLocalSpawner {
    type JoinHandle<T>: Future<Output = Result<T, JoinError>>;

    fn spawn_local<F, T>(future: F) -> Self::JoinHandle<T>
    where
        F: Future<Output = T> + 'static,
        T: 'static;
}

§AsyncSleep

pub trait AsyncSleep {
    type Sleep: Future<Output = ()>;

    fn sleep(duration: Duration) -> Self::Sleep;
}

§AsyncInterval

pub trait AsyncInterval {
    type Interval: Stream<Item = Instant>;

    fn interval(period: Duration) -> Self::Interval;
}

§AsyncTimeout

pub trait AsyncTimeout {
    fn timeout<F, T>(duration: Duration, future: F) -> TimeoutFuture<F>
    where
        F: Future<Output = T>;
}

§RuntimeLite

Combines all traits for convenience:

pub trait RuntimeLite:
    AsyncSpawner +
    AsyncLocalSpawner +
    AsyncSleep +
    AsyncInterval +
    AsyncTimeout +
    Yielder
{
    // All trait methods available
}

§Conditional Compilation Helpers

agnostic-lite provides macros for conditional compilation:

use agnostic_lite::{cfg_tokio, cfg_smol};

cfg_tokio! {
    // This code only compiles when tokio feature is enabled
    use tokio::task;
}

cfg_smol! {
    // This code only compiles when smol feature is enabled
    use smol::Task;
}

§Performance

agnostic-lite has zero runtime overhead. All trait methods are inlined and compile to the same code as using the runtime directly:

No allocations: Works without heap allocations
No dynamic dispatch: All trait calls are statically resolved
Zero-cost abstractions: Compiles to identical assembly as direct runtime usage

§License

agnostic-lite is under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Modules§

async_ioasync-io: Time related traits concrete implementations for runtime based on async-io, e.g. smol.
smolsmol: Concrete runtime implementations based on smol runtime.
teststest or test: Unit test for the RuntimeLite
timetime: Time related traits
tokiotokio: Concrete runtime implementations based on tokio runtime.
wasmwasm: Concrete runtime implementations based on wasm-bindgen-futures.

Macros§

cfg_linux: Macro to conditionally compile items for linux system
cfg_smol: Macro to conditionally compile items for smol feature
cfg_tokio: Macro to conditionally compile items for tokio feature
cfg_unix: Macro to conditionally compile items for unix system
cfg_windows: Macro to conditionally compile items for windows system

Enums§

AfterHandleErrortime: Error of AfterHandle’s output

Traits§

AfterHandletime: The handle returned by the AsyncAfterSpawner when a after future is spawned.
AsyncAfterSpawnertime: A spawner trait for spawning futures. Go’s time.AfterFunc equivalent.
AsyncBlockingSpawner: A spawner trait for spawning blocking.
AsyncLocalSpawner: A spawner trait for spawning futures.
AsyncSpawner: A spawner trait for spawning futures.
JoinHandle: Joinhanlde trait
LocalJoinHandle: Joinhanlde trait
RuntimeLite: Runtime trait
Yielder: Yielder hints the runtime to execution back