Skip to main content

SensorDb

Struct SensorDb 

Source
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 implementing NorFlash and ReadNorFlash
  • PAGE_SIZE: the unit this database writes in. Must be a multiple of F::WRITE_SIZE — checked at compile time — and must not exceed the part’s physical program page, which embedded-storage does not express and so cannot be checked. Note WRITE_SIZE is 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 × 48 bytes for the in-RAM sector index (SectorSummary array)
  • PAGE_SIZE bytes 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>

Source

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 storage
  • base_offset: Starting offset in flash for the database region
  • sector_count: Number of sectors to use
  • reserved_sectors: Number of sectors to keep free for compaction headroom
§Limits
  • The entire database region (sector_count × ERASE_SIZE + base_offset) must fit within u32 address space (4 GB).
  • SectorSummary.write_offset is u32, supporting individual sectors up to 4 GB.
  • sector_count must not exceed MAX_SECTORS.
§Errors
  • TooManySectors if sector_count > MAX_SECTORS
  • InvalidConfig if reserved_sectors >= sector_count
Source

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
  • TooManySectors if config.sector_count() > MAX_SECTORS
  • Overflow if the region does not fit in u32 address space
§Panics

Fails to compile, not to run, if PAGE_SIZE is not a multiple of F::WRITE_SIZE — the compile-time Geometry assert.

Source

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.

Source

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
  • AlreadyMounted if already mounted
  • ForeignVolume if the medium belongs to a different log
  • UnsupportedVersion if the medium uses a newer format
Source

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
  • AlreadyMounted if already mounted
  • ForeignVolume if the medium belongs to a different log
  • UnsupportedVersion if the medium uses a newer format
Source

pub fn append( &mut self, sensor_id: u16, timestamp: u64, payload: &[u8], ) -> Result<(), Error>

Append a sensor reading to the database.

§Arguments
  • sensor_id: Sensor identifier
  • timestamp: Timestamp (typically microseconds since epoch)
  • payload: Raw sensor data
§Errors
  • NotMounted if not mounted
  • PayloadTooLarge if payload exceeds max size
  • NoSpace if no sectors available
Source

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
  • NotMounted if not mounted
  • PayloadTooLarge if the framed run exceeds max_payload_size; split the burst
  • NoSpace if no sectors available
Source

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
  • CorruptEntry if the header claims a run and the payload is not one
  • otherwise as append
Source

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.

Source

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 query
  • buf: Buffer to receive payload
§Returns

Some((header, payload_len)) if found, None if no entries for this sensor.

Source

pub fn query_range<C>( &mut self, sensor_id: Option<u16>, t_start: u64, t_end: u64, callback: C, ) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &[u8]) -> bool,

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. Return false to 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.

Source

pub fn query_all<C>( &mut self, sensor_id: Option<u16>, callback: C, ) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &[u8]) -> bool,

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. Return false to 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
})?;
Source

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 query
  • buf: 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);
}
Source

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)?;
Source

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 erase
  • scope: Which sealed sectors are eligible. Use CompactScope::SpooledOnly to reclaim space without destroying anything that has not been replicated yet.
§Returns

Number of sectors actually erased.

Source

pub fn stats(&self) -> DbStats

Get database statistics.

Source

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.

Source

pub fn is_mounted(&self) -> bool

Check if the database is mounted.

Source

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.

Source

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 identifier
  • timestamp: 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 })?;
Source

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
  • SizeMismatch if the stored payload size doesn’t match size_of::<T>()
  • InvalidData if the bytes cannot be interpreted as type T
§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);
}
Source

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.

Source

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
  • SizeMismatch if the stored payload is not size_of::<T>() + 1 bytes
  • SchemaMismatch if it was written under another SCHEMA_VERSION of this type
§Example
ⓘ
if let Some((hdr, temp)) = db.latest_sensor::<Temperature>()? {
    println!("Temperature: {} °C at {}", temp.celsius, hdr.timestamp);
}
Source

pub fn query_sensor<T: SensorData, C>( &mut self, t_start: u64, t_end: u64, callback: C, ) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &T) -> bool,

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. Return false to 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
})?;
Source

pub fn query_all_sensor<T: SensorData, C>( &mut self, callback: C, ) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &T) -> bool,

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. Return false to 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
})?;
Source

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
  • SizeMismatch if the stored payload size doesn’t match size_of::<T>()
  • InvalidData if the bytes cannot be interpreted as type T
§Example
ⓘ
if let Some((hdr, temp)) = db.oldest_sensor::<Temperature>()? {
    println!("First reading: {} °C at {}", temp.celsius, hdr.timestamp);
}
Source

pub fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>

Count entries for a sensor type.

§Returns

Number of entries for this sensor type.

§Example
ⓘ
let temp_count = db.count_sensor::<Temperature>()?;
Source

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. Use LogPosition::BEGINNING to 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. Return Ok(false) to stop, rejecting the entry just offered; return Err to 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
  • NotMounted if the database is not mounted
  • whatever the callback returns
Source

pub fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &[u8]) -> Result<(), 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
  • NotMounted if 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
Source

pub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &[u8]) -> Result<(), 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
  • NotMounted if the database is not mounted
  • whatever the callback returns, which stops the walk
Source

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.

Source

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.

Source

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.

Source

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
  • RegionOverlap if the region intersects the database’s sectors
  • InvalidConfig if base or len is misaligned, len is zero, or the region runs past the device’s capacity
  • Overflow if base + len does not fit in u32
ⓘ
// 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))??;
Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn log_id(&self) -> Option<LogId>

This log’s declared identity, if any.

Source

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.

Source

pub fn mount_mode(&self) -> MountMode

How much of the index the current mount rebuilt.

Source

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.

Source

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>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSink for SensorDb<F, PAGE_SIZE, MAX_SECTORS>

Source§

fn append( &mut self, sensor_id: u16, timestamp: u64, payload: &[u8], ) -> Result<(), Error>

Append a sample.
Source§

fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error>

Append a run: many evenly spaced samples under one header. Read more
Source§

fn sync(&mut self) -> Result<(), Error>

Make everything appended so far durable.
Source§

impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSource for SensorDb<F, PAGE_SIZE, MAX_SECTORS>

Source§

fn latest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>

The most recent entry for a sensor, or None if it has none. Read more
Source§

fn oldest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>

The oldest retained entry for a sensor, or None if it has none. Read more
Source§

fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error>

Entries retained for a sensor, or for every sensor if None.
Source§

fn query_range( &mut self, sensor_id: Option<u16>, t_start: u64, t_end: u64, callback: &mut dyn FnMut(&EntryHeader, &[u8]) -> bool, ) -> Result<u32, Error>

Entries whose timestamp lies in [t_start, t_end], in log order. Read more

Auto Trait Implementations§

§

impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Freeze for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
where F: Freeze, SensorDbState<PAGE_SIZE, MAX_SECTORS>: Freeze,

§

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>
where F: Send, SensorDbState<PAGE_SIZE, MAX_SECTORS>: Send,

§

impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Sync for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
where F: Sync, SensorDbState<PAGE_SIZE, MAX_SECTORS>: Sync,

§

impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Unpin for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
where F: Unpin, SensorDbState<PAGE_SIZE, MAX_SECTORS>: Unpin,

§

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> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<L> LogSinkExt for L
where L: LogSink + ?Sized,

Source§

fn append_value<T: IntoBytes + Immutable>( &mut self, sensor_id: u16, timestamp: u64, data: &T, ) -> Result<(), Error>

Append a value’s bytes under an explicit sensor ID. Read more
Source§

fn append_sensor<T: SensorData>( &mut self, timestamp: u64, data: &T, ) -> Result<(), Error>

Append a value under the sensor ID its type declares. Read more
Source§

impl<L> LogSourceExt for L
where L: LogSource + ?Sized,

Source§

fn latest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>

The most recent value for a sensor type.
Source§

fn oldest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>

The oldest retained value for a sensor type.
Source§

fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>

Entries retained for a sensor type.
Source§

fn query_sensor<T: SensorData, C>( &mut self, t_start: u64, t_end: u64, callback: C, ) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &T) -> bool,

Values for a sensor type whose timestamp lies in [t_start, t_end]. Read more
Source§

fn query_all_sensor<T: SensorData, C>( &mut self, callback: C, ) -> Result<u32, Error>
where C: FnMut(&EntryHeader, &T) -> bool,

Every retained value for a sensor type, in log order.
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.