Skip to main content

cap_organic_surbs

Function cap_organic_surbs 

Source
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.