eve.aio.linux.io

Async file I/O primitives for Linux with io_uring optimization.

This module provides a Linux-specific implementation of asynchronous file I/O that uses io_uring when available for true kernel-level async operations. When io_uring is not available (Linux < 5.1 or restricted environments), it falls back to a thread pool implementation.

io_uring benefits for file I/O:

  • True kernel-level async - no threads needed
  • Zero syscall overhead with submission queue batching
  • Works with regular files unlike epoll
var FILE_RING_ENTRIES O_CLOEXEC
alias ErrorCallback ReadCallback WriteCallback
enum OperationType ThreadPoolWorkType
struct AsyncFile FileConfig ThreadPoolWorkItem
class AsyncFileState FileThreadPool IoUringFileRing
fn mapOpenError validated

Types 11

structFileConfig

File operation configuration.

Fields
size_t bufferSizeBuffer size hint for I/O operations.
Methods
bool isValid() @property const pure @safe nothrow @nogcValidate the config.
aliasReadCallback = void delegate(ref AsyncFile file, ubyte[] data, int error) @safe

Callback invoked when a read operation completes.

aliasWriteCallback = void delegate(ref AsyncFile file, size_t bytesWritten, int error) @safe

Callback invoked when a write operation completes.

aliasErrorCallback = void delegate(ref AsyncFile file, int error) @safe

Callback invoked on error conditions.

structAsyncFile

Async file handle wrapper.

Wraps a file descriptor and integrates with the Layer 1 event loop for async read/write operations. On Linux 5.1+, uses io_uring for true kernel-level async. Falls back to thread pool on older kernels.

Fields
AsyncFileState _state
Methods
AsyncFile create(FileConfig config = FileConfig.init) @trustedCreate a detached file wrapper.
void onRead(ReadCallback callback) @safeRegister callback for read completion.
void onWrite(WriteCallback callback) @safeRegister callback for write completion.
void onError(ErrorCallback callback) @safeRegister callback for error conditions.
bool isOpen() @property const @safe nothrow @nogcCheck if the file is open.
FileState state() @property const @safe nothrow @nogcGet the current file state.
bool usingIoUring() @property const @safe nothrow @nogcCheck if this file is using io_uring for async operations.
OpenResult open(ref EventLoop loop, scope const(char)[] path, int flags) @trustedOpen a file for reading and/or writing.
FileResult read(ubyte[] buffer, ulong offset) @trustedQueue an async read operation.
FileResult write(scope const(ubyte)[] data, ulong offset) @trustedQueue an async write operation.
long size() @trustedQuery the file size.
void close() @trustedClose the file.
void dispose() @trustedDispose the file wrapper and release resources.
AsyncFileState mutableState() @trusted
private enumOperationType : ubyte
NONE
READ
WRITE
private classAsyncFileState
Fields
FileConfig _config
Handle _handle
FileState _fileState
EventLoop * _loop
Token _wakeupToken
Token _ioToken
bool _usingIoUring
ReadCallback onRead
WriteCallback onWrite
ErrorCallback onError
OperationType _pendingOp
ubyte[] _readBuffer
ubyte[] _writeDataCopy
IoUringFileRing _ring
int _resultError
size_t _resultBytes
Methods
bool isOpen() @property const @safe nothrow @nogc
bool usingIoUring() @property const @safe nothrow @nogc
OpenResult open(ref EventLoop loop, scope const(char)[] path, int flags) @trusted nothrow
FileResult read(ubyte[] buffer, ulong offset) @trusted
FileResult write(scope const(ubyte)[] data, ulong offset) @trusted
private FileResult submitIoUringRead(ubyte[] buffer, ulong offset) @trusted
private FileResult submitIoUringWrite(scope const(ubyte)[] data, ulong offset) @trusted
private FileResult submitThreadPoolRead(ubyte[] buffer, ulong offset) @trusted
private FileResult submitThreadPoolWrite(scope const(ubyte)[] data, ulong offset) @trusted
long size() @trusted nothrow
void closeFile() @trusted nothrow
void dispose() @trusted nothrow
void handleIoUringCompletion(ref EventLoop loop, Token token, IoReady ready) @safe nothrow
void dispatchCompletion(ulong userData, int result) @trusted nothrow
void handleThreadPoolWakeup(ref EventLoop loop, Token token) @safe nothrow
void invokeReadCallback(int error, size_t bytes) @safe nothrow
void invokeWriteCallback(int error, size_t bytes) @safe nothrow
void notifyComplete(int error, size_t bytes) @trusted nothrow
AsyncFile owner() @trusted nothrow
Constructors
this(FileConfig config)
private classIoUringFileRing

Dedicated io_uring instance for file I/O operations.

Each AsyncFileState owns its own ring and eventfd so completion notifications stay scoped to the event loop that registered them.

Fields
private int _eventFd
private bool _valid
private void * _sqRing
private void * _cqRing
private void * _sqes
private size_t _sqRingSize
private size_t _cqRingSize
private size_t _sqesSize
private uint _sqEntries
private uint _cqEntries
private shared(uint) * _sqHead
private shared(uint) * _sqTail
private shared(uint) * _sqMask
private shared(uint) * _sqArray
private shared(uint) * _cqHead
private shared(uint) * _cqTail
private shared(uint) * _cqMask
private io_uring_cqe * _cqes
private io_uring_sqe * _sqeArray
private int _ringFd
private Mutex _submitMutex
private bool _probed
private bool _available
Methods
private uint load(shared(uint) * ptr) @trusted nothrow @nogc
private void store(shared(uint) * ptr, uint value) @trusted nothrow @nogc
IoUringFileRing create() @trusted nothrowCreate a file-local io_uring ring.
bool isValid() @property const @safe nothrow @nogc
int eventFd() @property const @safe nothrow @nogc
void dispose() @trusted nothrow
private void initRing() @trusted nothrow
private void cleanup() @trusted nothrow @nogc
bool submitRead(int fd, void * buf, uint len, ulong offset, ulong userData) @trusted nothrowSubmit a read operation to the ring.
bool submitWrite(int fd, const(void) * buf, uint len, ulong offset, ulong userData) @trusted nothrowSubmit a write operation to the ring.
void processCompletions(scope CompletionCallback callback) @trusted nothrowProcess all available completions.
Constructors
this()
private enumThreadPoolWorkType : ubyte
READ
WRITE
private structThreadPoolWorkItem
Fields
ThreadPoolWorkType type
int fd
ubyte * buffer
size_t length
ulong offset
AsyncFileState state
private classFileThreadPool

Simple thread pool for file I/O operations (fallback when io_uring unavailable).

Fields
private Mutex _mutex
private Condition _condition
private ThreadPoolWorkItem[] _queue
private Thread _worker
private bool _shutdown
private FileThreadPool _instance
private bool _instanceCreated
Methods
FileThreadPool instance() @trusted nothrow
void submit(ThreadPoolWorkItem item) @trusted nothrow
private void workerLoop() @trusted nothrow
private void processWork(ref ThreadPoolWorkItem item) @trusted nothrow
Constructors
this()

Functions 2

private fnOpenResult mapOpenError(int err) pure @safe nothrow @nogcMap errno values to OpenResult variants.
private fnFileConfig validated(FileConfig config) pure @safe nothrow @nogc

Variables 2

private enumvarO_CLOEXEC = 0x80000

O_CLOEXEC for exec-safe file descriptors.

private enumvarFILE_RING_ENTRIES = 64u

Requested ring size for file I/O operations.