Skip to content

feat(fast_io): cache PBUF_RING probe and surface in --version#3635

Merged
oferchen merged 1 commit into
masterfrom
feat/io-uring-pbuf-ring-probe
May 6, 2026
Merged

feat(fast_io): cache PBUF_RING probe and surface in --version#3635
oferchen merged 1 commit into
masterfrom
feat/io-uring-pbuf-ring-probe

Conversation

@oferchen
Copy link
Copy Markdown
Owner

@oferchen oferchen commented May 5, 2026

Summary

Implements task #2043: probe IORING_REGISTER_PBUF_RING (Linux 5.19+) at runtime, cache the result behind OnceLock, surface it on IoUringKernelInfo, and document the layered fallback chain in code and audit docs.

  • Adds a process-wide OnceLock-cached pbuf_ring_supported() -> bool probe in crates/fast_io/src/io_uring/buffer_ring.rs, re-exported at the crate root as fast_io::pbuf_ring_supported. The first call performs a uname(2) parse via config_detail::get_kernel_release_string; subsequent calls are a single relaxed atomic load.
  • Surfaces the probe on IoUringKernelInfo::pbuf_ring_supported (both Linux and the cross-platform stub) and appends , pbuf_ring=yes/no to the IoUringProbeResult::Available reason string so --version output communicates which fallback tier is active.
  • Cross-platform stub (io_uring_stub.rs) mirrors the same surface and always returns false; matching re-export added.
  • Module-level rustdoc updated on io_uring/buffer_ring.rs and io_uring/mod.rs, and docs/audits/iouring-pbuf-ring.md updated with the Phase 2 status note.

Fallback chain

  1. PBUF_RING (Linux 5.19+, IORING_REGISTER_PBUF_RING, opcode 22) - completion-time buffer selection via ring-mapped supplied buffers.
  2. Classic provide-buffers (Linux 5.6+, IORING_OP_PROVIDE_BUFFERS opcode 31, or IORING_REGISTER_BUFFERS opcode 0) - pre-registered pool with per-SQE selection.
  3. Standard read(2) / write(2) - traits::StdFileReader / traits::StdFileWriter fallback used when io_uring is unavailable entirely.
  4. Non-Linux io_uring stub (io_uring_stub.rs) - pbuf_ring_supported() returns false; BufferRing::new returns Err(Unsupported); BufferRing::try_new returns None.

Test plan

New crates/fast_io/tests/pbuf_ring_probe.rs adds five integration tests covering:

  • Idempotency across repeated calls (OnceLock caching contract).
  • Stub returns false on non-Linux / feature-disabled builds; type-correct on Linux.
  • pbuf_ring_supported() => is_io_uring_available() invariant (5.19+ implies the 5.6+ floor).
  • IoUringKernelInfo::pbuf_ring_supported mirrors the crate-root probe.
  • Cached probe returns identical values from 16 threads x 64 calls each (no torn reads, no re-entry into the kernel-version parser).

CI: fmt+clippy, nextest (Linux probe path; non-Linux stub path); audit doc renders.

Refs task #2043.

@github-actions github-actions Bot added the enhancement New feature or request label May 5, 2026
@oferchen oferchen force-pushed the feat/io-uring-pbuf-ring-probe branch 2 times, most recently from 34ecbfd to 9fbc31a Compare May 6, 2026 18:33
Adds a process-wide `OnceLock`-cached `pbuf_ring_supported()` probe for
`IORING_REGISTER_PBUF_RING` (Linux 5.19+), surfaces it on
`IoUringKernelInfo::pbuf_ring_supported`, and appends `pbuf_ring=yes/no`
to the `--version` reason string. The cross-platform stub mirrors the
same surface and always returns `false`. The fallback chain
(PBUF_RING -> classic provide-buffers -> standard read/write -> non-Linux
io_uring stub) is now documented at the module level on
`io_uring/buffer_ring.rs` and `io_uring/mod.rs`, and reflected in
`docs/audits/iouring-pbuf-ring.md` Phase 2 status.

Refs task #2043.
@oferchen oferchen force-pushed the feat/io-uring-pbuf-ring-probe branch from 9fbc31a to dc34a3d Compare May 6, 2026 18:40
@oferchen oferchen merged commit 8e1cd07 into master May 6, 2026
45 checks passed
@oferchen oferchen deleted the feat/io-uring-pbuf-ring-probe branch May 6, 2026 18:55
oferchen added a commit that referenced this pull request May 18, 2026
Adds a process-wide `OnceLock`-cached `pbuf_ring_supported()` probe for
`IORING_REGISTER_PBUF_RING` (Linux 5.19+), surfaces it on
`IoUringKernelInfo::pbuf_ring_supported`, and appends `pbuf_ring=yes/no`
to the `--version` reason string. The cross-platform stub mirrors the
same surface and always returns `false`. The fallback chain
(PBUF_RING -> classic provide-buffers -> standard read/write -> non-Linux
io_uring stub) is now documented at the module level on
`io_uring/buffer_ring.rs` and `io_uring/mod.rs`, and reflected in
`docs/audits/iouring-pbuf-ring.md` Phase 2 status.

Refs task #2043.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant