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.

Copyright (c) 2025 Al Liu.