pub struct SensorDb<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> { /* private fields */ }Expand description
Append-only sensor database for NOR flash.
Generic parameters:
F: Flash storage implementingNorFlashandReadNorFlashPAGE_SIZE: the unit this database writes in. Must be a multiple ofF::WRITE_SIZE— checked at compile time — and must not exceed the part’s physical program page, whichembedded-storagedoes not express and so cannot be checked. NoteWRITE_SIZEis the minimum write granularity, not the program-page size; a driver reporting 1 constrains nothing.MAX_SECTORS: Maximum number of sectors this instance can manage
§Memory Usage
The struct’s RAM footprint is approximately:
MAX_SECTORS × 48bytes for the in-RAM sector index (SectorSummaryarray)PAGE_SIZEbytes for the write page buffer- ~30 bytes for bookkeeping fields
Example: with PAGE_SIZE = 256 and MAX_SECTORS = 32, total ≈ 1,822 bytes.
§NOR Flash Constraints
Entries cannot span page boundaries because NOR flash requires page-aligned
writes. Each entry (header + payload + CRC) must fit within a single
PAGE_SIZE page. The maximum payload size is PAGE_SIZE - 20 bytes.
The database does not perform active wear leveling beyond the implicit distribution of the circular sector ring. Sectors are used round-robin starting from the sector after the current active one. For applications needing precise wear balancing, consider tracking erase counts externally.
§Read Model
Reads do not write to flash: latest, oldest, count, query_range
and their typed variants scan committed entries and transparently include
any buffered (unflushed) entries from the page buffer, so a read never
triggers a flash write and sync() is needed for durability alone, not
for read visibility.
They do take &mut self, because ReadNorFlash::read does. An earlier
revision wrapped the driver in a RefCell so they could take &self, and
it bought nothing: RefCell<F> is !Sync, so the only way to share a
SensorDb was a Mutex, which hands back &mut anyway. What it cost was
real — reads split into two shapes (&self here, &mut self on
LogSource, which
TieredDb forces), a re-entrancy panic to fence off
(a callback capturing &db and calling latest() double-borrowed), and a
panic path in a no_std crate. Without it SensorDb is Sync whenever
F is, and the port and the inherent methods agree.
Methods that touch no flash — stats,
is_mounted, head_position,
peek_unflushed and the rest — still take &self.
§Stack Usage
Most public methods allocate a single [u8; PAGE_SIZE] temporary buffer
on the stack. The deepest call chains (e.g., latest_value → latest →
find_latest_in_sector) pass buffers through rather than allocating new
ones, so the worst-case stack overhead per call is approximately
1 × PAGE_SIZE bytes on top of the SensorDb struct itself.
With PAGE_SIZE = 256, this is negligible. With PAGE_SIZE = 4096, each
read/query call uses ~4 KB of stack — plan accordingly on Cortex-M targets
with limited stack space.
Implementations§
Source§impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
Sourcepub fn new(
flash: F,
base_offset: u32,
sector_count: u16,
reserved_sectors: u16,
) -> Result<Self, Error>
pub fn new( flash: F, base_offset: u32, sector_count: u16, reserved_sectors: u16, ) -> Result<Self, Error>
Create a new SensorDb instance.
§Arguments
flash: Flash storagebase_offset: Starting offset in flash for the database regionsector_count: Number of sectors to usereserved_sectors: Number of sectors to keep free for compaction headroom
§Limits
- The entire database region (
sector_count × ERASE_SIZE + base_offset) must fit withinu32address space (4 GB). SectorSummary.write_offsetisu32, supporting individual sectors up to 4 GB.sector_countmust not exceedMAX_SECTORS.
§Errors
TooManySectorsifsector_count > MAX_SECTORSInvalidConfigifreserved_sectors >= sector_count
Sourcepub fn with_config(flash: F, config: DbConfig) -> Result<Self, Error>
pub fn with_config(flash: F, config: DbConfig) -> Result<Self, Error>
Create a SensorDb from a validated DbConfig.
Use this instead of new when the database needs a
LogId — for example when its storage is removable and could be
carried to, or confused with, another device.
§Errors
TooManySectorsifconfig.sector_count() > MAX_SECTORSOverflowif the region does not fit inu32address space
§Panics
Fails to compile, not to run, if PAGE_SIZE is not a multiple of
F::WRITE_SIZE — the compile-time Geometry assert.
Sourcepub fn format(&mut self) -> Result<(), Error>
pub fn format(&mut self) -> Result<(), Error>
Format the database region, erasing all sectors and initializing the first as active.
After format, the database is automatically mounted. All sectors carry
this database’s LogId and erase_count = 1, and the epoch restarts
at 1.
This destroys everything in the region unconditionally — including a
foreign volume. Use mount, which refuses to touch
another log’s data, when the medium’s provenance is not certain.
Sourcepub fn mount(&mut self) -> Result<MountStats, Error>
pub fn mount(&mut self) -> Result<MountStats, Error>
Mount an existing database by scanning all sectors and rebuilding the index.
Equivalent to mount_with(MountMode::Full).
§Errors
AlreadyMountedif already mountedForeignVolumeif the medium belongs to a different logUnsupportedVersionif the medium uses a newer format
Sourcepub fn mount_with(&mut self, mode: MountMode) -> Result<MountStats, Error>
pub fn mount_with(&mut self, mode: MountMode) -> Result<MountStats, Error>
Mount an existing database, choosing how much of the index to rebuild.
§Foreign media
A sector whose header parses as this format but carries a different
LogId aborts the mount with Error::ForeignVolume, before
anything is written. This matters for removable storage: the fallback
path for “no valid sectors found” erases a sector to bootstrap the log,
so without this check, inserting another device’s card and mounting it
would destroy its data.
An anonymous database (no log_id in its DbConfig) accepts any
medium, preserving the behaviour of databases that never declare an
identity.
§Epoch
Each successful mount takes an epoch one higher than any found on the medium, and stamps it into every sector header written from then on. Timestamps from a device with no real-time clock restart at zero on every boot; the epoch is what lets a reader tell those runs apart.
§Errors
AlreadyMountedif already mountedForeignVolumeif the medium belongs to a different logUnsupportedVersionif the medium uses a newer format
Sourcepub fn append(
&mut self,
sensor_id: u16,
timestamp: u64,
payload: &[u8],
) -> Result<(), Error>
pub fn append( &mut self, sensor_id: u16, timestamp: u64, payload: &[u8], ) -> Result<(), Error>
Sourcepub fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error>
pub fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error>
Append a run: many evenly spaced samples under one header.
One entry header and one CRC for the whole burst, which is what makes it
worth doing — thirty-two f32 samples cost 148 bytes here against 800
appended one at a time.
The run is invisible to every read: query_range,
latest, oldest and
count expand it back into the samples it holds, so they
deliver byte for byte what append_sensor of the
same samples would have delivered. Only
read_from sees it as one entry, because replication
copies entries and a replica should keep the amortisation.
use sensor_db::Run;
let burst: [Temperature; 32] = collect_burst();
db.append_run(&Run::of(t0, 10_000, &burst)?)?;§Errors
NotMountedif not mountedPayloadTooLargeif the framed run exceedsmax_payload_size; split the burstNoSpaceif no sectors available
Sourcepub fn append_framed(
&mut self,
header: &EntryHeader,
payload: &[u8],
) -> Result<(), Error>
pub fn append_framed( &mut self, header: &EntryHeader, payload: &[u8], ) -> Result<(), Error>
Append an entry exactly as another log stored it.
The write side of replication, and the mirror of
read_from: hand back the (header, payload) pair a
stream delivered and the entry is reproduced here — a
run as a run, so the copy keeps the amortisation instead of
storing the frame as one opaque sample no read could interpret.
§Errors
CorruptEntryif the header claims a run and the payload is not one- otherwise as
append
Sourcepub fn sync(&mut self) -> Result<(), Error>
pub fn sync(&mut self) -> Result<(), Error>
Flush the page buffer to flash, committing buffered entries.
Call this after writing entries to ensure they survive a power loss.
Read methods (latest, query_range, oldest, count) do not
require a prior sync() — they transparently scan the page buffer for
unflushed entries. sync() is only needed for durability, not for
read visibility.
§Sync Policy
There is a trade-off between data safety and flash wear:
- Sync after every append: Maximum durability — no data loss on power failure, but each sync writes a full flash page (two writes for the two-phase commit), increasing wear.
- Sync periodically (e.g., every N entries or every T seconds): Reduces wear but risks losing buffered entries on power failure. Entries written since the last sync are not yet committed to flash.
On embedded systems with limited flash endurance (~100K erase cycles), prefer batching writes and syncing periodically.
Sourcepub fn latest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error>
pub fn latest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>
Find the most recent entry for a given sensor.
This method does not write to flash. It scans committed entries on flash and any buffered (unflushed) entries in the page buffer, returning the one with the highest timestamp.
§Arguments
sensor_id: Sensor to querybuf: Buffer to receive payload
§Returns
Some((header, payload_len)) if found, None if no entries for this sensor.
Sourcepub fn query_range<C>(
&mut self,
sensor_id: Option<u16>,
t_start: u64,
t_end: u64,
callback: C,
) -> Result<u32, Error>
pub fn query_range<C>( &mut self, sensor_id: Option<u16>, t_start: u64, t_end: u64, callback: C, ) -> Result<u32, Error>
Query entries within a time range.
This method does not write to flash. It scans committed entries on flash and any buffered (unflushed) entries in the page buffer.
§Arguments
sensor_id: Optional sensor filter (None for all sensors)t_start: Start timestamp (inclusive)t_end: End timestamp (inclusive)callback: Called for each matching entry. Returnfalseto stop early.
§Returns
Number of entries that matched.
Note: Entries are returned in write order (sector sequence, then offset within sector), not sorted by timestamp. If timestamps are non-monotonic, the callback will see them out of chronological order.
Sourcepub fn query_all<C>(
&mut self,
sensor_id: Option<u16>,
callback: C,
) -> Result<u32, Error>
pub fn query_all<C>( &mut self, sensor_id: Option<u16>, callback: C, ) -> Result<u32, Error>
Query all entries for a sensor (or all sensors) without time constraints.
This is a convenience wrapper around query_range that uses the full timestamp range.
§Arguments
sensor_id: Optional sensor filter (None for all sensors)callback: Called for each matching entry. Returnfalseto stop early.
§Returns
Number of entries that matched.
§Example
let count = db.query_all(Some(SENSOR_TEMP), |hdr, payload| {
println!("Entry at {}: {:?}", hdr.timestamp, payload);
true
})?;Sourcepub fn oldest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error>
pub fn oldest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>
Find the oldest (earliest) entry for a given sensor.
This method does not write to flash. It scans committed entries on flash and falls back to the page buffer if no committed entries exist for this sensor.
§Arguments
sensor_id: Sensor to querybuf: Buffer to receive payload
§Returns
Some((header, payload_len)) if found, None if no entries for this sensor.
§Example
let mut buf = [0u8; 64];
if let Some((hdr, n)) = db.oldest(SENSOR_TEMP, &mut buf)? {
let first_reading = &buf[..n];
println!("First reading at {}", hdr.timestamp);
}Sourcepub fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error>
pub fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error>
Count entries for a specific sensor (or all sensors).
Exact: the count is the number of entries
query_range would yield over the whole time range,
because both apply the same acceptance test — a matching entry CRC — and
resync the same way when one fails. Buffered entries not yet on flash are
included, as they are for latest.
This method does not write to flash.
§Cost
None is free: it returns the total the mount scan established.
A sensor filter scans every sector the per-sector bloom filter does not
reject, reading each entry’s payload to verify its CRC. That payload read
is the price of agreeing with the read path; it was once skipped, which
made count cheaper and wrong — it included entries latest and
query_range refused to return. It is still cheaper than
query_all, which has no bloom filter to skip
sectors by.
§Arguments
sensor_id: Optional sensor filter (None to count all entries)
§Returns
Number of entries matching the filter.
§Example
let temp_count = db.count(Some(SENSOR_TEMP))?;
let total = db.count(None)?;Sourcepub fn compact(&mut self, count: u16, scope: CompactScope) -> Result<u16, Error>
pub fn compact(&mut self, count: u16, scope: CompactScope) -> Result<u16, Error>
Compact the database by erasing the oldest sealed sectors.
§Arguments
count: Maximum number of sectors to erasescope: Which sealed sectors are eligible. UseCompactScope::SpooledOnlyto reclaim space without destroying anything that has not been replicated yet.
§Returns
Number of sectors actually erased.
Sourcepub fn sectors_erased(&self) -> u32
pub fn sectors_erased(&self) -> u32
Sectors this instance has erased, since it was created.
An erase takes 100 ms or more on many NOR parts, against microseconds for
a page write, so it is the one operation that can make a single append
or compact call visibly slow. Sampling this around a
call says whether one happened — useful for a caller with a real-time
deadline, and for
WritePolicy::CardFirst, where
appends go straight to a removable volume.
Not the same as DbStats::total_erase_count, which is a wear history
read back from the sector headers and therefore counts erases from every
previous run too. This counter starts at zero for each SensorDb value,
including across a remount, and saturates rather than wrapping.
Sourcepub fn is_mounted(&self) -> bool
pub fn is_mounted(&self) -> bool
Check if the database is mounted.
Sourcepub fn max_payload_size(&self) -> usize
pub fn max_payload_size(&self) -> usize
Maximum payload size that can fit in a single entry.
Returns PAGE_SIZE - 20 bytes (PAGE_SIZE minus the 16-byte entry
header and 4-byte CRC-32C). Each entry must fit entirely within a
single flash page.
A typed payload carries a one-byte schema tag, so the largest storable
T is one byte smaller again — see
SCHEMA_TAG_SIZE.
Sourcepub fn append_value<T: IntoBytes + Immutable>(
&mut self,
sensor_id: u16,
timestamp: u64,
data: &T,
) -> Result<(), Error>
pub fn append_value<T: IntoBytes + Immutable>( &mut self, sensor_id: u16, timestamp: u64, data: &T, ) -> Result<(), Error>
Append a typed value to the database with an explicit sensor ID.
This is the Layer 1 API where you provide the sensor ID explicitly.
The value type must implement IntoBytes and Immutable from zerocopy.
§Arguments
sensor_id: Sensor identifiertimestamp: Timestamp (typically microseconds since epoch)data: Reference to the typed value to store
§Example
#[derive(IntoBytes, Immutable)]
#[repr(C)]
struct Temperature { celsius: f32 }
db.append_value(0x01, timestamp, &Temperature { celsius: 25.5 })?;Sourcepub fn latest_value<T: FromBytes + KnownLayout>(
&mut self,
sensor_id: u16,
) -> Result<Option<(EntryHeader, T)>, Error>
pub fn latest_value<T: FromBytes + KnownLayout>( &mut self, sensor_id: u16, ) -> Result<Option<(EntryHeader, T)>, Error>
Find the most recent entry for a given sensor and interpret as a typed value.
This is the Layer 1 API where you provide the sensor ID explicitly.
The value type must implement FromBytes and KnownLayout from zerocopy.
§Arguments
sensor_id: Sensor to query
§Returns
Some((header, value)) if found, None if no entries for this sensor.
§Errors
SizeMismatchif the stored payload size doesn’t matchsize_of::<T>()InvalidDataif the bytes cannot be interpreted as typeT
§Example
#[derive(FromBytes, KnownLayout)]
#[repr(C)]
struct Temperature { celsius: f32 }
if let Some((hdr, temp)) = db.latest_value::<Temperature>(0x01)? {
println!("Temperature: {} °C", temp.celsius);
}Sourcepub fn append_sensor<T: SensorData>(
&mut self,
timestamp: u64,
data: &T,
) -> Result<(), Error>
pub fn append_sensor<T: SensorData>( &mut self, timestamp: u64, data: &T, ) -> Result<(), Error>
Append a sensor reading using the type-driven API.
This is the Layer 2 API where the sensor ID is derived from the type.
The data type must implement SensorData.
§Arguments
timestamp: Timestamp (typically microseconds since epoch)data: Reference to the sensor data to store
§Example
#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Temperature { celsius: f32 }
impl SensorData for Temperature {
const SENSOR_ID: u16 = 0x01;
}
db.append_sensor(timestamp, &Temperature { celsius: 25.5 })?;§Schema tag
The payload is the type’s
SCHEMA_VERSION followed by the value’s
bytes, so the entry’s payload_len is size_of::<T>() + 1. Entries
written with the untagged append_value are not
readable through the *_sensor methods, and vice versa.
Sourcepub fn latest_sensor<T: SensorData>(
&mut self,
) -> Result<Option<(EntryHeader, T)>, Error>
pub fn latest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>
Find the most recent entry for a sensor type.
This is the Layer 2 API where the sensor ID is derived from the type.
The data type must implement SensorData.
§Returns
Some((header, value)) if found, None if no entries for this sensor.
§Errors
SizeMismatchif the stored payload is notsize_of::<T>() + 1bytesSchemaMismatchif it was written under anotherSCHEMA_VERSIONof this type
§Example
if let Some((hdr, temp)) = db.latest_sensor::<Temperature>()? {
println!("Temperature: {} °C at {}", temp.celsius, hdr.timestamp);
}Sourcepub fn query_sensor<T: SensorData, C>(
&mut self,
t_start: u64,
t_end: u64,
callback: C,
) -> Result<u32, Error>
pub fn query_sensor<T: SensorData, C>( &mut self, t_start: u64, t_end: u64, callback: C, ) -> Result<u32, Error>
Query sensor entries within a time range using the type-driven API.
This is the Layer 2 API where the sensor ID is derived from the type.
The data type must implement SensorData.
§Arguments
t_start: Start timestamp (inclusive)t_end: End timestamp (inclusive)callback: Called for each matching entry with the header and typed value. Returnfalseto stop early.
§Returns
Number of entries that matched and were successfully deserialized.
§Example
let count = db.query_sensor::<Temperature, _>(t_start, t_end, |hdr, temp| {
println!("{}: {} °C", hdr.timestamp, temp.celsius);
true // continue iterating
})?;Sourcepub fn query_all_sensor<T: SensorData, C>(
&mut self,
callback: C,
) -> Result<u32, Error>
pub fn query_all_sensor<T: SensorData, C>( &mut self, callback: C, ) -> Result<u32, Error>
Query all entries for a sensor type without time constraints.
This is a convenience wrapper that queries all entries for the sensor type.
§Arguments
callback: Called for each matching entry with the header and typed value. Returnfalseto stop early.
§Returns
Number of entries that matched and were successfully deserialized.
§Example
let count = db.query_all_sensor::<Temperature, _>(|hdr, temp| {
println!("{}: {} °C", hdr.timestamp, temp.celsius);
true
})?;Sourcepub fn oldest_sensor<T: SensorData>(
&mut self,
) -> Result<Option<(EntryHeader, T)>, Error>
pub fn oldest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>
Find the oldest (earliest) entry for a sensor type.
§Returns
Some((header, value)) if found, None if no entries for this sensor.
§Errors
SizeMismatchif the stored payload size doesn’t matchsize_of::<T>()InvalidDataif the bytes cannot be interpreted as typeT
§Example
if let Some((hdr, temp)) = db.oldest_sensor::<Temperature>()? {
println!("First reading: {} °C at {}", temp.celsius, hdr.timestamp);
}Sourcepub fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>
pub fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>
Sourcepub fn read_from<C>(
&mut self,
from: LogPosition,
max_entries: u32,
callback: C,
) -> Result<ReadCursor, Error>
pub fn read_from<C>( &mut self, from: LogPosition, max_entries: u32, callback: C, ) -> Result<ReadCursor, Error>
Deliver committed entries in log order, starting at from (inclusive).
This is the read side of replication: it walks the log as a stream rather than a query, so a copy can be resumed from a durable position after a reboot or after the destination went away.
§Durability boundary
Only entries that are durable on flash are delivered. Entries still
sitting in the page buffer are excluded, so a caller replicating this log
never copies something the source itself could still lose to a power cut.
Call sync first to make the tail eligible.
§Arguments
from: where to resume. UseLogPosition::BEGINNINGto start at whatever the log still retains.max_entries: upper bound on entries delivered in this pass. Bounds both the work done and, for a replicating caller, the amount that has to be redone after a crash.callback: receives each entry’s position, header, and payload. ReturnOk(false)to stop, rejecting the entry just offered; returnErrto abort the pass.
§Rejection semantics
Ok(false) means “I did not take this one, and I want to stop”. The
entry is not counted in ReadCursor::entries and
ReadCursor::next stops before it, so resuming from next
re-offers it. Likewise, an Err from the callback leaves next at the
last entry the callback actually accepted.
This is the opposite of query_range, where
returning false stops after consuming the entry — and deliberately
so. A caller forwarding this stream to somewhere else must be able to
decline an entry (because the destination is full, or the batch has
reached a boundary) without the log recording it as delivered.
The callback returns Result<bool, Error> rather than a bare bool
because its dominant use is writing each entry somewhere that can fail;
a bare bool would force every such caller to smuggle the error out
through captured state.
§Ordering
Entries are delivered in write order (ascending sector sequence, then
ascending offset), which is not necessarily timestamp order — the same
caveat as query_range.
§Errors
NotMountedif the database is not mounted- whatever the callback returns
Sourcepub fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
pub fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
Hand out entries that are buffered in RAM but not yet durable, then discard them from this database.
Touches no flash. This is what makes it usable when the underlying device has physically gone away: a removable medium can be pulled mid-page, and the entries still sitting in the page buffer are recovered into RAM and can be re-appended somewhere that still exists. A yank is not a power loss — the processor is still running, so nothing needs to be lost.
Entries already durable on flash are left alone; only the RAM-only tail is drained. On return the page buffer is truncated to its durable prefix and the entry accounting is adjusted to match.
“Durable” here means written to flash, which is not the same as the
entry’s committed flag: a commit pass that failed part-way leaves entries
flagged committed in RAM that flash never received. Those are drained,
because a later mount would not see them.
The per-sector bloom filter and timestamp range are not rolled back — they may stay wider than the data warrants, which costs a redundant sector scan on some queries but never returns a wrong answer.
§Returns
The number of entries handed to the callback.
§Errors
NotMountedif the database is not mounted- whatever the callback returns; the drain stops there and the buffer is left untouched, so the operation can be retried
Sourcepub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
pub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
Show the entries that are buffered in RAM but not yet durable, without removing them.
The non-destructive twin of drain_unflushed,
and the piece read_from deliberately leaves out:
read_from streams only what flash has, because a replica must never be
told about data the source could still lose, whereas a reader of this
log should see everything the log holds. Composing the two covers the
whole log from a position.
Touches no flash, so it costs nothing, works on a device that has gone
away, and is one of the few reads that still takes &self.
§Errors
NotMountedif the database is not mounted- whatever the callback returns, which stops the walk
Sourcepub fn sector_epoch_at(
&mut self,
position: LogPosition,
) -> Result<Option<u32>, Error>
pub fn sector_epoch_at( &mut self, position: LogPosition, ) -> Result<Option<u32>, Error>
The epoch of the sector containing position.
Reads the sector header from flash on demand rather than caching an
epoch per sector in RAM — with MAX_SECTORS = 512 that cache would cost
2 KB for a field consulted once per replication batch.
Returns None when no retained sector holds that position, which is the
normal answer for a position that has fallen off the tail of the ring.
Sourcepub fn head_position(&self) -> LogPosition
pub fn head_position(&self) -> LogPosition
Position immediately after the newest entry, buffered entries included.
Note this can be ahead of what read_from will
deliver, which stops at the durable tail. Returns
LogPosition::BEGINNING when there is no active sector.
Sourcepub fn tail_position(&self) -> LogPosition
pub fn tail_position(&self) -> LogPosition
Position of the oldest entry the log still retains.
A read_from starting before this reports a gap.
Returns LogPosition::BEGINNING when the log is empty.
Sourcepub fn with_region<R>(
&mut self,
base: u32,
len: u32,
f: impl FnOnce(&mut Partition<&mut F>) -> R,
) -> Result<R, Error>
pub fn with_region<R>( &mut self, base: u32, len: u32, f: impl FnOnce(&mut Partition<&mut F>) -> R, ) -> Result<R, Error>
Run f with flash access bounded to [base, base + len).
This is how something else on the same chip — a config store, a
replication cursor, a firmware slot — reaches the device the database
owns by value. The closure gets a Partition, so its offsets are
relative to base and an access past len is
PartitionError::OutOfBounds
rather than a write into a neighbour.
A region intersecting [base_offset, base_offset + sector_count * sector_size) is rejected with Error::RegionOverlap. That check is
the point of this method: writing inside the database region behind the
database’s back corrupts the log, the in-RAM index silently disagrees
with flash, and nothing surfaces until a later mount.
For a driver capability rather than a region — presence detection, a
wear counter, a chip id, deep power-down — use
driver_mut.
§Errors
RegionOverlapif the region intersects the database’s sectorsInvalidConfigifbaseorlenis misaligned,lenis zero, or the region runs past the device’s capacityOverflowifbase + lendoes not fit inu32
// Read the config block that lives just below the log.
let mut buf = [0u8; 64];
db.with_region(CONFIG_BASE, CONFIG_LEN, |p| p.read(0, &mut buf))??;Sourcepub fn driver_mut(&mut self) -> &mut F
pub fn driver_mut(&mut self) -> &mut F
Borrow the underlying flash driver.
For capabilities that belong to the driver rather than to any region of
the chip: presence detection, wear counters, chip identification, power
modes, and test introspection. The database owns F by value, so without
this nothing else can reach those.
§Correctness
This is the unbounded escape hatch, and nothing here can enforce
anything: F is a NorFlash, so a caller can write anywhere on the
chip. Do not address flash through it. Use
with_region, which is checked.
Sourcepub fn note_spooled(&mut self, upto: LogPosition, moved: Replicated)
pub fn note_spooled(&mut self, upto: LogPosition, moved: Replicated)
Advance the replication watermark.
Call this only after moved, ending at upto, is durably stored
somewhere else. Advancing it early is the one way to turn this design’s
at-least-once guarantee into data loss: the watermark is what tells the
ring which sectors are safe to overwrite first.
Monotonic — an upto at or behind the current watermark is ignored, so
replaying an old acknowledgement cannot move it backwards.
Sourcepub fn restore_spool_watermark(
&mut self,
upto: LogPosition,
) -> Result<(), Error>
pub fn restore_spool_watermark( &mut self, upto: LogPosition, ) -> Result<(), Error>
Restore the replication watermark from an external source of truth.
mount deliberately cannot recover this: the watermark
lives on the replica, which is what lets two removable media be rotated
against one log with no local state. Until a replica reappears and calls
this, spool_stats reports everything as
un-replicated — the safe direction, because it can only cause redundant
copying, never loss.
Accounting is recomputed from the in-RAM index for whole sectors, plus one
scan of the sector the watermark falls inside — the index knows how many
entries a sector holds but not where each one starts, so the entries below
the watermark within that sector have to be counted off flash. The result
matches what note_spooled would have accumulated
had the replica never gone away.
§Errors
Only from that one scan, and only ever Flash. The watermark itself is
restored before the scan and stays restored, because it is the part that
matters: it is what tells the ring which sectors are safe to overwrite.
An Err therefore means the log is fully usable and only
spool_stats is degraded — it over-reports
unspooled_entries by at most one sector’s worth, the same conservative
answer this method used to give unconditionally.
Sourcepub fn spool_stats(&self) -> SpoolStats
pub fn spool_stats(&self) -> SpoolStats
Replication accounting for this log.
unspooled_entries is O(1). See SpoolStats for the meaning of each
field, and note that data_lost is sticky.
Sourcepub fn epoch(&self) -> u32
pub fn epoch(&self) -> u32
The current epoch — one higher than any epoch found on the medium at mount.
Stamped into every sector header this run creates, which is what lets a reader attribute data to a particular run of a device whose clock restarts at zero on every boot.
§How a run’s epoch reaches the medium
Epochs live in sector headers, so a run only records one by creating a sector. To keep the attribution exact, the first append after a mount rolls to a fresh sector rather than continuing in the one the previous run left open. Every entry a run writes therefore sits in a sector stamped with that run’s epoch.
The roll is deferred to the first append, so a run that only reads costs nothing. A run that writes costs one extra sector transition — one erase, plus whatever space was left unused in the inherited sector. That is cheap when reboots are rare, which is the case this is built for.
If the ring is completely full and cannot yield a sector, the roll is
skipped rather than failing the append: losing epoch precision is always
preferable to losing a sample. Replication correctness never depends on
the epoch — it rests on LogPosition.
Sourcepub fn mount_mode(&self) -> MountMode
pub fn mount_mode(&self) -> MountMode
How much of the index the current mount rebuilt.
Sourcepub fn mark_as_replica(&mut self)
pub fn mark_as_replica(&mut self)
Declare this log a replica of another, suppressing the per-run epoch roll.
A primary log rolls to a fresh sector on its first append after a mount
so that the run’s epoch is recorded on the medium. For a
replica that is pure waste: its entries are copies, and their provenance
lives in the replication cursor, not in this log’s sector headers. Left
enabled it would burn a sector — and on a full ring, evict the oldest one
— every single time the medium is inserted.
Spooler::attach calls this, so a
volume managed by a spooler needs no action. Call it directly only when
maintaining a replica by hand.
Takes effect for the current mount; call it again after each mount.
Sourcepub fn into_inner(self) -> F
pub fn into_inner(self) -> F
Consume the database and return the underlying flash storage.
Trait Implementations§
Source§impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Debug for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Debug for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
Source§impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSink for SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSink for SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
Source§impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSource for SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSource for SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
Source§fn latest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error>
fn latest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>
None if it has none. Read moreSource§fn oldest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error>
fn oldest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>
None if it has none. Read moreAuto Trait Implementations§
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Freeze for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> RefUnwindSafe for SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: RefUnwindSafe,
SensorDbState<PAGE_SIZE, MAX_SECTORS>: RefUnwindSafe,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Send for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Sync for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Unpin for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> UnsafeUnpin for SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: UnsafeUnpin,
SensorDbState<PAGE_SIZE, MAX_SECTORS>: UnsafeUnpin,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> UnwindSafe for SensorDb<F, PAGE_SIZE, MAX_SECTORS>where
F: UnwindSafe,
SensorDbState<PAGE_SIZE, MAX_SECTORS>: UnwindSafe,
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<L> LogSinkExt for L
impl<L> LogSinkExt for L
Source§fn append_value<T: IntoBytes + Immutable>(
&mut self,
sensor_id: u16,
timestamp: u64,
data: &T,
) -> Result<(), Error>
fn append_value<T: IntoBytes + Immutable>( &mut self, sensor_id: u16, timestamp: u64, data: &T, ) -> Result<(), Error>
Source§fn append_sensor<T: SensorData>(
&mut self,
timestamp: u64,
data: &T,
) -> Result<(), Error>
fn append_sensor<T: SensorData>( &mut self, timestamp: u64, data: &T, ) -> Result<(), Error>
Source§impl<L> LogSourceExt for L
impl<L> LogSourceExt for L
Source§fn latest_sensor<T: SensorData>(
&mut self,
) -> Result<Option<(EntryHeader, T)>, Error>
fn latest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>
Source§fn oldest_sensor<T: SensorData>(
&mut self,
) -> Result<Option<(EntryHeader, T)>, Error>
fn oldest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>
Source§fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>
fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>
Source§fn query_sensor<T: SensorData, C>(
&mut self,
t_start: u64,
t_end: u64,
callback: C,
) -> Result<u32, Error>
fn query_sensor<T: SensorData, C>( &mut self, t_start: u64, t_end: u64, callback: C, ) -> Result<u32, Error>
[t_start, t_end]. Read more