pub struct SensorDbAsync<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> { /* private fields */ }async only.Expand description
Async append-only sensor database for NOR flash.
This is the async counterpart of SensorDb, using
embedded-storage-async traits for all flash operations. It is designed
for use with Embassy on targets that benefit from DMA-based flash access.
§Key differences from SensorDb
- All flash-touching methods are
async fn - All methods take
&mut self(noRefCell/ interior mutability) - Reuses the same wire format, sector layout, and
SensorDbStatevalue
Generic parameters:
F: Flash storage implementing asyncNorFlashandReadNorFlashPAGE_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 — which the trait does not express, so it cannot be checked. SeeSensorDbfor the full contract.MAX_SECTORS: Maximum number of sectors this instance can manage
Implementations§
Source§impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDbAsync<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 async SensorDb instance.
§Arguments
flash: Async 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
§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 SensorDbAsync 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.
Sourcepub async fn format(&mut self) -> Result<(), Error>
pub async 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.
Sourcepub async fn mount(&mut self) -> Result<MountStats, Error>
pub async 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 async fn mount_with(&mut self, mode: MountMode) -> Result<MountStats, Error>
pub async fn mount_with(&mut self, mode: MountMode) -> Result<MountStats, Error>
Mount an existing database, choosing how much of the index to rebuild.
See SensorDb::mount_with for the
foreign-media and epoch semantics; they are identical here.
§Errors
AlreadyMountedif already mountedForeignVolumeif the medium belongs to a different logUnsupportedVersionif the medium uses a newer format
Sourcepub async fn append(
&mut self,
sensor_id: u16,
timestamp: u64,
payload: &[u8],
) -> Result<(), Error>
pub async fn append( &mut self, sensor_id: u16, timestamp: u64, payload: &[u8], ) -> Result<(), Error>
Append a sensor reading to the database.
§Errors
NotMountedif not mountedPayloadTooLargeif payload exceeds max sizeNoSpaceif no sectors available
Sourcepub async fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error>
pub async fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error>
Append a run: many evenly spaced samples under one header.
Async mirror of SensorDb::append_run,
including its invisibility to every read.
Sourcepub async fn append_framed(
&mut self,
header: &EntryHeader,
payload: &[u8],
) -> Result<(), Error>
pub async fn append_framed( &mut self, header: &EntryHeader, payload: &[u8], ) -> Result<(), Error>
Append an entry exactly as another log stored it.
Async mirror of
SensorDb::append_framed.
Sourcepub async fn sync(&mut self) -> Result<(), Error>
pub async fn sync(&mut self) -> Result<(), Error>
Flush the page buffer to flash, committing buffered entries.
Sourcepub async fn latest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error>
pub async fn latest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>
Sourcepub async fn query_range<C>(
&mut self,
sensor_id: Option<u16>,
t_start: u64,
t_end: u64,
callback: C,
) -> Result<u32, Error>
pub async fn query_range<C>( &mut self, sensor_id: Option<u16>, t_start: u64, t_end: u64, callback: C, ) -> Result<u32, Error>
Sourcepub async fn query_all<C>(
&mut self,
sensor_id: Option<u16>,
callback: C,
) -> Result<u32, Error>
pub async 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.
Sourcepub async fn oldest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error>
pub async fn oldest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> Result<Option<(EntryHeader, usize)>, Error>
Find the oldest (earliest) entry for a given sensor.
Sourcepub async fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error>
pub async fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error>
Count entries for a specific sensor (or all sensors).
Exact, and priced, exactly as SensorDb::count
— the count matches what query_range would yield,
at the cost of a payload read per entry in each sector the bloom filter
does not reject.
Sourcepub async fn compact(
&mut self,
count: u16,
scope: CompactScope,
) -> Result<u16, Error>
pub async fn compact( &mut self, count: u16, scope: CompactScope, ) -> Result<u16, Error>
Compact the database by erasing the oldest sealed sectors.
See SensorDb::compact for the meaning of
scope.
Sourcepub fn sectors_erased(&self) -> u32
pub fn sectors_erased(&self) -> u32
Sectors this instance has erased, since it was created.
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.
Sourcepub async fn append_value<T: IntoBytes + Immutable>(
&mut self,
sensor_id: u16,
timestamp: u64,
data: &T,
) -> Result<(), Error>
pub async fn append_value<T: IntoBytes + Immutable>( &mut self, sensor_id: u16, timestamp: u64, data: &T, ) -> Result<(), Error>
Append a typed value with an explicit sensor ID, untagged.
Entries written this way carry no schema version and are not readable
through the *_sensor methods.
Sourcepub async fn latest_value<T: FromBytes + KnownLayout>(
&mut self,
sensor_id: u16,
) -> Result<Option<(EntryHeader, T)>, Error>
pub async fn latest_value<T: FromBytes + KnownLayout>( &mut self, sensor_id: u16, ) -> Result<Option<(EntryHeader, T)>, Error>
Find the most recent entry for a sensor and interpret as a typed value.
Sourcepub async fn append_sensor<T: SensorData>(
&mut self,
timestamp: u64,
data: &T,
) -> Result<(), Error>
pub async fn append_sensor<T: SensorData>( &mut self, timestamp: u64, data: &T, ) -> Result<(), Error>
Append a sensor reading using the type-driven API.
The payload is the type’s SCHEMA_VERSION followed by the value’s
bytes; see SensorData::SCHEMA_VERSION.
Sourcepub async fn latest_sensor<T: SensorData>(
&mut self,
) -> Result<Option<(EntryHeader, T)>, Error>
pub async fn latest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>
Find the most recent entry for a sensor type.
§Errors
SizeMismatchif the stored payload is notsize_of::<T>() + 1bytesSchemaMismatchif it was written under anotherSCHEMA_VERSION
Sourcepub async fn query_sensor<T: SensorData, C>(
&mut self,
t_start: u64,
t_end: u64,
callback: C,
) -> Result<u32, Error>
pub async 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.
Sourcepub async fn query_all_sensor<T: SensorData, C>(
&mut self,
callback: C,
) -> Result<u32, Error>
pub async fn query_all_sensor<T: SensorData, C>( &mut self, callback: C, ) -> Result<u32, Error>
Query all entries for a sensor type without time constraints.
Sourcepub async fn oldest_sensor<T: SensorData>(
&mut self,
) -> Result<Option<(EntryHeader, T)>, Error>
pub async fn oldest_sensor<T: SensorData>( &mut self, ) -> Result<Option<(EntryHeader, T)>, Error>
Find the oldest (earliest) entry for a sensor type.
Sourcepub async fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>
pub async fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error>
Count entries for a sensor type.
Sourcepub async fn read_from<C>(
&mut self,
from: LogPosition,
max_entries: u32,
callback: C,
) -> Result<ReadCursor, Error>
pub async 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).
Async mirror of SensorDb::read_from; see
there for the durability boundary, ordering, and gap semantics.
§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 buffered in RAM but not yet durable, then discard them.
Async mirror of
SensorDb::drain_unflushed. Touches
no flash, so it works when the device has physically gone away.
Sourcepub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
pub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
Show the RAM-buffered entries without removing them.
Async mirror of
SensorDb::peek_unflushed. Not
async: it touches no flash.
Sourcepub async fn sector_epoch_at(
&mut self,
position: LogPosition,
) -> Result<Option<u32>, Error>
pub async fn sector_epoch_at( &mut self, position: LogPosition, ) -> Result<Option<u32>, Error>
The epoch of the sector containing position.
Async mirror of
SensorDb::sector_epoch_at.
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.
Sourcepub fn head_position(&self) -> LogPosition
pub fn head_position(&self) -> LogPosition
Position immediately after the newest entry, buffered entries included.
Sourcepub fn tail_position(&self) -> LogPosition
pub fn tail_position(&self) -> LogPosition
Position of the oldest entry the log still retains.
Sourcepub fn note_spooled(&mut self, upto: LogPosition, moved: Replicated)
pub fn note_spooled(&mut self, upto: LogPosition, moved: Replicated)
Advance the replication watermark. See
SensorDb::note_spooled.
Sourcepub async fn restore_spool_watermark(
&mut self,
upto: LogPosition,
) -> Result<(), Error>
pub async fn restore_spool_watermark( &mut self, upto: LogPosition, ) -> Result<(), Error>
Restore the replication watermark from an external source of truth. See
SensorDb::restore_spool_watermark,
including why an Err leaves the log fully usable.
async because exact accounting costs one scan of the sector the
watermark falls inside.
Sourcepub fn spool_stats(&self) -> SpoolStats
pub fn spool_stats(&self) -> SpoolStats
Replication accounting for this log.
Sourcepub fn epoch(&self) -> u32
pub fn epoch(&self) -> u32
The current epoch — one higher than any epoch seen on the medium at mount.
Sourcepub fn mount_mode(&self) -> MountMode
pub fn mount_mode(&self) -> MountMode
How much of the index the current mount rebuilt.
Sourcepub fn region(
&mut self,
base: u32,
len: u32,
) -> Result<Partition<&mut F>, Error>
pub fn region( &mut self, base: u32, len: u32, ) -> Result<Partition<&mut F>, Error>
Flash access bounded to [base, base + len).
The async counterpart of
SensorDb::with_region, and it returns
the Partition rather than taking a closure: a closure cannot express
an awaited operation, because the future it returned would borrow from
its own argument and the signature has nowhere to tie that lifetime to.
The same check applies — a region intersecting the database’s sectors is
rejected with Error::RegionOverlap — and it applies at the point the
partition is handed out, which is the only place it can be applied.
§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
Sourcepub fn driver_mut(&mut self) -> &mut F
pub fn driver_mut(&mut self) -> &mut F
Borrow the underlying flash driver.
See SensorDb::driver_mut: driver
capabilities only — presence detection, wear counters, chip
identification, power modes. To address flash, use
region, which is checked.
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 SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Debug for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
Source§impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSinkAsync for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSinkAsync for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
Source§impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSourceAsync for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> LogSourceAsync for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>where
F: NorFlash + ReadNorFlash,
Source§fn latest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> impl Future<Output = Result<Option<(EntryHeader, usize)>, Error>>
fn latest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> impl Future<Output = Result<Option<(EntryHeader, usize)>, Error>>
None if it has none.Source§fn oldest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> impl Future<Output = Result<Option<(EntryHeader, usize)>, Error>>
fn oldest( &mut self, sensor_id: u16, buf: &mut [u8], ) -> impl Future<Output = Result<Option<(EntryHeader, usize)>, Error>>
None if it has none.Auto Trait Implementations§
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Freeze for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> RefUnwindSafe for SensorDbAsync<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 SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Sync for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Unpin for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> UnsafeUnpin for SensorDbAsync<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 SensorDbAsync<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> LogSinkAsyncExt for Lwhere
L: LogSinkAsync + ?Sized,
impl<L> LogSinkAsyncExt for Lwhere
L: LogSinkAsync + ?Sized,
Source§fn append_value<T: IntoBytes + Immutable>(
&mut self,
sensor_id: u16,
timestamp: u64,
data: &T,
) -> impl Future<Output = Result<(), Error>>
fn append_value<T: IntoBytes + Immutable>( &mut self, sensor_id: u16, timestamp: u64, data: &T, ) -> impl Future<Output = Result<(), Error>>
Source§fn append_sensor<T: SensorData>(
&mut self,
timestamp: u64,
data: &T,
) -> impl Future<Output = Result<(), Error>>
fn append_sensor<T: SensorData>( &mut self, timestamp: u64, data: &T, ) -> impl Future<Output = Result<(), Error>>
Source§impl<L> LogSourceAsyncExt for Lwhere
L: LogSourceAsync + ?Sized,
impl<L> LogSourceAsyncExt for Lwhere
L: LogSourceAsync + ?Sized,
Source§fn latest_sensor<T: SensorData>(
&mut self,
) -> impl Future<Output = Result<Option<(EntryHeader, T)>, Error>>
fn latest_sensor<T: SensorData>( &mut self, ) -> impl Future<Output = Result<Option<(EntryHeader, T)>, Error>>
Source§fn oldest_sensor<T: SensorData>(
&mut self,
) -> impl Future<Output = Result<Option<(EntryHeader, T)>, Error>>
fn oldest_sensor<T: SensorData>( &mut self, ) -> impl Future<Output = Result<Option<(EntryHeader, T)>, Error>>
Source§fn count_sensor<T: SensorData>(
&mut self,
) -> impl Future<Output = Result<u32, Error>>
fn count_sensor<T: SensorData>( &mut self, ) -> impl Future<Output = Result<u32, Error>>
Source§fn query_sensor<T: SensorData, C>(
&mut self,
t_start: u64,
t_end: u64,
callback: C,
) -> impl Future<Output = Result<u32, Error>>
fn query_sensor<T: SensorData, C>( &mut self, t_start: u64, t_end: u64, callback: C, ) -> impl Future<Output = Result<u32, Error>>
[t_start, t_end].