Skip to main content

Crate a10

Crate a10 

Source
Expand description

The A10 I/O library. 1

This library is meant as a low-level library safely exposing different OS’s abilities to perform non-blocking I/O.

For simplicity this only has the following main types and a number of helper types:

  • AsyncFd is a wrapper around a file descriptor that provides a safe API to perform I/O operations such as read(2) using Futures.
  • SubmissionQueue is needed to start operations, such as opening a file or new socket, but on its own can’t do much.
  • Ring needs be polled so that the I/O operations can make progress.

Some modules provide ways to create AsyncFd, e.g. socket or OpenOptions, others are simply a place to expose the Futures supporting the I/O operations. The modules try to roughly follow the same structure as that of the standard library.

§Implementation Notes

On Linux this uses io_uring, which is a completion based API. For the BSD family of OS (FreeBSD, OpenBSD, NetBSD, etc.) and for the Apple family (macOS, iOS, etc.) this uses kqueue, which is a poll based API.

To support both the completion and poll based API most I/O operations need ownership of the data, e.g. a buffer, so it can delay deallocation if needed. 2 The input data can be retrieved again by using the Extract trait.

Additional documentation can be found in the io_uring(7) and kqueue(2) manuals.

§Examples

Examples can be found in the examples directory of the source code, available online on GitHub.

  1. The name A10 comes from the A10 ring road around Amsterdam, which relates to the ring buffers that io_uring uses in its design. ↩

  2. Delaying of the deallocation needs to happen for completion based APIs where an I/O operation Future is dropped before it’s complete – the OS will continue to use the resources, which would result in a use-after-free bug. ↩

Re-exports§

pub use extract::Extract;
pub use fd::AsyncFd;

Modules§

extract
Extraction of input arguments.
fd
Asynchronous file descriptor (fd).
fs
Filesystem manipulation operations.
io
Type definitions for I/O functionality.
mem
Memory operations.
net
Networking.
pipe
Unix pipes.
process
Process handling.

Structs§

Config
Configuration of a Ring.
Ring
Ring.
SubmissionQueue
Queue to submit asynchronous operations to.