fn hold_for_surb_reserve(
session_id: SessionId,
estimator: &AtomicSurbFlowEstimator,
balancer: &Arc<BalancerStateValues>,
pix: bool,
) -> Option<BoxFuture<'static, ()>>Expand description
Holds an outgoing data packet back while the Exit’s SURB stock is down to its keep-alive reserve
(see current_keep_alive_surb_reserve).
Returns None, with nothing allocated, in the common case of a stock above the reserve. Otherwise
the future resolves once the stock has risen above it, polling the estimate every
SURB_RESERVE_POLL. It has no deadline of its own: the Session’s own deadlines apply, and a
Session that is closed drops the future with the sink.
Only once the Entry has shown that it refills the stock
(BalancerStateValues::counterparty_refills): that is, a keep-alive from its balancer, which only an
Entry with a SURB balancer sends (a manual ping, [KeepAliveFlag::ManualPing], is not one). An Entry without one
can run a rate-controlled Session too: it announces no target (one that predates this announces the balancer-rate
fallback, which the Exit cannot tell from a real target), attaches one SURB to each data packet and sends no
keep-alives but the odd manual ping. So the announcement says nothing about a balancer either way. A reply held for
a stock above the reserve would then wait until the Entry sent that many more packets.
The Exit’s keep-alives do not come through here: its keep-alive stream sends on the message sender
directly (see SessionManager::spawn_exit_keep_alive), and the PIX fill packets are bounded by
their own min_surb_reserve. That is the point of the reserve: they are what it is held for.
pix says whether the Session runs a PIX egress gate, and only labels the hold episode: the
hold itself is the same either way.