SourceOpenHints

struct SourceOpenHints

Declared in Sources/PrismCore/Probe/SourceOpenHints.swift · PrismCore 3.5.4

What a caller already knows about a source, handed to the open so it can read less.

The governing rule, and the reason every field below is described as "sizing": a hint may let this engine do less work; it may never let it decode something it would otherwise have refused, or skip a check it would otherwise have made. A wrong sizing hint costs a read. Nothing here is allowed to cost a wrong parse.

hints: nil is today's behaviour byte for byte — the hinted path is an addition to the open, not a fork of it. Everything a hint influences is behind an if let on a value that is absent by default.

Initializers

init(headerBytes:firstClusterOffset:indexLocation:expectedValidator:keyframes:)source

init(headerBytes: Int? = nil, firstClusterOffset: Int64? = nil, indexLocation: IndexLocation = .unknown, expectedValidator: String? = nil, keyframes: SuppliedKeyframeMap? = nil)

No documentation comment in the source.

Instance properties

headerBytes source

var headerBytes: Int?

The length of the source's initial metadata region, from byte 0. Used to size the first read, and for nothing else.

firstClusterOffset source

var firstClusterOffset: Int64?

The offset of the first top-level media element. Same use, and it wins over headerBytes when both are present: it is the offset past which there is provably nothing left for the header parse to want.

indexLocation source

var indexLocation: IndexLocation

Where the caller believes the container's index lives.

Carried, not acted on. Acting on it would mean skipping the tail reads, and skipping a read is the one thing a sizing hint is not allowed to do: a stale none on a file that has Cues would cost a keyframe-basis plan with nothing in the logs to say why. It is here so a caller can pass the whole document through and so measurements can correlate against it; the day it earns a behaviour, that behaviour needs the transport binding, not this field.

expectedValidator source

var expectedValidator: String?

The validator (ETag, else Last-Modified) the caller expects the transport to report for the representation these hints describe.

Required — and required to match — before keyframes may be used at all. A transport that reports no validator is a rejection of the hints, never of the play; so is a mismatch found before the first byte has been delivered. A mismatch found after reading has started is not a hint problem but a representation change underneath a live session, and HTTPRangeInput already refuses to append that block.

keyframes source

var keyframes: SuppliedKeyframeMap?

A keyframe map computed elsewhere.

Provenance rides inside the value rather than in a flag beside it, so it cannot be dropped on the way to a planner — the distinction between this and a map harvested locally by a remux of these very bytes is the whole of the trust argument, and a bare [Int64] would erase it.

Generated from the public symbols of PrismCore 3.5.4. All types