SO_REUSEPORT_LB / receive-CPU affinity / overview
A connection's locality is decided twice. The NIC and iflib decide, at attach, which CPU every packet of a flow will be processed on; the socket layer decides, once at the SYN, which worker gets the connection. The exact-claim design only ever touched the second decision and so could not use more workers than receive queues. This page draws both decisions and what we learned by measuring them: where packets land is a placement policy, where connections go is a dealing policy, and the measured cost that matters is crossing an L3 group.
The change has three parts. iflib gains an optional spread of queue CPUs across cache groups. The load-balancing group gains a dealt map that serves every worker from the nearest receiving CPU with an equal share. accept(2) learns both which CPUs receive and where each worker runs, so unmodified servers get all of it.
Measured 2026. On this host (Ryzen 9 5950X, two CCDs on one package) the expensive hop is cross-CCD: it costs +19% cycles per request, and the exact-claim predecessor gained up to -15% with workers spanning both CCDs (affinity vs hash). On the two-socket Xeon E5-2470 v2 (two sockets over QPI) the ring deal itself was run: with receive spanning both sockets and one worker per receive CPU across both, it cut cross-CPU wakeups from ~292k to ~15k and cycles per request by 11.3% against a plain hash - the same win as exact-claim while starving no worker and needing no application change. Same-socket, the automatic accept(2) learning co-located ~96% of connections. Caveat: supply is learned in two ten-second windows, so runs shorter than that under-converge. The September runs predate the hash mix, the HPTS CPU choice and the balance sysctl. Ring detail: distance rings.
| part | touches | delivers | measured |
|---|---|---|---|
| 1. queue spread | sys/net/iflib.c: an order array built at attach, cpuid_advance() walking it, a cursor keyed by the set and the order, tunable dev.X.Y.iflib.core_spread | queues on every cache group of the local domain; default off, numeric order unchanged | not yet run on hardware; on the 5950X the order is 0, 16, 2, 18, 4, 20, 6, 22 |
| 2. the deal | in_pcb_var.h, in_pcb.h, in_pcb.c, in6_pcb.c | the dealt map and the selection; tagged CPUs stand in as receive CPUs until a handshake is counted; net.inet.tcp.reuseport_lb_balance (on by default) for equal shares | 2026-09-26, two-socket Xeon, receive on both sockets: -11.3% cycles per request against the hash, every worker used |
| 3. learning at accept(2) | protosw.h (pr_accepted), uipc_syscalls.c, tcp_usrreq.c, tcp_syncache.c, tcp_var.h, mbuf.h (M_HASHTYPE_ISRSS) | counts, windows, tag capture from pinned threads, the new connection's HPTS CPU, net.inet.tcp.reuseport_lb_accept_cpu (on by default); unmodified servers get everything | 2026-09-26, one socket: ~96% of connections co-located, no application change |
| situation | what happens |
|---|---|
| no member is tagged | no map is built; selection and cost are identical to today |
| workers are tagged but nothing is counted (a NIC that reports no hash, such as bhyve e1000 or vtnet; loopback) | the tagged CPUs stand in as receive CPUs with equal supply, so each deals only to its own nearest members; a SYN on a tagged CPU goes to that CPU's workers, a SYN elsewhere hashes. With one worker per CPU and the SYNs on a few CPUs, the other workers get nothing |
| something counted, a tag names a CPU that never receives | that member is dealt from the nearest receiving CPU; a tag cannot starve anyone |
| UDP | no accept(2), so nothing is tagged and the group keeps the hash |
| a packet arrives on a CPU with no slots (loopback, a stray netisr CPU) | hash over all members |
| two members tag the same CPU | both filled from it when its supply covers them; otherwise the later one takes its quota from the next ring |
| one receive queue, thirty-two workers | all thirty-two are dealt from that CPU: the same distribution as the hash |
| queues or NICs receive at different rates | supply follows the counts; a trickle CPU supplies a trickle and its workers get the rest elsewhere |
| all queues on one L3, workers on every CPU | the far workers are dealt from the nearest L3 that receives; only placement (the spread) can do better |
net.inet.tcp.reuseport_lb_balance=0 | every member is owed the whole table, so each receive CPU's connections stay with its nearest listener and farther ones can get nothing, as under the exact claim; equal shares are the default |
| a member joins or leaves, or is tagged; the map allocation fails | remap in the same critical section, old map freed after an epoch; on failure the map is NULL, the hash takes over, the next trigger retries |
| an unbound netisr thread carries the traffic (deferred dispatch, options RSS without the netisr dispatch fix) | counts follow the thread; after it migrates, flows on the new CPU hash until it is counted, then at most two windows of skew; the precondition of a per-flow-stable CPU is unchanged |
| single-L3 machine with one interrupt thread per core, or a kernel without SMP | the spread order equals the numeric order; the rings are exact, the SMT sibling where there is one, then everyone |
| two sockets, NIC local to one | the spread interleaves the local socket's cache groups and never crosses to the other, since the interrupt set is already the local domain; with one L3 per socket, as on the two-socket Xeon, the order is unchanged |
reuseport_lb_balance=0 lifts); supply is proportional to observed handshakes, each CPU fills its ring in tag order, and the last ring closes the deal.