Struct FillRegistry 

pub struct FillRegistry { /* private fields */ }

Range-aware coalescing registry: the live in-flight fills, keyed by hash, plus a per-hash captured outboard. A serve-miss consults Self::claim to split its range into an attach (covered by a running pull) and a remainder (fetch it), and Self::range_still_live answers a parked reader’s “keep awaiting or fail?”. Purely synchronous range math under a std Mutex; the lock is never held across an await.

Implementations

impl FillRegistry

pub fn new() -> Self

An empty registry with no metrics handle (unit fixtures).

pub fn with_metrics(metrics: Option<Arc<CacheMetrics>>) -> Self

An empty registry that reports its coalescing decisions to metrics.

pub fn register_fill( self: &Arc<Self>, hash: Hash, session: &Arc<FillSession>, ) -> ObserverLease

Publish a new pull’s session (already scoped via FillSession::set_covered to the bytes it will fetch) and return the owner lease (observer count starts at 1). The entry stays in the map until the owning pull is joined node-side. A test-facing helper; production registers via Self::claim.

pub fn in_flight_total(&self, hash: Hash) -> Option<u64>

The blob length of a LIVE in-flight fill for hash, if one runs — an ADVISORY peek the serve-miss path uses to skip its upstream header handshake when a pull it can coalesce onto already exists. Returns the total_bytes of the first non-dead session under hash (every session for one hash shares the blob’s geometry, so any live one’s length is THE length); None when no live fill exists (empty, or only dead sessions remain). Advisory only: a concurrent last-observer drop can retire the peeked session before the caller’s atomic Self::claim, which then owns a fresh pull and opens the leg late — so this NEVER replaces claim, it only removes the handshake in the common coalescing case.

pub fn range_still_live(&self, hash: Hash, range: &ChunkRanges) -> bool

Whether any LIVE fill of hash still covers range. A parked reader calls this (via FillSession::range_still_live) to decide “keep awaiting a capture / present-range advance, or fail because no pull will ever fill this”. true iff some live session’s covered intersects range.

pub fn claim( self: &Arc<Self>, hash: Hash, offset: u64, len: u64, total: u64, make_session: impl FnOnce() -> Arc<FillSession>, ) -> FillClaim

Atomically decide attach/own/mixed AND register any new owner session, all under ONE map-lock acquisition. This closes the coalescing TOCTOU race a separate plan-then-register pair would leave open: between two lock acquisitions another thread can register, so two concurrent fresh misses for the same blob would both see an empty registry and both open a pull. claim holds the lock across the whole decision, so exactly one of two racing identical claims registers an owner and the other attaches.

R = align_range_clamped(offset, len, total): an end past total clamps to it, so a request whose claimed size grows still coalesces with a live fill instead of always falling to Owner. On an align error (a start at or past total) or empty R, the caller takes the Owner path (its own fetch surfaces any out-of-bounds error). Otherwise, over LIVE sessions whose paid frontier reaches R’s aligned fetch start (a session behind that frontier is excluded — attaching to it would park this request on a pull that advances only as the OTHER client pays, #2062; the exclusion trades duplicate egress for the overlap, counted as fill_not_coalesced), covered_union = ⋃ covered, attach = R ∩ covered_union, remainder = R − covered_union:

• attach empty → OWNER of the whole R.
• remainder empty (a live pull covers all of R) → ATTACH to the largest-overlap session; make_session is NOT called.
• both non-empty, and the largest-overlap sibling covers ALL of attach, and R − sibling.covered is ONE contiguous span → MIXED: own a pull for that remainder, attach the sibling for the overlap.
• otherwise (a multi-sibling union, or an interior overlap splitting the remainder in two) → OWNER of the whole R, the conservative fallback. It never wedges; like the frontier exclusion above it can double-pull an overlap a live sibling also covers.

make_session runs under the lock only on an owning branch (never built-and-dropped on a pure attach); it does no await (a std lock) and only allocates, so holding the lock across it is safe.

Trait Implementations

impl Debug for FillRegistry

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

Formats the value using the given formatter.

impl Default for FillRegistry

fn default() -> Self

Returns the “default value” for a type.