Async I/O

Namespace: dftracer::utils::io

For usage guide and examples, see Async I/O API.

source

struct IoAwaitable

Result of an async I/O operation. Holds the return value of the underlying syscall (bytes read/written, fd for open, 0 for close) or a negative errno on failure.

Public Functions

inline bool await_ready() const noexcept

void await_suspend(std::coroutine_handle<> h) noexcept

inline ssize_t await_resume() const noexcept

Public Members

ssize_t result_ = 0

std::coroutine_handle handle_ = {}

SubmitContext *submit_ctx_ = nullptr

bool ready_ = false

Public Static Functions

static inline IoAwaitable ready(ssize_t result) noexcept

Create an already-completed awaitable (for sync fallback)

source

class IoBackend

Abstract I/O backend interface. Concrete implementations (io_uring, epoll+threadpool, threadpool-only) live entirely in src/ and are never exposed to users.

Public Functions

virtual ~IoBackend() = default

virtual void start() = 0

Start the backend (completion thread, ring init, etc.)

virtual void stop() = 0

Stop the backend (join completion thread, drain pending ops)

virtual IoAwaitable submit_read(int fd, void *buf, std::size_t len) = 0

Submit an async sequential read. Works on any fd type.

virtual IoAwaitable submit_write(int fd, const void *buf, std::size_t len) = 0

Submit an async sequential write. Works on any fd type.

virtual IoAwaitable submit_pread(int fd, void *buf, std::size_t len, off_t offset) = 0

Submit an async positional read. Only seekable fds.

virtual void submit_pread_callback(int fd, void *buf, std::size_t len, off_t offset, IoCompletionFn completion, void *context) = 0

Submit an async positional read with a completion callback. The callback receives either a byte count or a negative errno.

virtual IoAwaitable submit_pwrite(int fd, const void *buf, std::size_t len, off_t offset) = 0

Submit an async positional write. Only seekable fds.

virtual IoAwaitable submit_open(const char *path, int flags, mode_t mode) = 0

Submit an async open operation.

virtual IoAwaitable submit_close(int fd) = 0

Submit an async close operation.

virtual IoAwaitable submit_fsync(int fd) = 0

Submit an async fsync operation.

virtual IoAwaitable submit_ftruncate(int fd, off_t length) = 0

Submit an async ftruncate operation.

virtual IoAwaitable submit_fstat(int fd, struct stat *buf) = 0

Submit an async fstat operation.

virtual IoAwaitable submit_readv(int fd, const struct iovec *iov, int iovcnt) = 0

Scatter-gather sequential read. Works on any fd type.

virtual IoAwaitable submit_writev(int fd, const struct iovec *iov, int iovcnt) = 0

Scatter-gather sequential write. Works on any fd type.

virtual IoAwaitable submit_preadv(int fd, const struct iovec *iov, int iovcnt, off_t offset) = 0

Scatter-gather positional read. Only seekable fds.

virtual IoAwaitable submit_pwritev(int fd, const struct iovec *iov, int iovcnt, off_t offset) = 0

Scatter-gather positional write. Only seekable fds.

virtual IoAwaitable submit_lseek(int fd, off_t offset, int whence) = 0

Reposition file offset. Returns new offset.

virtual IoAwaitable submit_sendfile(int out_fd, int in_fd, off_t offset, std::size_t count) = 0

Zero-copy transfer from in_fd to out_fd. Returns bytes sent.

virtual std::size_t poll(int timeout_ms = 0) = 0

Non-blocking poll for completions. Called by idle workers. Returns number of completions reaped.

inline virtual int flush()

Flush all pending batched operations. Backends that submit ops immediately (thread pool, epoll+threadpool) return 0. io_uring backend submits all pending SQEs in one syscall. Returns number of operations flushed.

virtual IoAwaitable submit_accept(int listen_fd, struct sockaddr *addr, socklen_t *addrlen) = 0

Accept a connection on a listening socket. Returns the new client fd via IoAwaitable::result_.

virtual IoAwaitable submit_recv(int fd, void *buf, std::size_t len, int flags) = 0

Receive data from a connected socket. Returns bytes received via IoAwaitable::result_.

virtual IoAwaitable submit_send(int fd, const void *buf, std::size_t len, int flags) = 0

Send data to a connected socket. Returns bytes sent via IoAwaitable::result_.

ssize_t submit_read_sync(int fd, void *buf, std::size_t len, off_t offset)

Blocking read &#8212; for contexts that cannot co_await (e.g., VFS). Submits through the normal async path and blocks until done.

ssize_t submit_write_sync(int fd, const void *buf, std::size_t len, off_t offset)

Blocking write.

int submit_fsync_sync(int fd)

Blocking fsync.

int submit_ftruncate_sync(int fd, off_t length)

Blocking ftruncate.

int submit_fstat_sync(int fd, struct stat *buf)

Blocking fstat.

virtual std::string name() const = 0

Human-readable name for logging.

source

struct SubmitContext

Submission context &#8212; base struct for backend-specific data. The first member is always a function pointer that await_suspend calls to trigger the actual I/O submission. Backends derive from this (or embed it) to add operation-specific fields.

Public Types

using SubmitFn = void (*)(SubmitContext*, IoAwaitable*)

Public Members

SubmitFn submit = nullptr