Struct Source 

pub struct Source {
    pub caps: Capability,
    pub gamma_est: f64,
    pub rho_est: f64,
    pub delta_est: f64,
    pub suspended_until: f64,
    pub consecutive_stalls: u32,
    pub priority: u32,
    pub live: bool,
}

Fields

caps: Capability

gamma_est: f64

Per-connection goodput ceiling estimate, bytes/s.

rho_est: f64

Per-source shaping cap estimate, bytes/s.

delta_est: f64

Measured request setup cost, seconds.

suspended_until: f64

Suspended until this time (429/503 Retry-After, or stall backoff).

consecutive_stalls: u32

Consecutive stalls observed on this source; drives exponential backoff.

priority: u32

Publisher-stated preference: 1 is best, NO_PRIORITY means unranked.

Why this is a PRIOR and nothing more

Everything else in this struct is measured. This is not: it is what a mirror list (Metalink priority/preference, an RFC 6249 Link ... pri=) says about a source before a single byte has moved. It is worth having because the first split has to be made from something, and a publisher’s ranking is a better guess than an arbitrary order — it usually encodes geography, bandwidth, and whether the host is a CDN or a volunteer.

It is worth having ONLY as a prior. A ranking cannot know that the preferred mirror is currently overloaded, and this scheduler exists precisely because that is discoverable at runtime and correctable for free. So priority biases Scheduler::initial_split and nothing else: once gamma_est and the per-connection rate estimates have real samples in them, repair decisions are made on measurement, and a highly-ranked mirror that is slow loses its work exactly as fast as an unranked one would. Letting the prior persist would be strictly worse than having no ranking at all, because it would defend the wrong source against evidence.

live: bool

False once a source has been retired: it is out of the transfer for good.

Distinct from suspended_until, which is a pause with an end. A retired source is one a caller has replaced or abandoned — an unreachable host, a mirror serving the wrong object — and it must never be handed work again, however long the transfer runs. Conflating the two is how a dead mirror gets retried every backoff for the life of the download.

Implementations

impl Source

pub fn priority_weight(&self) -> f64

Relative share of the first split this source’s ranking argues for.

1 / priority, so rank 1 gets twice rank 2 and eight times rank 8, and every unranked source gets the same small share as every other. The exact curve is a judgement call and is deliberately gentle: it is a prior over a quantity nobody has measured yet, and the correction costs one repair. A steeper curve would concentrate the object on one mirror and turn the publisher’s guess into a single point of failure — the opposite of what a mirror list is for.

pub fn usable_at(&self, now: f64) -> bool

May this source be given work right now?

Retirement and suspension are separate conditions with one answer, and every assignment path must ask the combined question. A path that checks only suspended_until hands work to a retired mirror the moment its last backoff expires — which is exactly the host a caller retired it for.

Trait Implementations

impl Clone for Source

fn clone(&self) -> Source

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Source

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Source

fn default() -> Self

Returns the “default value” for a type.