Struct PixFillControl 

pub(crate) struct PixFillControl {
    session_id: SessionId,
    controller: RateController,
    notify_period: Option<Duration>,
    min_surb_reserve: u64,
    estimator: AtomicSurbFlowEstimator,
    state: Mutex<PixFillState>,
}

The Exit’s control over the single Exit → Entry keep-alive stream a Session runs.

One stream, two producers with different jobs, and this is what reconciles them:

• the SURB-level notification, sent every surb_balance_notify_period, which tells the Entry’s balancer how many SURBs the Exit believes it holds. It is the signal that asks for more, so it must go out even when there are none left;
• PIX fill, whose rate the supervisor plans once a second so that a funded cycle completes inside its own deadline even if the application never sends a byte.

The effective rate is the faster of the two, because both are the same packet: a keep-alive carrying the SURB level is exactly what fill needs to send, and sending two streams of them would double the traffic to say the same thing twice. Every shipped Entry already parses it, counts it as a consumed SURB so its balancer refills, and — since the fix that precedes this — credits it as service against the successor gate.

Fields

session_id: SessionId

controller: RateController

The rate limiter of the keep-alive stream this steers.

notify_period: Option<Duration>

The configured SURB-level notification period, if the node has one.

None disables the notification half entirely; the stream then runs at the fill rate alone, which is how a PIX Session on a node with surb_balance_notify_period: None still fills.

min_surb_reserve: u64

SURBs that must remain estimated-available before a fill packet is let through.

The effective reserve for this Session, not the configured one: the Entry decides how deep the Exit’s SURB buffer for the Session is, so a reserve above what the Entry ever intends to supply would refuse every fill packet forever. See effective_surb_reserve.

estimator: AtomicSurbFlowEstimator

The Session’s SURB flow estimate, which is what the reserve is measured against.

state: Mutex<PixFillState>

Implementations

impl PixFillControl

fn new( session_id: SessionId, controller: RateController, notify_period: Option<Duration>, min_surb_reserve: u64, estimator: AtomicSurbFlowEstimator, ) -> Self

pub(crate) fn start_notify(&self)

Turns the SURB-level notification on, after its initial delay.

A no-op once the Session is draining, for the reason enter_drain gives — and it has to be checked here rather than only there, because the one-shot delay task holds a clone of this control and nothing bounds how long an operator may make its period.

pub(crate) fn enter_drain(&self) -> bool

Puts the stream into post-close drain mode, silencing the SURB-level notification.

Returns false if the stream was draining already, which is how two closes racing through begin_surb_drain settle which of them owns the drain. The read and the write have to be one lock acquisition for that: callers that each saw is_draining before either wrote it would both start a drain, and both tell the supervisor about it.

The notification is the single packet admit_at exempts from the SURB reserve, and the exemption exists for one reason: it is the message that asks the Entry for more SURBs. It asks on behalf of a Session that a drain has already lost — the Entry itself may well still be there, but nothing is left to act on the request — so leaving it on would originate below the reserve into a buffer nothing is refilling, which is the one failure mode PixFillConfig::min_surb_reserve exists to prevent, since a return packet with no SURB holds up every packet this node originates. With it off, notification_due is always false and the reserve is the only gate.

pub(crate) fn is_draining(&self) -> bool

Whether this Session is draining its SURB buffer after having been closed.

pub(crate) fn drainable_surbs(&self) -> u64

The SURBs this Session could still spend on a drain, net of the reserve it must leave behind.

An estimate and an upper bound at that — ring-buffer overwrites, store eviction and invalidated relayers are all unobserved — which is why the supervisor weighs it against a cycle’s whole remaining emission rather than a discounted one. The reserve subtracted is the effective one already derived for this Session, not the configured ceiling.

pub(crate) fn set_fill(&self, rate: FillRate)

Applies a rate planned by the PIX supervisor.

fn effective(state: &PixFillState, notify_period: Option<Duration>) -> FillRate

fn apply(&self, state: &PixFillState)

pub(crate) fn admit(&self) -> bool

Decides whether the next keep-alive may go out, and books it if so.

The SURB-level notification always may: it is the message that asks the Entry for more SURBs, so refusing it when SURBs are scarce is refusing to ask for the thing that is scarce.

Fill above that rate is refused while the estimate is below the reserve, and that refusal is not an optimisation. A return packet that finds no SURB is not dropped — the routing resolver holds it, and with it every packet this node originates, for the whole of surb_resolution_wait. An Exit filling a cycle down to its last SURB would therefore stall the Session it is filling for, and every other Session on the node with it.

Which packet is the notification

Nothing about a packet says which producer it belongs to, so the notification is the first one released no sooner than a period after the last — less a slack of min(MAX_WAIT_CHUNK, period / 2), which is what keeps the classification from resting on scheduling latency. The rate limiter that releases these packets sleeps in chunks of MAX_WAIT_CHUNK, re-reads its controller on each wake, and rounds a rate into an integer packet count, so a stream asked for one packet per period releases them a shade over or a shade under it. Compared against the period exactly, a period the controller rounds short by a microsecond would classify every other notification as fill — counted in hopr_session_pix_fill_packets_total and, below the reserve, dropped. That is the signal asking the Entry for the SURBs whose absence caused the drop, and it runs on every Exit Session with a surb_balance_notify_period configured, PIX or not.

The slack cannot let fill masquerade as the notification: last_notify_at advances to the instant the packet actually went out, so only the first packet past the slack window is the notification, and every fill packet that follows it inside the period is still fill and is still bounded by the reserve. The cap at half the period is what stops a very short period from having its window widened away to nothing.

fn admit_at(&self, now: Instant) -> bool

admit against a caller-supplied instant, so the classification can be tested as the rule it is rather than by sleeping out a period and hoping the scheduler cooperates.

fn set_withholding(state: &mut PixFillState, withholding: bool)

Moves the surb_starved gauge on the edges only, so it counts stalled Sessions rather than refused packets — the same distinction PixGateBlockEpisode draws for the egress gate.

Trait Implementations

impl Drop for PixFillControl

Returns this Session’s surb_starved count if it was withholding when it went away.

Drop rather than a call on the close paths, for the reason PixGateBlockEpisode gives: a Session can end by teardown, by drain, or by its last Arc going out of scope in a task nobody is waiting on, and this is the one mechanism that covers all three. Without it a Session that dies mid-stall leaves the gauge standing for the life of the process.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.