Expand description
Backing storage for readers over large binary artifacts.
The terrain store and the precise-interpolant store are both read by indexing into a byte span: construction parses only the header, datum tag, and tile/segment index, and every lookup addresses payload by offset. Neither reader holds a reference into its own bytes, so the bytes can be owned, borrowed, or memory-mapped without any of them being a self-referential struct - the span is derived on demand from whichever backing is present.
That is what makes the mapped variant safe to add: there is no interior
pointer to keep valid, no drop-order invariant hiding in field declaration
order, and no unsafe at any interface boundary.
§Why mapping matters more than the copy
Avoiding one memcpy is the smaller half. A memory map is demand-paged, so a
reader that queries a geographically local region faults in the handful of
pages covering those tiles and never touches the rest of the file. A
constructor that copies - however the bytes arrive - forfeits that and pays
for the whole artifact on every open. For a 30+ GB terrain store that is the
difference between a working process and one that cannot start.
Enums§
- Artifact
Bytes - Where a reader’s bytes live.
- Digest
Provenance - Who computed the content digest a handle carries.