xtc_iosched(3)

---

xtc_iosched(3)

adaptive write-batching scheduler for the async file path

XTC_IOSCHED(3) Library Functions Manual XTC_IOSCHED(3)

xtc_iosched_create, xtc_iosched_destroy, xtc_iosched_write, xtc_iosched_flush, xtc_iosched_get_stats — adaptive write-batching scheduler for the async file path

#include <xtc.h>
#include <xtc_iosched.h>

int
xtc_iosched_create(const xtc_iosched_opts_t *opts, xtc_iosched_t **out);

void
xtc_iosched_destroy(xtc_iosched_t *s);

int
xtc_iosched_write(xtc_iosched_t *s, const void *buf, uint32_t len, int64_t off);

int
xtc_iosched_flush(xtc_iosched_t *s);

void
xtc_iosched_get_stats(const xtc_iosched_t *s, xtc_iosched_stats_t *out);

xtc_iosched is an adaptive write-batching scheduler for a single writer over the async file path (xtc_aio(3)), intended for the direct-I/O writeback hot path such as a buffer manager flusher or a WAL writer. Queued writes are coalesced into batches; each flush issues the batch via () and measures throughput. When adaptive mode is enabled a genetic tuner (xtc_dio_sched(3)) evolves the batch size to maximise observed throughput and re-adapts when the workload or device behaviour shifts; with adaptive off it uses a fixed batch size.

: all calls for one scheduler must come from one fiber (the device's writer). This keeps batching free of cross-fiber coordination; flushing parks only that fiber.

() creates a scheduler from opts: the target descriptor fd, whether to adaptive-tune the batch size, the fixed or initial batch_size, the min_batch/max_batch gene bounds when adaptive, and the tuner PRNG seed.

() queues a len-byte write of buf at offset off. The buffer must remain valid until the next flush completes. When the queue reaches the current batch size an implicit flush runs, issuing the batch and possibly parking the writer fiber.

() issues all queued writes immediately.

() copies the scheduler's counters into out: total writes queued, bytes written, flushes issued, the cur_batch size in use, the last_mbps throughput of the last flush, and the tuner mutation_rate (adaptive only).

() frees the scheduler.

xtc_iosched_create(), xtc_iosched_write(), and xtc_iosched_flush() return XTC_OK on success or a negative errno / XTC_E_* code from the underlying flush.

xtc_aio(3), xtc_dio_sched(3), xtc_fs(3)

The XTC Project.

July 3, 2026 Debian

View the mdoc source