docs(fast_io): adaptive io_uring buffer-pool sizing audit + telemetry (#1834, #2045)#3499
Merged
Merged
Conversation
) Add an audit doc designing EMA-driven adaptive sizing for the io_uring registered buffer pool, plus the lightweight telemetry counters that the design depends on. The audit (docs/audits/io-uring-adaptive-buffer-sizing.md) covers: - Where the current sizing constants live (IoUringConfig defaults, for_large_files, for_small_files) and how they reach the pool. - Where to measure miss rate without a syscall on the hot path. - Proposed EMA design: alpha=0.2, WARMUP_SAMPLES=8, geometric grow / linear shrink, hysteresis cooldown, MIN/MAX clamps. - Integration points: Phase 1 (telemetry) lands now; Phase 2 (AdaptiveBufferSizer + resize driver) follows. - Risks: registered-buffer reallocation cost, RLIMIT_MEMLOCK, the 1024-buffer kernel cap, Drop ordering, in-flight SQEs, SQPOLL, per-checkout fetch_add overhead. Telemetry (Phase 1): - RegisteredBufferGroup carries total_acquires / total_misses AtomicU64 counters bumped inside checkout(). Cost is two Relaxed fetch_add per call; sub-percent at line rate. - A new RegisteredBufferStats snapshot type with miss_rate(), modeled on BufferPoolStats in the engine. - RegisteredBufferGroup::stats() accessor. - The stub module mirrors the API so adaptive-sizing logic compiles on non-Linux targets. - Five new unit tests cover the zero state, hit path, miss path, return-does-not-decrement invariant, and the helper math. Phase 2 (the actual AdaptiveBufferSizer + resize cycle) is intentionally not in this PR. The doc is the contract.
github-actions
Bot
added
the
documentation
oferchen
added a commit
that referenced
this pull request
May 5, 2026
) (#3499) Add an audit doc designing EMA-driven adaptive sizing for the io_uring registered buffer pool, plus the lightweight telemetry counters that the design depends on. The audit (docs/audits/io-uring-adaptive-buffer-sizing.md) covers: - Where the current sizing constants live (IoUringConfig defaults, for_large_files, for_small_files) and how they reach the pool. - Where to measure miss rate without a syscall on the hot path. - Proposed EMA design: alpha=0.2, WARMUP_SAMPLES=8, geometric grow / linear shrink, hysteresis cooldown, MIN/MAX clamps. - Integration points: Phase 1 (telemetry) lands now; Phase 2 (AdaptiveBufferSizer + resize driver) follows. - Risks: registered-buffer reallocation cost, RLIMIT_MEMLOCK, the 1024-buffer kernel cap, Drop ordering, in-flight SQEs, SQPOLL, per-checkout fetch_add overhead. Telemetry (Phase 1): - RegisteredBufferGroup carries total_acquires / total_misses AtomicU64 counters bumped inside checkout(). Cost is two Relaxed fetch_add per call; sub-percent at line rate. - A new RegisteredBufferStats snapshot type with miss_rate(), modeled on BufferPoolStats in the engine. - RegisteredBufferGroup::stats() accessor. - The stub module mirrors the API so adaptive-sizing logic compiles on non-Linux targets. - Five new unit tests cover the zero state, hit path, miss path, return-does-not-decrement invariant, and the helper math. Phase 2 (the actual AdaptiveBufferSizer + resize cycle) is intentionally not in this PR. The doc is the contract.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/audits/io-uring-adaptive-buffer-sizing.mdcovering EMA-driven adaptive sizing for the io_uring registered buffer
pool, addressing tasks Scan for placeholder markers on the first line #1834 and Align cross-compile matrix with build_daemon metadata #2045.
RegisteredBufferGroupnow carriestotal_acquiresand
total_missesAtomicU64counters bumped insidecheckout(),plus a
RegisteredBufferStatssnapshot accessor with amiss_rate()helper. The stub module mirrors the API so non-Linux targets compile.
AdaptiveBufferSizer+ resize driver) isdeliberately scoped out; the audit doc fixes the design contract so
the follow-up is mechanical.
Audit highlights
The doc cites concrete file:line locations for every claim:
IoUringConfigdefaults(
crates/fast_io/src/io_uring/config.rs:330-342),for_large_files(
config.rs:347-358),for_small_files(config.rs:362-373).RegisteredBufferGroup::new(
crates/fast_io/src/io_uring/registered_buffers.rs:204-296),try_new(registered_buffers.rs:303-305).crates/fast_io/src/io_uring/file_writer.rs:215-246,file_writer.rs:282-308,crates/fast_io/src/io_uring/file_reader.rs:158-184.crates/engine/src/local_copy/buffer_pool/throughput.rs:80-246(
ThroughputTracker,alpha=0.1,WARMUP_SAMPLES=8).crates/engine/src/local_copy/buffer_pool/pool.rs:783-797,849-859(
BufferPoolStats,OC_RSYNC_BUFFER_POOL_STATS=1).Proposed EMA parameters:
alpha=0.2,WARMUP_SAMPLES=8, sample windowof 256 acquires,
MIN_BUFFERS=2,MAX_BUFFERS=min(64, kernel_cap),GROW_THRESHOLD=10%,SHRINK_THRESHOLD=0.5%, geometric2xgrow,linear
0.75xshrink,4x SAMPLE_WINDOWcooldown for hysteresis.Telemetry cost
fetch_add(1, Relaxed)on x86_64 islock xadd(~5 ns uncontended); onaarch64 is
LDADD(similar). Two extrafetch_addpercheckoutissub-percent overhead even at sustained line-rate, and the pool is
single-threaded per ring in practice so cache-line contention is not a
concern.
Test plan
cargo fmt --all -- --checkcargo check -p fast_io --all-features --testscrates/fast_io/src/io_uring/registered_buffers.rs:stats_initially_zerostats_count_successful_checkoutsstats_count_misses_on_exhaustionstats_not_decremented_on_returnstats_miss_rate_zero_when_no_acquiresstats_miss_rate_all_misses