Skip to main content

Module inputs

Module inputs 

Source
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§

InputPlaneStats
Counters describing what the consumer-side plane has done.
InputRouteTable
Every input’s plane state, and the reader threads behind the attached ones.

Constants§

MAX_CONSECUTIVE_LAGS
How many consecutive RecvError::Lagged reports 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 InputRouteUpgrade names and attaches a reader to it.