Crate lio

Crate lio 

Source
Expand description

§Lio - Platform-Independent Async I/O Library

Lio is a high-performance, platform-independent async I/O library that uses the most efficient IO for each platform.

§Features

  • Zero-copy operations where possible.
  • Automatic fallback to blocking operations when async isn’t supported.
  • Manual control with high level async API.

Note: This is a quite low-level library. This library creates os resources (fd’s) which it doesn’t cleanup automatically.

§Platform support

PlatformI/O MechanismStatus
Linuxio_uringYes
WindowsIOCPNot supported (planned)
macOSkqueueYes
Other Unixpoll/epoll/event portsYes

§Quick Start

use std::os::fd::RawFd;

fn handle_result(result: std::io::Result<i32>, buf: Vec<u8>) {
  println!("result: {result:?}, buf: {buf:?}");
}

async fn example() -> std::io::Result<()> {
    let fd: RawFd = 1; // stdout
    let data = b"Hello, World!\n".to_vec();

    // Async API (on "high" feature flag).
    let (result, buf) = lio::write(fd, data.clone(), 0).await;
    handle_result(result, buf);

    // Channel API (on "high" feature flag).
    let receiver: oneshot::Receiver<(std::io::Result<i32>, Vec<u8>)> = lio::write(fd, data.clone(), 0).get_receiver();
    let (result, buf) = receiver.recv().unwrap();
    handle_result(result, buf);

    // Callback API.
    lio::write(fd, data.clone(), 0).when_done(|(result, buf)| {
      handle_result(result, buf);
    });

    Ok(())
}

Note: Only one of these API’s can be used for one operation.

§Safety and Threading

  • The library handles thread management for background I/O processing
  • Operations can be safely used across different threads

§Error Handling

All operations return std::io::Result or BufResult for operations that return buffers. Errors are automatically converted from platform-specific error codes to Rust’s standard I/O error types.

Modules§

ffiunstable_ffi
lio C API
op

Enums§

OperationProgress
Represents the progress of an I/O operation across different platforms.

Functions§

accept
Accepts a connection on a listening socket.
bind
Binds a socket to a specific address.
close
Closes a file descriptor.
connect
Connects a socket to a remote address.
exit
Shut down the lio I/O driver background thread(s) and release OS resources.
fsync
Sync to fd.
linkat
Create a hard-link
listen
Marks a socket as listening for incoming connections.
openat
Opens a file relative to a directory file descriptor.
read
Performs a read operation on a file descriptor. Equivalent of the pread syscall.
recv
Receives data from a connected socket.
send
Sends data on a connected socket.
shutdown
Shuts socket down.
socket
Creates a new socket with the specified domain, type, and protocol.
symlinkat
Create a soft-link
tee
Copies data between file descriptors without copying to userspace (Linux only).
timeout
Times out something
truncate
Truncates a file to a specified length.
write
Performs a write operation on a file descriptor. Equivalent to the pwrite syscall.

Type Aliases§

BufResult
Result type for operations that return both a result and a buffer.