fn cap_organic_surbs(
data: &mut ApplicationDataOut,
max_surbs: usize,
surb_mgmt: &BalancerStateValues,
)Expand description
Caps how many SURBs an outgoing Session data packet may carry, per the SURB balancer.
Every finite max_surbs is gated by the balancer’s target: the packet carries the client’s number
of SURBs while the counterparty is estimated to be below its target, and none once it is at or above
it. The default of 1 is the plain case. A larger client value, which exists to save the balancer
work on highly asymmetric traffic, is gated the same way, so no setting but usize::MAX can hold
the counterparty more than one packet’s SURBs above the target. An explicit 0 always wins, whatever
the estimate. usize::MAX leaves the packet’s existing limit untouched and is the one way to opt out
of the gate.
The gate is BalancerStateValues::organic_surbs_per_packet, which yields 0 once the
counterparty is estimated to be at its target. That zero is the whole point of the function:
without it, the balancer can silence its keep-alives and still have organic SURBs pouring into a
full buffer, where each one evicts an older SURB and destroys the PIX share it carried. It also
bounds the stock the counterparty holds, which is what lets a SURB generation change wipe it at a
cost the PIX surplus can absorb.
One exception: while data goes out into a silence (see BalancerStateValues::silence_sustain),
a closed gate gives exactly one SURB per packet, whatever the client asked for. The estimate that
closed it is fed by the counterparty, and the counterparty has not been heard from for a while, so
the estimate cannot see the stock draining and would hold the gate shut until it is empty. One SURB
per data packet is about what the counterparty spends answering it: no burst, bounded by the data
rate, and it ends with the first report or reply.
Nothing else has to change to keep the SURB accounting straight. This runs in front of the
counting sink, so estimate_surbs_with_msg reports the capped figure; and the PIX share for a
SURB is drawn per SURB while it is built, so a cap of 0 draws no share at all and leaves it
queued for a packet that can actually deliver it.