Skip to main content

Lanes

One subscription reads one queue through one pump; workers(n, by_key) spreads its messages over lanes keyed by the FIFO message group.

One subscription's dispatch: a FIFO queue, one pump, one stream and two lanes keyed by message groupQueue orders.fifomessage groups alice, bob and carolPumpone receive ahead of the handlersSqsSubscriber streamone message at a timeworkers(2, by_key)lane = hash of the message groupLane 1alice and carol,each in orderLane 2bob, in orderA standard queue carries no group,so its messages rotate over the lanesReplicas of the service poll the same queue,and SQS hands each message to one of them
The diagram as text
  1. Queue orders.fifo message groups alice, bob and carol → Pump one receive ahead of the handlers: ReceiveMessage
  2. Pump one receive ahead of the handlers → SqsSubscriber stream one message at a time: a batch
  3. SqsSubscriber stream one message at a time → workers(2, by_key) lane = hash of the message group: one at a time
  4. workers(2, by_key) lane = hash of the message group → Lane 1 alice and carol, each in order
  5. workers(2, by_key) lane = hash of the message group → Lane 2 bob, in order
  6. A standard queue carries no group, so its messages rotate over the lanes
  7. Replicas of the service poll the same queue, and SQS hands each message to one of them

A subscription's stream yields one message at a time. Without workers, one loop runs the handler for each message in turn, and nothing runs side by side. workers(n) runs up to n handlers at once, in no particular order.

workers(n, by_key) runs n lanes, and a message goes to the lane its key hashes to. The key is the message's PARTITION_KEY_HEADER, which holds its FIFO message group. So a group never spreads over two lanes, and the order Groups keeps on the queue is kept in the service. Lanes fewer than groups serve several groups each. A standard queue has no group, so its messages have no key and rotate over the lanes.

The pump stays at most one receive ahead of the handlers. A message it received and has not handed over yet is kept invisible by its extender meanwhile. A FIFO queue also holds back a group while one of its messages is in flight, which keeps a group's next message out of the service until the previous one settles or its timeout lapses.

Several replicas of a service, or several subscriptions on one queue, compete for its messages: SQS hands each message to one of them. The in-process transport keeps the order of a standard queue, which SQS does not, so a test that asserts order uses a FIFO queue.

A batch handler takes one receive at a time, up to the size the mount site names and at most ten, so a batch is often smaller than that size.