Expand description
The slow-start route handshake, consumer side (blueprint §6.2, §6.3).
super::routes is the producer’s half: a RouteUpgrade arrives, a
astrs_shm::Producer is opened, and every later publish writes into a
ring slot. This module is the other half, and it is the one that makes the
plane actually engage: a route is only upgraded once “all static same-host
consumers attached to the ring” (§6.3), so until a consumer attaches by
itself, nothing ever moves off the daemon path.
InputRouteUpgrade{input, source, segment}
│
▼
SegmentClient::attach ──► astrs_shm::Consumer ──► reader thread
│ │
│ doorbell registered with the broker │ Payload::zero_copy
▼ ▼
the daemon observes the pid in the consumer table the node's input queue
│
▼
RouteUpgrade to the producer — §6.3 completes§Why attaching early is safe
The daemon sends InputRouteUpgrade before the producer is offered its
own upgrade, because the producer’s offer is gated on observing this
consumer in the segment’s consumer table. So a consumer always attaches
while the producer is still publishing through the daemon — and the ring is
therefore empty. astrs_shm::StartPosition::Latest puts the cursor at the
next write, so the transition can neither duplicate a message the daemon
already delivered nor skip the first one the ring carries.
§What still arrives on the daemon path
An upgraded route is not a ring only. §6.2 keeps the threshold rule — “a
heap payload ≥ threshold is copied once into a slot; below threshold it
rides the UDS control channel” — so a producer on the shared-memory plane
still publishes its small messages through the daemon, and so does one
whose ring was momentarily full (§6.2: never sleep-retry). Both arrive
here as ordinary astrs_wire::NodeEvent::Input frames on the same input
queue. A node sees one stream; crate::Payload::is_zero_copy is the only
thing that differs.
The consequence worth stating plainly: on an output that publishes payloads on both sides of the threshold, the two carriers have different latencies and the relative order of a large and a small message is not guaranteed. An output whose payloads are uniformly sized — the normal case, since a port carries one type — stays on one carrier and stays in order.
§Falling back is a detach
Every fatal condition ends the same way: the astrs_shm::Consumer is
dropped, which releases its consumer-table entry, which the daemon’s next
plane pass observes as a detachment — and a detached consumer downgrades
the producer, which resumes publishing through the daemon (§6.3). The node
keeps reading the same event stream throughout. Nothing has to be
negotiated for the fallback to be correct; it falls out of the handshake.
§Holding a sample holds a slot, and that is fine
A queued crate::Payload on the zero-copy plane pins the ring slot it
points at, so a node that reads slowly holds slots its producer cannot
refill. That sounds like a way to stall a producer, and it is worth being
explicit about why it is not.
Two bounds close it. The consumer’s queue policy (§11.2) caps how many
events can be outstanding at once — a queue_size: 4 input pins at most
four slots, whatever the node does — and the producer’s reaction to a ring
with no free slot is astrs_shm::Producer::try_allocate failing, which
the node API turns into §6.2’s documented fallback: publish inline, count
shm_fallback_total, carry on. Nothing waits, so nothing stalls.
An earlier version of this module copied payloads out of their slots once
an input’s queue passed a threshold, to “protect” the producer. It bought
nothing the two bounds above do not already give, and it cost the thing the
plane exists for: a consumer that fell briefly behind started copying every
frame, which made it slower, which kept it behind. The copy is still
available — crate::Payload::detach — to the node, which knows whether
it is about to stash the payload and is the right place for the decision.
Structs§
- Input
Plane Stats - Counters describing what the consumer-side plane has done.
- Input
Route Table - Every input’s plane state, and the reader threads behind the attached ones.
Constants§
- MAX_
CONSECUTIVE_ LAGS - How many consecutive
RecvError::Laggedreports end the attachment. - RECV_
SLICE - How long one blocking receive parks on the doorbell before the reader looks at its stop flag again.
Functions§
- open_
consumer - Opens the segment an
InputRouteUpgradenames and attaches a reader to it.