Skip to content

feat: distinguish disabled vs failed registration in RegisteredBufferStats#4065

Merged
oferchen merged 1 commit into
masterfrom
feat/registered-buffer-stats-disabled-vs-failed-2156
May 14, 2026
Merged

feat: distinguish disabled vs failed registration in RegisteredBufferStats#4065
oferchen merged 1 commit into
masterfrom
feat/registered-buffer-stats-disabled-vs-failed-2156

Conversation

@oferchen
Copy link
Copy Markdown
Owner

Summary

  • Add RegisteredBufferStatus { Enabled | Disabled | RegistrationFailed { reason } } so observability can tell why a transfer is using non-registered buffers.
  • Route IoUringReader / IoUringWriter construction through a new RegisteredBufferGroup::try_new_with_status helper that captures the kernel's formatted errno on failure, and expose the value via registered_buffer_status().
  • Mirror the enum on the non-Linux stub so cross-platform telemetry surfaces stay cfg-free.
  • Mark the IU2 row in docs/audits/io-uring-fixed-buffer-invariants-audit.md as RESOLVED.

Previously, Option<RegisteredBufferGroup> collapsed two operator-visible cases - caller-opted-out via IoUringConfig::register_buffers = false, and kernel-rejected registration (low RLIMIT_MEMLOCK, IORING_MAX_REG_BUFFERS exceeded, seccomp, etc.) - into the same None, leaving no signal to diagnose why the unfixed IORING_OP_READ / IORING_OP_WRITE path was in use. The new enum closes that observability gap.

Refs #2156. Sibling design notes in docs/audits/iouring-fixed-buffer-registration.md Section 5a.

Test plan

  • try_new_with_status_disabled_when_flag_off - confirms enabled=false returns Disabled, never RegistrationFailed.
  • try_new_with_status_enabled_on_success - confirms successful registration yields Enabled and a live group.
  • try_new_with_status_registration_failed_carries_reason - forces failure via the wrapper's MAX_REGISTERED_BUFFERS ceiling and confirms the formatted errno reaches the caller.
  • with_ring_skips_registration_when_disabled - extended to assert the writer's status is Disabled.
  • registered_buffer_status_failed_when_kernel_rejects - confirms the writer's status is RegistrationFailed when registration is requested but rejected.
  • CI: fmt+clippy, nextest (stable), Windows, macOS, Linux musl all green.

Add a `RegisteredBufferStatus` enum (Enabled / Disabled /
RegistrationFailed { reason }) and surface it on `IoUringReader` and
`IoUringWriter` via `registered_buffer_status()`. Both writers and
readers route construction through a new
`RegisteredBufferGroup::try_new_with_status` helper that captures the
kernel's formatted errno on failure.

Previously, `Option<RegisteredBufferGroup>` collapsed two distinct
operator-visible cases - "caller opted out via
`IoUringConfig::register_buffers = false`" and "kernel rejected
registration (low RLIMIT_MEMLOCK, IORING_MAX_REG_BUFFERS exceeded,
seccomp, etc.)" - into the same `None`, leaving no signal to diagnose
why a transfer was using the unfixed `IORING_OP_READ` / `IORING_OP_WRITE`
fallback. The enum closes that observability gap. Mirrored stub on
non-Linux so cross-platform telemetry stays cfg-free.

Refs: oc-rsync #2156. Closes the open IU2 row in
`docs/audits/io-uring-fixed-buffer-invariants-audit.md`.
@github-actions github-actions Bot added the enhancement New feature or request label May 14, 2026
@oferchen oferchen merged commit 3d61519 into master May 14, 2026
43 of 45 checks passed
@oferchen oferchen deleted the feat/registered-buffer-stats-disabled-vs-failed-2156 branch May 16, 2026 19:50
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