Crate ringline 

ringline — io_uring-native async I/O runtime for Linux.

ringline is a thread-per-core I/O framework built directly on io_uring. It provides an async/await API (AsyncEventHandler) on a single-threaded executor with no work-stealing.

Quick Start

use ringline::{AsyncEventHandler, Config, ConnCtx, ParseResult, RinglineBuilder};

struct Echo;

impl AsyncEventHandler for Echo {
    fn on_accept(&self, conn: ConnCtx) -> impl std::future::Future<Output = ()> + 'static {
        async move {
            loop {
                let n = conn.with_data(|data| {
                    conn.send_nowait(data).ok();
                    ParseResult::Consumed(data.len())
                }).await;
                if n == 0 { break; }
            }
        }
    }
    fn create_for_worker(_id: usize) -> Self { Echo }
}

fn main() -> Result<(), ringline::Error> {
    let config = Config::default();
    let (_shutdown, handles) = RinglineBuilder::new(config)
        .bind("127.0.0.1:7878".parse().unwrap())
        .launch::<Echo>()?;
    for h in handles { h.join().unwrap()?; }
    Ok(())
}

Platform

Linux 6.0+ only. Requires io_uring with multishot recv, ring-provided buffers, SendMsgZc, and fixed file table support.

Re-exports

pub use handler::ConnToken;

pub use handler::DriverCtx;

pub use handler::SendPart;

pub use handler::UdpToken;

pub use error::TimerExhausted;

pub use error::UdpSendError;

pub use config::Config;

pub use config::ConfigBuilder;

pub use config::RecvBufferConfig;

pub use config::WorkerConfig;

pub use direct_io::DirectIoCompletion;

pub use direct_io::DirectIoConfig;

pub use direct_io::DirectIoFile;

pub use direct_io::DirectIoOp;

pub use error::Error;

pub use guard::GuardBox;

pub use guard::SendGuard;

pub use nvme::NvmeCompletion;

pub use nvme::NvmeConfig;

pub use nvme::NvmeDevice;

Modules

config

direct_io

Direct I/O via io_uring (O_DIRECT + IORING_OP_READ / IORING_OP_WRITE).

error

guard

handler

nvme

NVMe io_uring passthrough types and helpers.

Structs

AsyncSendBuilder

Async scatter-gather send builder. Builder for scatter-gather sends in the async API.

ConnCtx

Async connection context with send/recv futures. The async equivalent of ConnToken + DriverCtx. Passed to the connection’s async fn, provides I/O methods.

ConnectFuture

Future that completes when a connect finishes. Future that awaits an outbound TCP connection. The connect SQE was submitted eagerly by ConnCtx::connect — this future waits for the CQE result.

Deadline

A monotonic clock deadline for absolute timers. A monotonic clock deadline for use with absolute timers.

DiskIoFuture

Future that awaits a disk I/O completion (NVMe or Direct I/O). Future that awaits a disk I/O completion (NVMe or Direct I/O).

Elapsed

Error returned when a timeout() expires. Error returned when a timeout() deadline expires.

Join

Future returned by join(). Future that polls two sub-futures and returns both outputs when complete.

Join3

Future returned by join3(). Future that polls three sub-futures and returns all outputs when complete.

MemoryRegion

Memory region for io_uring fixed buffer registration. A user-registered memory region (e.g., mmap’d storage arena).

RecvReadyFuture

Future that resolves when recv data is available (sink, accumulator, or close). Future returned by ConnCtx::recv_ready. Resolves when:

RegionId

Region identifier for SendGuard implementations. Identifies a registered memory region (index into the iovec array).

RinglineBuilder

Builder for launching ringline workers. Builder for launching ringline workers with optional listener/acceptor.

Select

Future returned by select(). Future that polls two sub-futures and returns whichever completes first. Biased: always polls a before b.

Select3

Future returned by select3(). Future that polls three sub-futures and returns whichever completes first. Biased: polls a, then b, then c.

SendFuture

Future that completes when a send finishes. Future that awaits send completion. The SQE was already submitted eagerly by ConnCtx::send — this future only waits for the CQE result. No data stored in the future. No allocation.

ShutdownHandle

Handle for triggering graceful shutdown. Handle returned by launch() to trigger graceful shutdown of all workers.

SleepFuture

Future returned by sleep(). Future returned by sleep() or sleep_until(). Completes after the configured duration or at the given deadline.

TaskId

Opaque handle for a standalone spawned task. Opaque handle for a standalone task spawned via spawn().

TimeoutFuture

Future returned by timeout(). Future returned by timeout() or timeout_at().

UdpCtx

Async context for a UDP socket. Async context for a UDP socket.

UdpRecvFuture

Future returned by UdpCtx::recv_from(). Future returned by UdpCtx::recv_from().

WithBytesFuture

Future that provides received data as zero-copy Bytes. Future returned by ConnCtx::with_bytes.

WithDataFuture

Future that provides received data. Future returned by ConnCtx::with_data.

Enums

Either

Result of select() — which branch completed. Result of select() — indicates which branch completed first.

Either3

Result of select3() — which branch completed. Result of select3() — indicates which of three branches completed first.

ParseResult

Result of a parse closure: consumed bytes or need more data. Result of a parse closure passed to ConnCtx::with_data or ConnCtx::with_bytes.

Constants

MAX_GUARDS

Maximum zero-copy guards per scatter-gather send.

MAX_IOVECS

Maximum iovecs per scatter-gather send.

Traits

AsyncEventHandler

Trait for async event handlers (one task per connection). Trait for async connection handlers.

Functions

connect

Initiate an outbound TCP connection from any async task. Initiate an outbound TCP connection from any async task (connection or standalone).

connect_with_timeout

Initiate an outbound TCP connection with a timeout from any async task. Initiate an outbound TCP connection with a timeout from any async task.

direct_io_read^⚠

Submit a Direct I/O read and return a future for the result. Submit a Direct I/O read and return a future for the result.

direct_io_write^⚠

Submit a Direct I/O write and return a future for the result. Submit a Direct I/O write and return a future for the result.

join

Poll two futures concurrently, returning both outputs when complete. Poll two futures concurrently, returning both outputs when they complete.

join3

Poll three futures concurrently, returning all outputs when complete. Poll three futures concurrently, returning all outputs when they complete.

nvme_read

Submit an NVMe read and return a future for the result. Submit an NVMe read and return a future for the result.

nvme_write

Submit an NVMe write and return a future for the result. Submit an NVMe write and return a future for the result.

open_direct_io_file

Open a Direct I/O file from any async task. Open a Direct I/O file from any async task.

open_nvme_device

Open an NVMe device from any async task. Open an NVMe device from any async task.

request_shutdown

Request graceful shutdown from any async task. Request graceful shutdown of the worker event loop from any async task.

select

Poll two futures concurrently, returning whichever completes first. Poll two futures concurrently, returning whichever completes first.

select3

Poll three futures concurrently, returning whichever completes first. Poll three futures concurrently, returning whichever completes first.

sleep

Create a future that completes after a duration. Create a future that completes after the given duration.

sleep_until

Create a future that completes at an absolute deadline. Create a future that completes at the given absolute deadline.

spawn

Spawn a standalone async task on the current worker. Spawn a standalone async task on the current worker thread.

timeout

Wrap a future with a deadline. Wrap a future with a deadline. If the future does not complete within duration, returns Err(Elapsed).

timeout_at

Wrap a future with an absolute deadline. Wrap a future with an absolute deadline. If the future does not complete before deadline, returns Err(Elapsed).

try_sleep

Fallible sleep that returns an error if the timer pool is exhausted. Create a sleep future, returning an error if the timer pool is exhausted.

try_sleep_until

Fallible sleep_until that returns an error if the timer pool is exhausted. Create an absolute-deadline sleep, returning an error if the timer pool is exhausted.

try_timeout

Fallible timeout that returns an error if the timer pool is exhausted. Wrap a future with a deadline, returning an error if the timer pool is full.

try_timeout_at

Fallible timeout_at that returns an error if the timer pool is exhausted. Wrap a future with an absolute deadline, returning an error if the timer pool is full.