Module correlation 

Request/reply correlation for a service client — issue 2009.

ClientTrait::send_request_raw hands back the id the backend assigned to a request and ClientTrait::take_response_raw hands back the id of the request a reply answers (issue 0778). This module is the ONE place that decides what a client does with the pair, so every surface that takes a reply — the Rust Promise, the executor’s callback clients, the action client’s three sub-clients, the C and C++ blocking paths — applies the same rule:

• a reply is delivered only to the request whose id it carries;
• a reply whose request is not pending — cancelled, abandoned, timed out, or a duplicate of one already answered — is DROPPED, never handed to the next request the client sends;
• a backend that cannot supply ids (SEQUENCE_ID_UNKNOWN) gets a defined behaviour instead of a guess: one request in flight per client, and a reply without an id is delivered only when exactly one request is pending.

Bounded and allocation-free: a RequestCorrelator is a fixed table of N (id, key) pairs held inline by the client that owns it. A full table refuses the next send (SendRefusal::Full) before anything reaches the wire, so a request is never sent that its reply could not be matched to.

The C++ rclcpp::Future keeps several requests in flight on ONE client with a reply buffer per future; it applies this same rule over an intrusive list of its futures (rclcpp/future.hpp), because the buffers it delivers into live in the futures, not in the client.

Structs

RequestCorrelator

A fixed table of the requests a client has in flight, each keyed by the sequence id the backend assigned and carrying a caller-chosen K (() for a plain service client, the GoalUuid for an action sub-client).

Enums

SendRefusal

Why a send was refused BEFORE it reached the backend.

Constants

MAX_STALE_DRAIN_PER_POLL

How many stale replies one take_correlated call drops before it gives up for this poll and reports “nothing yet”. Bounds the work a burst of stray replies can make a single poll do; the rest are dropped by the next poll.

SEQUENCE_ID_UNKNOWN

The id a backend reports when it cannot supply one — the Rust spelling of the ABI’s NROS_RMW_SEQUENCE_ID_UNKNOWN (INT64_MIN). The C vtable adapter pre-sets both out-parameters to it, so a backend that never writes them reads as “no id” rather than as id 0, which is a legal id.

Traits

ReplyMatcher

Type-erased RequestCorrelator::resolve, so one Promise type can poll a plain service client and an action sub-client alike.

Functions

take_correlated

Take the next reply that answers a pending request, dropping stale ones.

take_matched

take_correlated through the type-erased ReplyMatcher.