Skip to main content

Crate randomio

Crate randomio 

Source
Expand description

§randomio

Async random-access I/O capability traits for Rust.

Think of this crate as:

  • std::io::Write → sequential writes
  • tokio::io::AsyncWrite → async sequential writes
  • randomio::AsyncRandomWrite → async offset writes

If your device can read or write bytes at arbitrary offsets (files, block devices, object stores, io_uring, network storage), this crate defines the minimal traits to express that capability.

§Why randomio?

Rust currently provides:

  • sequential I/O (Read / Write)
  • async sequential I/O (AsyncRead / AsyncWrite)

But there is no standard abstraction for random-access async I/O.

Libraries end up inventing incompatible write_at APIs.

randomio fills that gap with:

  • zero-cost traits
  • poll-based primitives
  • no allocation
  • no runtime coupling
  • no policy

This crate only describes what a backend CAN do. Higher layers decide how it SHOULD be used.

§Design Principles

  • Capability, not policy
  • Zero buffering
  • Zero scheduling
  • Zero allocation
  • Runtime-agnostic
  • no_std compatible

If you need buffering, batching, WAL, durability tracking, or sinks/streams, build them in higher-level crates (e.g. randomio-sink).

§Core Types

  • Range — half-open byte interval [start, end)
  • Block — buffer associated with a fixed offset

§Core Traits

These traits intentionally use poll-style APIs to avoid allocations and async_trait overhead.

§Example

ⓘ
use randomio::AsyncRandomWrite;
use std::{pin::Pin, task::{Context, Poll}};

fn write_block<W: AsyncRandomWrite>(
    writer: Pin<&mut W>,
    cx: &mut Context<'_>,
) -> Poll<std::io::Result<()>> {
    writer.poll_write_at(cx, 4096, b"data")
}

§Non-Goals

This crate will never include:

  • buffering
  • batching
  • ordering guarantees
  • durability semantics beyond OS
  • runtimes
  • adapters
  • async fn wrappers

Keeping this crate minimal ensures a stable, forever-frozen core.

§Stability

Starting from 1.0, the core traits and structs are intended to be permanently stable. Only additive APIs will be introduced.

randomio is designed to be the foundational layer other crates build upon.

Modules§

io
I/O re-export for std environments. Traits, helpers, and type definitions for core I/O functionality.

Structs§

Block
Re-export core types. Data block at a specific offset
Range
Half-open byte interval [start, end)

Traits§

AsyncRandomRead
Re-export core traits. Optional read capability for asynchronous random-read I/O
AsyncRandomWrite
Re-export core traits. Core write capability for asynchronous random-write I/O