Struct FillPlanner 

pub(crate) struct FillPlanner {

    cfg: PixFillConfig,
    max_recovery_time: Duration,
    max_recovery_idle: Duration,
    cycle_shares: u64,
    last_tick: Instant,
    last_served_total: u64,
    organic_pps: f64,
    target: Option<SsaId<HoprPseudonym>>,
    target_seen: u64,
    target_progress_at: Option<Instant>,
    last_rate: FillRate,
    stall_warned: bool,
    stall_onset: bool,
}

The pure rate law. See the module documentation for what it computes and why.

Fields

cfg: PixFillConfig

max_recovery_time: Duration

SupervisorConfig::max_recovery_time, the budget finish_fraction is a fraction of.

max_recovery_idle: Duration

SupervisorConfig::max_recovery_idle, reused as the stall horizon so that fill gives up on a motionless cycle at the same point the idle rule would have, had it been able to see it.

cycle_shares: u64

E — every share one cycle of the negotiated dimensions emits, and therefore every packet it takes to complete one.

last_tick: Instant

When plan last ran. Also the base of next_tick.

last_served_total: u64

The gate’s served counter at last_tick, so the next tick can difference it.

organic_pps: f64

Exponential average of organic egress, in packets per second.

target: Option<SsaId<HoprPseudonym>>

The cycle the counters below belong to, so a handoff resets them rather than reading the successor’s progress as the predecessor’s stall.

target_seen: u64

largest_shares_seen as of the last tick that observed movement.

target_progress_at: Option<Instant>

When the target last moved, or when it became the target. None while there is no target.

last_rate: FillRate

The rate the stream is believed to be running at, and the value hysteresis compares against.

stall_warned: bool

Whether the stall has already been reported, so a stalled cycle warns once rather than once a second for the whole of max_recovery_time.

stall_onset: bool

Set on the tick a stall begins, and taken by the worker so it can count the event.

An edge rather than a level, because the metric it feeds counts stalls: a level would count one per second for as long as the cycle stayed motionless, which is a measure of how long the operator waited rather than of how often this happened.

Implementations

impl FillPlanner

pub(crate) fn new( cfg: &SupervisorConfig, dims: &PixParams, now: Instant, ) -> Self

Builds a planner for a Session of the given dimensions.

now seeds next_tick, so the first plan happens one sampling interval after the Session starts rather than immediately. Nothing is lost by that: a Session has no funded cycle to fill for until at least a commitment and a deposit have crossed the wire.

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

Whether fill is configured on at all.

pub(crate) fn take_stall_onset(&mut self) -> bool

Reports, once, that the target cycle has gone motionless and fill has fallen back.

Consumed rather than read so the caller counts the stall rather than its duration. The caller is the worker, which is the layer allowed to have side effects; this module stays pure.

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

Whether the target has gone motionless and fill has fallen back to its heartbeat.

The level behind take_stall_onset’s edge, so the census can report a stall for as long as it lasts without the caller tracking it.

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

Whether the stream this planner drives is currently emitting nothing.

The supervisor uses it to decide whether a tick is worth waking for when there is no target: a planner that has already stopped has nothing left to say, while one that is still running owes the stream a zero.

pub(crate) fn next_tick(&self) -> Instant

When the next plan is due.

pub(crate) fn stop(&mut self) -> Option<FillRate>

Silences the stream, if it is running, and forgets the target.

Returns the action’s payload only when there is something to stop, so a Session that never filled — a disabled one, or one that closed before its first cycle funded — emits nothing and its action stream is byte-for-byte what it was before fill existed.

pub(crate) fn plan( &mut self, now: Instant, served_total: u64, target: Option<FillTarget>, ) -> Option<FillRate>

Re-derives the fill rate, returning it only if it is worth emitting.

served_total is the service gate’s counter — organic egress and nothing else. target is the cycle the Exit is working for, or None when it has none, which is the case that stops the stream.

fn observe_organic(&mut self, now: Instant, served_total: u64)

Folds this interval’s organic egress into the exponential average.

alpha = dt / ORGANIC_WINDOW, capped at one, so the average has the same time constant however irregularly the ticks land — a worker that was busy for five seconds contributes five seconds of weight, not one tick’s worth. A tick with no elapsed time contributes nothing rather than dividing by zero.

fn observe_target(&mut self, now: Instant, target: &FillTarget)

Tracks whether the target has moved, which is the input to the stall rule.

A change of target resets the clock rather than inheriting the predecessor’s: a successor that has just reached the front has made no progress yet, and reading that as a stall would hold every cycle after the first at the heartbeat.

fn required_rate(&self, now: Instant, target: &FillTarget) -> f64

The rate at which the cycle’s remaining emission clears the aim point, in packets per second.

The aim point sits (1 − finish_fraction) × max_recovery_time before the hard deadline, so the last part of the budget is margin: for loss beyond loss_margin, for a mixnet delay spike, and for the commitment and deposit round trip the successor still needs. An aim point already in the past collapses to one sampling interval, which asks for the whole remainder at once and is then bounded by max_rate — the correct behaviour for a cycle that is out of time, since there is no rate at which it can still be saved and no reason to stop trying.

A drain collapses the horizon the same way for a different reason: pacing a cycle to its deadline only makes sense while the Session is still there to be paced, and a drained one is spending a buffer nothing will refill. The ceiling in bound then becomes the only thing setting the rate, which is the intent rather than a side effect.

fn bound(&mut self, now: Instant, wanted: f64) -> FillRate

Applies the stall rule and the two bounds, and expresses the result as a FillRate.

The heartbeat is a floor rather than a special case, so a Session whose application is keeping up still emits one packet per period: it refreshes the Entry’s idle eviction, it carries the SURB level the Entry’s balancer acts on, and it is what distinguishes a planner that decided on nothing from one that has stopped planning.

The stall rule still applies while draining.

Without it, a doomed drain could sit at max_rate until the deadline and waste SURBs. A healthy drain pays nothing for the rule, because progress refreshes target_progress_at. And max_recovery_idle does not replace it: that deadline ends the drain, this bounds what it spends before then.

fn should_emit(&self, rate: FillRate) -> bool

Whether rate differs from what the stream is already doing by enough to be worth an action.

The planner runs every second for the whole life of a cycle — hours, at production dimensions — and the required rate drifts continuously as the remainder and the horizon both shrink. Emitting every one of those would put a per-second action on a channel sized for lifecycle transitions, and the driver would reconfigure a rate controller for a change no packet schedule can express. So a change is reported when it is a real one:

• any change to or from zero, because that is the difference between filling and not;
• any crossing of the heartbeat, because that is the difference between filling and idling;
• otherwise, a relative change of more than ten per cent.