Crate ringline

Expand description

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.

Crate ringline

Crate ringline Copy item path

§Quick Start

§Platform

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate ringline