Module dispatch_deque 

DequeDispatcher - per-call routing across the MMF-deque family.

The dispatcher owns one handle of each SharedDeque / SharedDequeKhpd / SharedDequeLoh / SharedDequeUrd variant that the host has configured, and picks the right one per call based on a caller-supplied WorkloadShape.

The routing decision

No single variant wins every workload shape. The right pick depends on (a) whether the producer batches or dispatches per-item, (b) how many thieves the workload runs, and (c) whether the caller wants the consumer to halt the logical CPU between batches via WAITPKG.

Workload	Pick	Why
Per-item dispatch, single thief	ChaseLev	Lowest constant per push; no batch to amortize.
Producer batches K = 2..128 items per call	Khpd	3 items per Release-store on the publication line; empirically the best per-item cost on Zen+/Zen 4 at this scale.
Producer batches K >= 128 items per call	Loh	1 tail.fetch_add(K) amortizes across the whole batch.
Multiple thieves AND batched producer	Urd	Per-thief mailbox = zero CAS contention.
Multiple thieves AND wait_idle=true	Urd	Hardware-mediated wake via WAITPKG / PAUSE-spin.

The routing table is a starting point. Per-host calibration may flip individual cells. Callers that already know which variant they want may call the per-variant getters (DequeDispatcher::chase_lev, etc.) directly.

Cross-process E2E

A DequeDispatcher lives in the producer process. Each variant it owns is backed by its own MMF file path; consumer processes open those same paths to drain. See the dispatcher_demo example for the parent/child split.

Structs

DequeDispatcher

MMF-backed dispatcher across the deque family.

DispatcherBuilder

Builder for DequeDispatcher.

WorkloadShape

Caller-supplied workload shape feeding the routing decision.

Enums

DequeVariant

The deque-family variants the dispatcher routes across.

DispatchError

Errors from the dispatcher’s send-side methods.