Crate ringline

Expand description

ringline — async I/O runtime with io_uring and mio backends.

ringline is a thread-per-core I/O framework with two compile-time selectable backends: io_uring (Linux, default) and mio (cross-platform). 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

With io-uring feature (default): Linux 6.0+. Requires io_uring with multishot recv, ring-provided buffers, SendMsgZc, and fixed file table support.

With --no-default-features: mio backend, works on Linux and macOS. NVMe passthrough and zero-copy sends are not available. Direct I/O and filesystem operations are supported via a dedicated thread pool.

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 signal::Signal;
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;
pub use config::TlsClientConfig;
pub use config::TlsConfig;

Modules§

config
direct_io: Direct I/O via io_uring (O_DIRECT + IORING_OP_READ / IORING_OP_WRITE).
error
fs: Async filesystem I/O via io_uring.
guard
handler
mpsc: Bounded multi-producer, single-consumer async channel. A bounded multi-producer, single-consumer channel.
nvme: NVMe io_uring passthrough types and helpers.
oneshot: Single-use async channel for sending exactly one value. A single-use channel for sending exactly one value between tasks.
process: Async process spawning.
signal: Signal handling for graceful shutdown.

Structs§

BlockingJoinHandle: Future returned by spawn_blocking(). Resolves to the closure’s return value. Future returned by spawn_blocking(). Resolves to the closure’s return value.
CancellationToken: Token for cooperative cancellation of async tasks. A token for cooperative cancellation of async tasks.
CancelledFuture: Future returned by CancellationToken::cancelled(). Future returned by CancellationToken::cancelled.
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.
ConnStream: Wraps a ConnCtx and implements futures_io::{AsyncRead, AsyncWrite, AsyncBufRead}. Wraps a ConnCtx and implements AsyncRead, AsyncWrite, and AsyncBufRead.
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.
JoinHandle: Handle to a spawned task’s return value, obtained from spawn_with_handle(). Handle to a spawned task’s return value.
MemoryRegion: Memory region for io_uring fixed buffer registration. A user-registered memory region (e.g., mmap’d storage arena).
RecvError: Error returned by oneshot::Receiver when the sender is dropped. Error returned by oneshot::Receiver when the sender is dropped without sending a value.
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).
ResolveFuture: Future returned by resolve(). Future returned by resolve(). Resolves to a SocketAddr.
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.
SendError: Error returned by mpsc::Sender::send when the receiver is dropped. Error returned by mpsc::Sender::send and mpsc::Sender::try_send when the receiver has been dropped. Contains the value that could not be sent.
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().
TlsInfo: TLS session info (protocol version, cipher suite, etc.). Information about a negotiated TLS session.
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§

Backend: The I/O backend selected at compile time.
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.
PeerAddr: Peer address for a connection — TCP or Unix domain socket. Peer address for a connection — either TCP (IPv4/IPv6) or Unix domain socket.
TryRecvError: Error returned by mpsc::Receiver::try_recv. Error returned by mpsc::Receiver::try_recv.
TrySendError: Error returned by mpsc::Sender::try_send. Error returned by mpsc::Sender::try_send when the channel is full.

Traits§

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

Functions§

backend: Returns the I/O backend selected at compile time.
connect: Initiate an outbound TCP connection from any async task. Initiate an outbound TCP connection from any async task (connection or standalone).
connect_tls: Initiate an outbound TLS connection from any async task. Initiate an outbound TLS connection from any async task (connection or standalone).
connect_tls_with_timeout: Initiate an outbound TLS connection with a timeout from any async task. Initiate an outbound TLS connection with a timeout from any async task.
connect_unix: Initiate an outbound Unix domain socket connection from any async task. Initiate an outbound Unix domain socket connection from any async task.
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_flush: Submit an NVMe flush and return a future for the result. Submit an NVMe flush and return a future for the result.
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.
resolve: Resolve a hostname to a SocketAddr using the dedicated resolver pool. Resolve a hostname to a SocketAddr using the dedicated resolver pool.
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.
spawn_blocking: Offload a blocking closure to the dedicated blocking thread pool. Offload a blocking closure to the dedicated blocking thread pool.
spawn_with_handle: Spawn a standalone async task and return a handle to await its result. Spawn a standalone async task and return a handle to await its result.
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§

Traits§

Functions§

Crate ringline