Expand description
Run-encoded entries: many evenly spaced samples under one entry header.
A single f32 sample costs 20 bytes of entry overhead plus a 1-byte schema
tag to store 4 bytes of data — 84% overhead. For a burst of samples taken
at a fixed cadence, almost all of that is repetition: the same sensor id, and
a timestamp the previous one already implies.
A run stores the burst as one entry:
payload = [ schema_version : u8 ] [ interval : u64 LE ] [ count : u16 LE ] [ T ; count ]with the entry header’s timestamp holding the first sample’s, so sample i
is at base + i * interval. Thirty-two f32 samples cost 148 bytes instead
of 800.
§A run is invisible to readers
Every read path expands a run back into the samples it holds, so
query_range, latest, oldest and count deliver exactly what
append_sensor of the same samples would
have delivered — same headers, same [version][value] payloads, same
order. Only read_from sees the run as one
entry, because replication copies entries and a replica should keep the
amortisation rather than unpack it.
That transparency is what makes runs a pure storage optimisation: a caller can start using them without changing a single read.
§Why the marker and not the payload
An entry is a run because its header carries
ENTRY_MARKER_RUN instead of
ENTRY_MARKER — a field the entry header CRC
covers and the raw append path cannot write.
The alternative — flagging a run in the payload, say with the high bit of the
schema tag — was tried and reverted. It cannot work, because a raw payload is
arbitrary bytes: any payload whose first byte happened to have bit 7 set
would read as a run, and the sector index would inherit its invented time
span. tests/model.rs caught exactly that, on a workload containing no typed
data at all. A marker in the header is structural: the raw API always writes
0xAA, so a run is a run.
§Runs are a typed-API feature
Run::of takes &[T] for a SensorData type, because the frame carries
a schema tag and expansion produces [version][value] payloads — which is
precisely what the typed single-sample path writes. There is deliberately no
untyped constructor: an untagged run would expand into payloads that no read
path could interpret.
Structs§
- Run
- Evenly spaced samples of one sensor, ready to be appended as a single entry.
Constants§
- RUN_
FRAME_ SIZE - Bytes a run frame prepends to its samples: the schema tag, the interval, and the sample count.