Documentation
¶
Overview ¶
Package inflight tracks per-digest pulls currently being executed on this agent. The map is shared between two callers:
- The puller-side `please_pull` handler (the step 7) which calls Start to atomically claim a digest. The "already started" bool return is what produces the wire-level OUTCOME_ALREADY_PULLING vs OUTCOME_STARTED distinction.
- The responder-side `pull_intent_query` handler (the step 4) which calls LookupForIntent to report in_flight / started_at to the requester.
The requester-side the design doc stall check (IsStale) is also implemented here, so the stall threshold lives in exactly one place.
All operations are O(1) under a single sync.Mutex. The map is in- memory only - restarts clear it. Restart-during-pull is treated as a stalled pull from the requester's point of view (the design doc), which is the correct behavior: the puller is gone, rank-1 takes over.
Index ¶
- type Entry
- type Handle
- type Map
- func (m *Map) IsStale(kind ifaces.OriginRefKind, expectedSize int64, startedAt time.Time) bool
- func (m *Map) Len() int
- func (m *Map) LookupForIntent(d digest.Digest) (Entry, bool)
- func (m *Map) Stalls() Stalls
- func (m *Map) Start(d digest.Digest, kind ifaces.OriginRefKind, expectedSize int64) (*Handle, Entry, bool)
- type Stalls
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry struct {
StartedAt time.Time
ExpectedClass ifaces.OriginRefKind
ExpectedSize int64
}
Entry records the in-flight state for a single digest. ExpectedClass is set only after the puller learns whether this is a manifest / config (kB-scale, fixed timeout) vs a layer (size-aware timeout); ExpectedSize is set when known (manifest gives it).
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle is returned by Start. Calling Done on Handle removes the digest from the in-flight map. Handles are single-use; subsequent calls are no-ops.
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map is the per-agent in-flight registry. The zero value is not usable; construct via New.
func New ¶
New constructs an empty in-flight Map with the supplied stall config and clock. now == nil falls back to time.Now.
func (*Map) IsStale ¶
IsStale reports whether an in-flight Entry observed at startedAt for a digest of the given kind has exceeded the per-the design doc timeout. The expectedSize parameter is the size the requester believes the digest to be (0 means unknown). Used by the requester-side the design doc stall check - the requester is comparing a PullIntentResponse from a remote node to its local clock, so the time arrives via the response, not via a Map lookup.
func (*Map) Len ¶
Len returns the current number of in-flight entries. Used by the `p2p_in_flight_pulls` gauge.
func (*Map) LookupForIntent ¶
LookupForIntent returns the in-flight state for d, used to fill PullIntentResponse.in_flight / .started_at on the responder side. in_flight is false (and the entry zero) when d is not currently being pulled by this agent.
func (*Map) Start ¶
func (m *Map) Start(d digest.Digest, kind ifaces.OriginRefKind, expectedSize int64) (*Handle, Entry, bool)
Start atomically claims the digest. If alreadyPulling is true the returned handle is a no-op handle for that digest (callers MUST still receive a non-nil Handle so deferred Done works unconditionally). The Entry return is the existing entry when alreadyPulling is true; otherwise it's the entry just inserted.
Used by the puller-side `please_pull` handler to atomically decide between OUTCOME_STARTED and OUTCOME_ALREADY_PULLING.
type Stalls ¶
type Stalls struct {
ManifestConfig time.Duration
LayerFloor time.Duration // floor portion of expected_pull_seconds
LayerBytesPerSec int64 // 50 * 1024 * 1024 in v1
LayerMultiplier int // 3 in v1
}
Stalls bundles the per-digest-kind timeouts used by IsStale. See the design doc for the per-kind values. v1 defaults - manifest/config 5s, layer = max(10s, expected_size/50MB/s) × 3 - are produced by DefaultStalls and ResolveStall.
func (Stalls) ResolveStall ¶
ResolveStall computes the per-digest stall threshold from kind and the known/expected size. Per the design doc:
- manifest/config -> ManifestConfig (size irrelevant; kB-scale) - layer -> max(LayerFloor, size / bytesPerSec) × multiplier
expectedSize <= 0 (unknown) falls back to LayerFloor × multiplier for layers - the safest assumption when the manifest hasn't been parsed yet on this side.
Source Files