nros rmw-cffi
C vtable for plugging a third-party RMW backend into nros
Loading...
Searching...
No Matches
rmw_subscription_options_t Struct Reference

#include <rmw_entity.h>

Data Fields

uint32_t arrival_rate_mhz
uint32_t rx_buffer_hint

Detailed Description

Subscription creation options — the home for subscription-side transport hints (upstream: rmw_subscription_options_t). Passed as a NULLable trailing param to create_subscription; NULL = all defaults.

Field Documentation

◆ arrival_rate_mhz

uint32_t rmw_subscription_options_t::arrival_rate_mhz

Phase-519 W3 (RFC-0074, "On XRCE") — the rate this subscription DECLARED it can take, arrival_curve.rate_hz, in millihertz. 0 = undeclared, which is what every caller that names nothing passes, so the field took the old _reserved[4] bytes and the struct is the same 8 bytes it was.

  • ADVISORY, like rx_buffer_hint. A backend MAY ignore it. zenoh does: its enforcement point 1 is the router's downsampling rule, which a deployment step installs, so the device has nothing to ask for.
  • The XRCE backend asks the agent for max_bytes_per_second = rate_hz x rx_buffer_hint, and only when that is safe to ask for: rate_hz >= 1 (the agent's token bucket holds one second of the rate, and a sample bigger than the bucket stops the stream for good), a non-zero rx_buffer_hint, and a product that fits the wire field's uint16_t. Otherwise it asks for everything, as before, and logs why.
  • IT PACES, IT DOES NOT FILTER. The agent takes a sample and then waits for tokens, so what arrives is up to one period (1 / rate_hz) old, plus more for every sample the agent-side reader's history holds. Measured in RFC-0074: median age 104 ms at depth 1 for a 10 Hz declaration, against 0.2 ms unpaced.

◆ rx_buffer_hint

uint32_t rmw_subscription_options_t::rx_buffer_hint

Phase 231 (RFC-0038) — receive-buffer size hint, bytes, so a size-classing backend (zenoh-pico) can pick a small/large receive buffer. 0 = unset. A transport hint, not a DDS policy.

Phase 403 W1 — the paragraph above is what this field MEANS; the rules below are what it OBLIGES, and they are normative. They were prose in RFC-0005 ("Receive-buffer sizing: what a backend is obliged to do") and nowhere else, so a third party reading only this header could not tell whether ignoring the hint was conformant. It is.

  • ADVISORY. A backend MAY ignore this field entirely. A backend with a single receive-buffer size is conformant, and so is one that rounds 68 up to 1024.
  • 0 IS "THIS CALLER SAID NOTHING", NOT "THIS TYPE HAS NO BOUND". Every message type carries a derived upper bound — bounded in the .msg (string<=64) or capped in nros-codegen.toml, and an unbounded type is a BUILD ERROR rather than something that falls back to a configured default — so the runtime always has a number to put here. 0 therefore reaches a backend only from a caller that supplied no options at all (options == NULL, or a zero-filled struct from a hand-rolled C caller). A backend must never read it as a claim that the type is unbounded, and must not treat a non-zero hint as a tighter bound than the type's own.
  • IT IS NOT THE TAKE BUFFER. take's buf / buf_len are owned by the RUNTIME, and buf_len is authoritative on every call — including when it disagrees with this hint, and when it changes between calls for the same subscription. A backend must not cache a length from here and write buf against it.
  • MUST NOT LIE. A backend MUST NOT copy a sample that does not fit the caller's take buffer and return NROS_RMW_RET_OK. A sample larger than buf_len is reported as a failure — *taken = false with NROS_RMW_RET_BUFFER_TOO_SMALL — never as a truncated success. The runtime turns that into a diagnostic naming the buffer (report_dropped_take); a silent truncation is a corrupt message with no symptom at all. This is the ONE guarantee the hint carries, and it holds whether or not the backend honoured the hint.
  • NOT A WIRE BOUND. A remote publisher is bound by the .msg, never by our config, so this is no promise about incoming sample size. A backend must not size a fixed structure from it in a way that makes a larger sample undeliverable WITHOUT a diagnostic.

There is no reverse channel: the vtable's required_rx_bytes query (a backend saying what it would rather the take buffer were) was deleted unread — see the note where it stood in rmw_vtable.h.

The documentation for this struct was generated from the following file: