SO_REUSEPORT_LB / receive-CPU affinity / the deal in detail

Distance Rings

detail of the deal, in_pcblbgroup_remap() hardware-validated on a two-socket Ivy Bridge machine (Xeon E5-2470 v2) 2026-09-14, validated 2026-09-26

A receiving CPU spends its connections on the workers nearest to it, and "nearest" is not a number this design invents. It is read from the tree the scheduler already built to describe the machine. Ring 0 is the CPU itself; each ring after that is one step up that tree; and one final ring catches whatever is left so the deal always closes.

The drawings use the two-socket machine the deal was validated on, where each socket is its own NUMA domain with its own L3. There that comes to four rings: the CPU, its SMT sibling, the rest of its socket, and a last ring, the catch-all, that admits anyone still owed, which here means the other socket, plus any member that named no CPU. On a different machine it is a different number: the rings are however deep that machine's tree is, and the code asks rather than assumes.

Where a ring comes from

The chain the code walks, for CPU 2 on a two-socket Xeon E5-2470 v2 (CPUs 0-39) smp_topo_find(cpu_top, 2) the leaf group holding CPU 2 NUMA domain 0 socket 0 and its L3, CPUs 0-19 root, both sockets CPUs 0-39, joined by QPI NULL chain ends What each step becomes ring 0tag == cpu ring 1leaf mask, {2,3} ring 2domain mask, {0-19} ring 3, the last passanyone owed: {20-39}, untagged the root yields no mask; the last pass stands in for it What reads it in_pcblbgroup_ring(cpu, n)the n-th group's cg_mask, or NULL at or past the root in_pcblbgroup_remap()calls it until NULL: nlevels = 3 here, so level 3 is the last pass Each arrow is one cg_parent step. A member is in ring n of cpu when its tag is set in that mask. Ring 0 is tested against the CPU id itself rather than a mask, because a member that named this very CPU has to be settled before anything sharing its core can take the slots. The root's mask would admit every tagged member, which the last pass already does, so the walk stops one short of it. The walk is #ifdef SMP: cpu_top and smp_topo_find exist only there. Without SMP the chain is empty, and only ring 0 and the last pass remain.
The rings are the scheduler's group chain, numbered. There is no table of cache levels in this code and no assumption about how many there are. It walks from the leaf group containing the CPU up through cg_parent, and the n-th group below the root is ring n; a last pass then admits anyone still owed. On this machine the NUMA domain and the L3 are the same group, so ring 2 is the socket and the last pass is the other socket. A machine that reports more levels gets more rings; one that reports none gets two.

The four rings from CPU 2, drawn to what they cost

CPU 2 ring 0 ring 1 ring 2, socket 0 ring 3, socket 1 across QPI ring 0 the CPU itself members whose tag is 2, 1 CPU wakes locally, the cheapest there is ring 1 its SMT sibling the leaf group {2, 3}, 1 further CPU shares its core's L1 and L2 ring 2 the rest of its socket NUMA domain 0, {0-19}, 18 further CPUs shares L3 and memory; one reschedule IPI per wakeup; cycles per request measured flat ring 3 the last pass: anyone still owed NUMA domain 1, {20-39}, 20 further CPUs, and members that named no CPU, so the deal always closes crosses QPI: co-located vs far socket, -18.1% cycles per request The root is not walked as a ring: its mask covers every tagged member, which the last pass already admits. A machine with more levels below the root, such as several L3 groups per socket, gets more rings before the last pass.
Each ring is strictly larger than the last, and the cost steps once. Rings 0 and 1 are free relative to each other. Ring 2 keeps the data in the same L3 and memory but takes an inter-processor interrupt to wake the worker. Ring 3 is the only expensive step on this machine: it crosses QPI into the other NUMA domain. A receive CPU reaches it only when no member on its own socket is still owed, so when each socket's share of receive matches its share of workers, as on the validated run (one NIC local to each domain, one worker per receive CPU), each socket's connections stay on that socket. Queue spread does not supply that, as it never leaves the NIC's local domain.

A deal, traced ring by ring

One L3 group, 4 cores x 2 threads. Receive CPUs 0 and 2. Six workers, tagged 0 to 5. 96 slots: 48 per receive CPU, 16 owed to each worker. supply left deficit left, worker 0 to 5 what this pass did start 48 48 16 16 16 16 16 16 nothing dealt yet level 0 exact 32 32 016016 16 16 cpu0 to worker 0 (16), cpu2 to worker 2 (16) level 1 sibling 16 16 000016 16 cpu0 to worker 1 (16), cpu2 to worker 3 (16) level 2 last pass 0 0 000000 cpu0 to worker 4 (16), cpu2 to worker 5 (16) Every worker ends with 16 of the 96 slots, one sixth of the connections, and no worker was served from further away than it had to be. This machine's chain is the leaf and the root, so ring 1 is the only mask and level 2 is the last pass. The L3 group is the root here, so the last pass is the same L3. The loop that produced it for level in 0 .. nlevels: outermost, so no ring is entered before every CPU has finished the one before for each receiving CPU with supply: in CPU id order for each member still owed, in tag order: give it min(deficit, supply)
Levels outermost is the whole of the policy. Each pass lets every receiving CPU settle the members at one distance before any CPU is allowed to look further. Within a pass the receiving CPUs are taken in CPU order and the members in tag order, so the result depends on the machine and the tags; join order only breaks ties between equal tags.

Why the loops are nested that way round

Levels outermost, as the code walks them level 0: cpu0 takes worker 0 cpu2 takes worker 2 level 1: cpu0 takes worker 1 cpu2 takes worker 3 level 2: cpu0 takes worker 4 cpu2 takes worker 5 every worker that named a receiving CPU is served by it CPUs outermost, the mistake it avoids cpu0: worker 0, then worker 1, then worker 2 and worker 3 at ring 2, using up its slots cpu2: worker 2 already satisfied, takes 4 and 5 instead worker 2 named cpu2 and is served by cpu0 anyway Both orders deal every slot and give every worker an equal share. The difference is only locality, and it is not small: in the right-hand order a worker that named the very CPU its connections arrive on can be served from another core entirely, which is the property the whole design exists to provide. The same argument applies at every ring, not just the first: a CPU must not reach into ring n+1 while any CPU still has ring n business, or it can take a worker that a nearer CPU was about to claim. Cost of the ordering: the level loop runs nlevels + 1 times over the receiving CPUs, so the whole deal is about (nlevels + 1) x CPUs x members cheap set tests, typically 4 x 8 x 32, on membership, tag and count changes, never on the packet path.
The nesting is what makes "nearest" true rather than approximate. Reversing the loops would still balance the load and still fill every slot, so a test that only checked shares would pass either way. That is why the invariant asserted alongside the balance one is that an exact match is never displaced.

Machines where the rings are not four

machinechain from a leafrings that mean somethingwhat the deal does
2x Xeon E5-2470 v2 (two sockets, two NUMA domains)SMT pair, socket (its NUMA domain and L3), root0 exact, 1 sibling, 2 same socket, 3 last pass: the other socket (QPI)the worked example above; validated 2026-09-26: receive on both sockets, deal -11.3% cyc/req vs hash, no worker starved
this host, 5950X (two CCDs, one NUMA domain)SMT pair, L3 group, root0 exact, 1 sibling, 2 same L3, 3 last pass: the other CCDthe same four rings, with a CCD in place of a socket
one L3, no SMTroot only (a one-CPU core is not a group)0 exact, 1 same L3exact first, then anyone in the group
flat topology (smp_topo_none)root only0 exact, 1 everyonedegrades to exact-or-share, which is the honest answer for a machine that reports no structure
two sockets, 8 CCDsSMT pair, L3, socket, root0 to 4, five ringsfills its own CCD, then its own socket, then crosses
chains of unequal depthvaries by CPUas many as that CPU hasa CPU whose chain is shorter than the current level sits that pass out and waits for the catch-all, rather than reaching further than its neighbours
kernel without SMPnone0 exact, 1 everyoneone CPU, so the question does not arise
kern.smp.topology overridewhatever was asked forfollows itnearness follows the administrator's description, right or wrong
The count of rings is never written down in the code. in_pcblbgroup_remap() counts the chain for each receiving CPU and the deal runs one pass per level plus the catch-all, so a machine the scheduler describes in more detail gets a finer-grained deal without any change here.

What is new here

Widening rings over a machine's own topology are established practice in schedulers and memory allocators, where they place a thread or a page near the work that needs it. Equal-share slot tables are established practice in load balancers, where they divide traffic evenly and survive a membership change without reshuffling everything.

Neither has been brought to the socket layer's choice of which listener receives a connection. That choice has until now been an exact CPU match or a hash: the first starves every worker not sitting on a receive queue, the second throws locality away. Putting the two together there is new. The rings decide who is nearest, the slot table guarantees the share, and between them a machine can use every worker it has without giving up the locality the hardware set up.

Measured on hardware

This host (Ryzen 9 5950X, two CCDs on one package - the same four rings as the drawings above, with the other CCD in place of the other socket), 2026-08. Here ring 3 is the cross-CCD hop over Infinity Fabric, and its cost is measured, not assumed: against a same-CCD wakeup it is +19% cycles per request. The exact-claim predecessor that the ring deal generalizes was run across three worker layouts - workers all on the receiving CCD gained nothing (the wakeup already shares L3), workers spanning both CCDs gained -15% (affinity vs hash), and forcing every worker to the far CCD cost -19% (affinity vs anti, the pure ring-3 penalty). The ring deal itself was not exercised here; it needs the two-socket receive topology below. On this host they make the cross-CCD hop the one expensive step.

Two-socket 2x Xeon E5-2470 v2 (Ivy Bridge-EP), two sockets over QPI, 2026-09-26. This is the machine drawn above: each socket is one NUMA domain with one L3, the chain from any leaf CPU is the SMT pair, then its socket, then the root, and ring 3, the last pass, is the cross-socket step. Booted the affinity kernel with direct netisr dispatch; cycles per request from a process-scoped PMC over the worker threads only. The -18.1% in the drawings is the exact-claim predecessor on this machine, with eight workers and receive on socket 0: workers co-located with their receive CPU against the same workers pinned to the far socket.

The deal delivers when receive spans both sockets. One receive-queue set on each socket, one worker per receive CPU across both (16 workers): plain hash scatters about half the connections to the far socket, while the ring deal keeps each socket's connections on its own socket and still uses every worker. Cross-CPU wakeups fell from ~292k to ~15k and cycles per request dropped 11.3% against the hash - matching the exact-claim design's 12.1% while starving no worker and needing no application change (the learning is on by default; the workers only pin themselves).

Same-socket, the mechanism co-locates ~96% (workers one per receive CPU on one socket): cross-CPU wakeups ~266k to ~8k, learned automatically at accept(2). Cycles per request are flat there, because same-socket wakeups already share the L3 - the ring-3 hop is the only expensive step, exactly as drawn.

One caveat the runs surfaced: supply is learned in two ten-second windows, so a benchmark shorter than that under-converges and the deal stays partly on the hash. Sustained traffic converges it; short bursty runs show variance. Worth weighing where the window length meets real workloads.

What the drawings commit to

  • The ring count is read, not assumed. It is the scheduler's group chain for each receiving CPU, short of the root, plus one last pass.
  • Ring 0 is tested against the CPU id, every other ring against a group mask, so a member that named this exact CPU is settled before anything sharing its core.
  • Levels are the outer loop, so no CPU reaches into ring n+1 while any CPU still has ring n business.
  • The catch-all admits every member still owed slots, including those that named no CPU, which is why supply always reaches zero, and with equal shares (the default) every deficit does too.
  • A CPU whose chain is shorter than the current level sits that pass out rather than jumping ahead of its neighbours.
  • Nothing here runs on the packet path: the whole deal is a few thousand cheap set tests, on membership, tag and count changes.