feat(hiroz): add a payload pool for reusable message allocations

[YuanYuYuan]

Closes the payload-pool design issue. Part of the intra-process meta issue.

Note

Stacked on #340, which adds the intra-process bus this pool feeds. The base is feat/publisher-locality, so the diff here is the pool alone. #340 merges first.

PayloadPool gives hiroz the largest measured win on the intra-process branch, as a feature rather than as a pattern a user must reimplement.

let mut pool = PayloadPool::new(16, ByteMultiArray::default);
let Some(mut msg) = pool.acquire() else { return Ok(()) };  // never allocates
msg.stamp = now;                                            // written in place
publisher.publish_shared(msg.into_shared())?;

What this adds

It was thirty lines of benchmark code over one feature-gated accessor. It is now crates/hiroz/src/payload_pool.rs, and the benchmark's hand-rolled ring is deleted rather than bypassed.

let mut pool = PayloadPool::new(16, ByteMultiArray::default);
let Some(mut msg) = pool.acquire() else { return Ok(()) };  // never allocates
msg.stamp = now;                                            // written in place
publisher.publish_shared(msg.into_shared())?;

The module names no zenoh type, so it builds against released zenoh. Only rewriting a ZBuf's bytes in place still needs the unreleased accessor — and that no longer involves hiroz at all: #340 removes the wrapper, and a caller reaches zenoh's opt_mut_slice through ZBuf's inner type with its own [patch].

property	how
acquire never allocates	returns None; an invisible fallback is the defect it exists to prevent
a Weak cannot panic the sender	Arc::get_mut is the test, not strong_count then expect
a retained Arc is visible	PoolStats::stuck, warned once per slot rather than per send
no blocking acquire	delivery is inline, so the party freeing a slot is often the caller

7 unit tests plus 5 compatibility tests. Every defect it prevents has a detector proven to fail without it, each compiling — a revert that does not build is indistinguishable from a firing detector otherwise:

revert	test that failed
strong_count + expect	a_weak_reference_is_skipped_rather_than_panicking
no stuck accounting	a_retained_arc_removes_a_slot_and_is_eventually_reported
silent allocating fallback	exhaustion_returns_none_and_never_allocates (+2)
a fresh allocation per acquire	a_slot_is_reused_rather_than_reallocated

It composes with the rest of hiroz

payload_pool.rs carries 7 unit tests for the ring itself — acquisition, reuse, exhaustion, the stuck-slot report. payload_pool_compat.rs adds 5 for how it composes with publishers, QoS and fan-out, all green. Each concludes "nothing downstream retained the buffer" from available returning to capacity — and that is not vacuous: retaining the published Arc reds the wire test and only the wire test.

works with	why
the wire, and SHM	serialization writes a fresh ZBuf, so the transport queues a copy
TRANSIENT_LOCAL	the durability cache holds serialized samples, not the Arc<T>
Locality::Remote	bus and wire both release before publish_shared returns
many subscribers	one Arc shared — fan-out costs one slot, not N
a callback republishing from the same pool	into_shared consumes the guard, ending the borrow before the publish

Not publish_owned, which takes T by value and gives the message away — the opposite of pooling. (#342 renames it publish_moved.)

How this differs from the pool rmw_zenoh_cpp already has

rmw_zenoh_cpp::BufferPool (detail/zenoh_utils.hpp) pools the buffer that serialization writes into — the CDR destination, recycled with a deleter, mutex-guarded, capped at 8 MiB to stay cache-resident, used when SHM is unavailable.

	rmw_zenoh_cpp::BufferPool	the pool measured here
pools	the buffer serialization writes into	the user message itself
removes	one allocation of the CDR output	the allocation and the serialization
layer	inside the rmw, invisible to the user	above the middleware
exhaustion	falls back to the allocator silently	the caller decides

They are complementary rather than competing: one makes serializing cheaper, the other avoids serializing.

rmw_zenoh has no intra-process path of its own. The only mentions in its source set message_info->from_intra_process = false. rclcpp's intra-process comms sit above the rmw and bypass it — which is what the benchmark shows: rclcpp_ipc 13.0 µs against 26.1 µs for the same binary with the middleware back in the path.

Does this need a patched zenoh?

The pool does not. The module names no zenoh type; Arc::get_mut is std. Its seven unit tests pass with no features enabled.

Only rewriting the bytes inside an existing ZBuf does, and that is a zenoh-buffers patch the caller supplies, not a hiroz feature. So a pooled message whose fields are plain — a String, a fixed array, a Vec replaced wholesale — works against released zenoh today.

Measured both ways, on a pinned host, median of three interleaved runs:

200 Hz	plain Vec<u8>, no patch	ZBuf, with patch
128 KiB	−94.6%	−93.7%
1 MiB	−99.0%	−99.1%

The same win either way, so the patch is not what produces it. Control (an unchanged binary in the same sweep) moved 0.7–3.1%.

Warning

At 64 B pooling is a small loss, not a win: +17.3% p50 and +8.5% min, above the control. Pooling is for large payloads. The two pooled arms above must not be compared against each other — they differ in message type, container and write path at once, so the difference between them is unattributable.

Breaking changes

change	who is affected	before → after
pooled-payload feature removed (in #340)	workspaces enabling it	drop the feature; patch zenoh-buffers and call opt_mut_slice on ZBuf's inner type

Nothing else. PayloadPool is additive, and no hiroz code path calls the gated accessor.

What fails without this

Nothing. No failing baseline: this adds a capability. The justification is the caller it serves — a publisher that reuses one buffer instead of allocating per send — and the −99% that reuse is worth at 1 MiB.

Evidence

Sweep F — the first sweep whose pooled arm publishes through PayloadPool rather than the benchmark's own ring. 70 cells, 3 interleaved runs, 0 failures, 0 fallbacks; controls drifted 0.9% median over 21 unchanged cells.

200 Hz	hiroz(zc)	hiroz(zc,pool)	change
64 B	0.404	0.405	+0.2%
128 KiB	8.162	0.454	−94.4%
1 MiB	54.102	0.424	−99.2%

The public API is measurably slower than the private ring it replaces: min rose 17–25% across all three payloads (0.234 → 0.288 µs), consistent in sign and size and well outside control drift. That is a real regression, stated rather than omitted. It buys the Weak safety, the visible exhaustion and the stuck reporting above. The likely mechanism — Arc::get_mut reads the weak count too, and the pool keeps three parallel vectors where the ring kept one — is a hypothesis, not a measurement.

Seven unit tests plus five compatibility tests. Every defect the pool prevents has a detector proven to fail without it, and every reverted build reported zero compile errors — cargo exits 101 for a build failure and a test failure alike, so a revert that never compiled looks exactly like a detector that fired.

[Copilot]

🟡 Changes recommended

The re-entrancy test uses separate pools and retains the relevant mutex across publishing, so it does not validate the documented same-pool behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a fixed-capacity Arc<T> payload pool for allocation reuse on intra-process publishing paths.

Changes:

• Introduces pool acquisition, statistics, and stuck-slot detection.
• Exports the API publicly and through the prelude.
• Adds unit and publisher compatibility tests.

File summaries

File	Description
crates/hiroz/src/payload_pool.rs	Implements the reusable payload pool.
crates/hiroz/src/lib.rs	Exposes the new module.
crates/hiroz/src/prelude.rs	Re-exports pool types.
crates/hiroz-tests/tests/payload_pool_compat.rs	Tests publisher and QoS integration.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.