Support io_uring by yellowhatter · Pull Request #2332 · eclipse-zenoh/zenoh

yellowhatter · 2025-12-23T08:41:05Z

Summary

This PR introduces io_uring support to Zenoh behind the uring feature flag.

The implementation is intentionally scoped as an internal transport/runtime enhancement rather than a public API change. The patch adds a new internal crate, commons/zenoh-uring, and wires it into the workspace so the io_uring-specific memory, batching, reader, and writer logic can live outside the public surface area.

What this changes

Transport integration

Adds uring feature that is efficient only for Linux.
Adds io_uring support to the Zenoh transport stack.
Integrates the new I/O path with most links.
Adds automatic read-mode selection between io_uring and tokio.
Updates transport-side code paths to route io_uring operations through dedicated transport support code.

Link coverage

Adds support for streamed/socket-based links.
Keeps the existing transport model intact so the non-uring path still works normally.

Buffer and memory handling

Introduces a dedicated page-backed arena for uring buffers.
Allocates pinned memory with mmap/mlock and exposes it both as io_uring provided buffers and as registered iovec buffers.

Reader / writer path

Adds dedicated reader and writer implementations for the uring path.
Adds zero-copy oriented handling for split and fragmented payloads.
Improves RX batch reclamation so large payloads can be handled with less memory waste.
Tunes batch growth behavior to better support big messages and improve footprint.

Error handling and runtime integration

Passes Tokio executor context into the uring thread so Tokio-aware user code remains compatible.

Build / CI / test coverage

Adds the uring crate and dependency wiring to the workspace.
Ensures Zenoh still compiles when the uring feature is disabled.
Adds uring to CI.
Expands uring-related tests, including dynamic-port coverage and extended UDP test paths.

Design notes

The implementation follows a conservative enhancement approach:

no public API expansion,
no behavioral change for users who do not enable uring,
all uring-specific code isolated behind feature gates and internal crates,
transport and buffer-management changes kept close to the existing architecture instead of introducing a separate parallel stack.

Expected user impact

For users building with -F uring, this adds a new Linux I/O backend that reduces overhead in the transport path and improve handling of larger or fragmented payloads. For users who do not enable the feature, the existing build and transport behavior remain unchanged. The improvement gives 25-50% latency reduction and few % messaging rate increase. Performance tests included in comments to this PR below.

Validation

Validation for this PR is centered on:

successful compilation with and without uring,
CI coverage for the new feature,
transport-level tests for the new I/O path,
UDP and split-buffer / fragmentation scenarios,
correctness of buffer reclamation and RX finalization behavior.

🏷️ Label-Based Checklist

Based on the labels applied to this PR, please complete these additional requirements:

Labels: enhancement

✨ Enhancement Requirements

Since this PR enhances existing functionality:

Enhancement scope documented - Clear description of what is being improved
Minimum necessary code - Implementation is as simple as possible, doesn't overcomplicate the system
Backwards compatible - Existing code/APIs still work unchanged
No new APIs added - Only improving existing functionality
Tests updated - Existing tests pass, new test cases added if needed
Performance improvement measured - If applicable, before/after metrics provided
Documentation updated - Existing docs updated to reflect improvements
User impact documented - How users benefit from this enhancement

Remember: Enhancements should not introduce new APIs or breaking changes.

Instructions:

Check off items as you complete them (change - [ ] to - [x])
The PR checklist CI will verify these are completed

This checklist updates automatically when labels change, but preserves your checked boxes.

Conflicts: Cargo.toml

- support UDP - WIP on streamed links

- fix buffer reclamation bug

- integrate uring support for most links - make automatic read mode selection (uring or tokio) - code format

codecov · 2026-02-09T22:12:31Z

Codecov Report

❌ Patch coverage is 78.15207% with 227 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.08%. Comparing base (e03b0c0) to head (4487490).
⚠️ Report is 9 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
commons/zenoh-uring/src/linux/reader/window.rs	55.70%	66 Missing ⚠️
commons/zenoh-uring/src/linux/api/reader/mod.rs	82.60%	36 Missing ⚠️
commons/zenoh-uring/src/linux/batch_arena.rs	62.19%	31 Missing ⚠️
...noh-uring/src/linux/api/reader/fragmented_batch.rs	47.22%	19 Missing ⚠️
commons/zenoh-uring/src/linux/page_arena.rs	72.85%	19 Missing ⚠️
...mons/zenoh-uring/src/linux/api/reader/rx_buffer.rs	58.62%	12 Missing ⚠️
...mons/zenoh-uring/src/linux/api/reader/read_task.rs	76.74%	10 Missing ⚠️
...s/zenoh-uring/src/linux/reader/reservable_arena.rs	90.62%	9 Missing ⚠️
commons/zenoh-buffers/src/zbuf.rs	46.15%	7 Missing ⚠️
io/zenoh-transport/src/common/batch.rs	72.00%	7 Missing ⚠️
... and 3 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2332      +/-   ##
==========================================
- Coverage   74.11%   74.08%   -0.04%     
==========================================
  Files         400      414      +14     
  Lines       61030    62032    +1002     
==========================================
+ Hits        45234    45954     +720     
- Misses      15796    16078     +282

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

- make growing RX batch memory (to optimize mem footprint and support zero-copy for big payloads)

- exponential grow for uring batch arena - tune RX arena size based on config

Conflicts: Cargo.lock

- add async wait for uring-global errors (as opposed to rx-task-related errors) - supply uring thread with tokio executor context to be compatible with tokio-aware user code

Conflicts: io/zenoh-transport/src/unicast/universal/link.rs

yellowhatter · 2026-04-17T15:31:56Z

100Hz:

main:

uring:

yellowhatter · 2026-04-17T15:33:18Z

1kHz:

main:

uring:

yellowhatter · 2026-04-17T15:34:05Z

max freq

main:

uring:

- support transport_compression for io_uring - fix stats for io_uring

yellowhatter · 2026-04-22T13:39:06Z

Docs update: zenoh-rs/zenoh-web#127

Conflicts: Cargo.lock Cargo.toml zenoh-ext/tests/liveliness.rs

Conflicts: Cargo.lock Cargo.toml

- Optimize memory fragmentation - Optimize main read loop - Optimnize zbuf reader

yellowhatter · 2026-06-01T09:27:08Z

@YuanYuYuan can you please validate this performance on your side? The issue should be fixed now

YuanYuYuan · 2026-06-12T07:57:29Z

@YuanYuYuan can you please validate this performance on your side? The issue should be fixed now

The evaluation is finally out. The results look quite good. https://gist.github.com/YuanYuYuan/f919ebf7eb4b171e502aa13536e5d5db

- Remove debug sleep(100ms) from z_ping warmup and measurement loops - Revert unrelated liveliness test weakening: restore order-specific assert_eq! checks, remove HashSet indirection, #[ignore] attrs, debug println!s, and commented-out code - Delete orphaned linux/memory/ directory (never compiled, duplicate of reader/ left over from the split-into-files refactor)

- Degrade gracefully when io_uring reactor init fails (Option<Uring> in TransportManagerState, warn + fallback to tokio instead of error) - Enforce lease timeout on the uring RX task via TimeoutTracker; reset on each received fragment, bail on expiry (was TODO/unimplemented) - Restrict get_fd() to Connected UDP only; unconnected sockets are shared across peers and cannot be demuxed by io_uring RecvMulti - Fix BatchHeader::new() called without transport_compression feature; use tuple constructor BatchHeader(h) which is always available

Strip the unused thread-priority/realtime scheduling block, commented //ring.submit(), //let len, alternate enter() calls, and the no-op //bail! match arms from api/reader/mod.rs. Remove the commented log! macro from window.rs. Remove commented writer field and constructor from uring.rs. Fix "Urng" typo in reactor thread log message.

The io_uring TX writer is not wired into the transport layer in this PR. Remove linux/writer/ and linux/api/writer/ rather than shipping unused public API. Remove thread-priority from Cargo.toml; its only consumer was the commented-out realtime scheduling block already deleted.

fix(uring): review fixups for eclipse-zenoh#2332

WIP on io_uring

10eb1a1

yellowhatter requested a review from YuanYuYuan December 23, 2025 08:41

yellowhatter self-assigned this Dec 23, 2025

yellowhatter added the enhancement Existing things could work better label Dec 23, 2025

yellowhatter added 19 commits January 16, 2026 13:58

Merge commit '52b9efdcd2aa9d195111e80e3dea250fe48fed92'

ccba406

Conflicts: Cargo.toml

Very big WIP on Io_uring

85aef6f

- support zero-copy link integration

9b8222e

- support UDP - WIP on streamed links

WIP on fragmented buffer support

3a88a7d

Support streaming sockets

889b65d

Merge commit 'c162cb607344b842ab470d124685fc1ed2b39471'

e6a356f

WIP on proper uring RX task finalization

59a60cf

Develop uring rx task control

4258fac

Optimize buffer reclamation signalling

bfbdcc3

Update Cargo.toml

5912f9d

- optimize uring operation in Zenoh

2015d90

- fix buffer reclamation bug

- add "uring" feature

6f55604

- integrate uring support for most links - make automatic read mode selection (uring or tokio) - code format

Merge commit '0682bc526fdd0b19dc9eb1d5ecdbbd344ace8533'

a0059e3

fix compilation without uring featuire

ab94ba1

fix missong feature check

1ac2053

Add uring feature to CI

915fc6f

fix typos

657b986

typos

8bb5bee

Make uring batches configurable

3ae8f40

yellowhatter added 6 commits February 10, 2026 02:16

Update reader.rs and manager.rs

2a1989b

- significantly improve RX batch reclamation

919ec65

- make growing RX batch memory (to optimize mem footprint and support zero-copy for big payloads)

- little brush-up for uring reader code

0d1f5f6

- exponential grow for uring batch arena - tune RX arena size based on config

Merge commit '8ed18988cb0d0ddd1181d9d804ea97a32038f7cc'

feba6b1

Conflicts: Cargo.lock

- improve uring error handling

9258bd4

- add async wait for uring-global errors (as opposed to rx-task-related errors) - supply uring thread with tokio executor context to be compatible with tokio-aware user code

Merge commit '7d9233912ed393c4230dcad78c72b13ad7714790'

9918768

Conflicts: io/zenoh-transport/src/unicast/universal/link.rs

Merge commit 'd182f9328ec9a8bf435137d58ef0c99e62f74b2a'

f3c7df2

yellowhatter added 4 commits April 17, 2026 18:36

fix clippy

dc33bcc

- fix clippy

44d27df

- support transport_compression for io_uring - fix stats for io_uring

- rustfmt

944f8c3

Spelling

a66c513

yellowhatter marked this pull request as ready for review April 21, 2026 08:26

yellowhatter changed the title ~~WIP on io_uring~~ Support io_uring Apr 21, 2026

yellowhatter added 2 commits April 21, 2026 11:38

Format Cargo.toml

f554572

Merge commit 'fe7a78ebcfcb0e2c57c5d00a89082a1a9c730869'

354209b

yellowhatter added 9 commits April 27, 2026 13:25

Merge commit '7792ebbb2fb0c8311e51419994171cf91fb619d7'

5181bc1

Conflicts: Cargo.lock Cargo.toml zenoh-ext/tests/liveliness.rs

format Cargo.toml

b6d5074

Merge commit '77507c12b883e80d1b5d08604935502725a8f00d'

772b6d2

Conflicts: Cargo.lock Cargo.toml

Merge commit '0aa75786ad1044ae6b90dd199a5f3958d6580541'

21203b8

- Optimize bufer reclamation

2dca3c1

- Optimize memory fragmentation - Optimize main read loop - Optimnize zbuf reader

Merge commit 'aa4767626d5893bb1e931482aa99f7b6307cc9c2'

54bd9a9

Merge commit '692a0c7ca4402050cc4dbe8f3b20a6916c00b4de'

596ca61

Fix bug with uring cmd processing

1215544

Merge commit 'e03b0c0ec4716c0500b4fcdaceb89570381011b0'

caca5f0

YuanYuYuan added 3 commits June 12, 2026 16:58

YuanYuYuan mentioned this pull request Jun 12, 2026

fix(uring): review fixups for eclipse-zenoh/zenoh#2332 ZettaScaleLabs/zenoh#31

Merged

YuanYuYuan and others added 2 commits June 12, 2026 22:59

Merge pull request #31 from ZettaScaleLabs/PR-local/2332

4487490

fix(uring): review fixups for eclipse-zenoh#2332

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support io_uring#2332

Support io_uring#2332
yellowhatter wants to merge 99 commits into
eclipse-zenoh:mainfrom
ZettaScaleLabs:io_uring

yellowhatter commented Dec 23, 2025 •

edited by github-actions Bot

Loading

Uh oh!

codecov Bot commented Feb 9, 2026 •

edited

Loading

Uh oh!

yellowhatter commented Apr 17, 2026

Uh oh!

yellowhatter commented Apr 17, 2026

Uh oh!

yellowhatter commented Apr 17, 2026

Uh oh!

yellowhatter commented Apr 22, 2026

Uh oh!

yellowhatter commented Jun 1, 2026

Uh oh!

YuanYuYuan commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

yellowhatter commented Dec 23, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What this changes

Transport integration

Link coverage

Buffer and memory handling

Reader / writer path

Error handling and runtime integration

Build / CI / test coverage

Design notes

Expected user impact

Validation

🏷️ Label-Based Checklist

✨ Enhancement Requirements

Uh oh!

codecov Bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

yellowhatter commented Apr 17, 2026

Uh oh!

yellowhatter commented Apr 17, 2026

Uh oh!

yellowhatter commented Apr 17, 2026

Uh oh!

yellowhatter commented Apr 22, 2026

Uh oh!

yellowhatter commented Jun 1, 2026

Uh oh!

YuanYuYuan commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yellowhatter commented Dec 23, 2025 •

edited by github-actions Bot

Loading

codecov Bot commented Feb 9, 2026 •

edited

Loading