sensor-db 0.1.0

Append-only sensor database for NOR flash on embedded devices
Documentation
//! Sharing one log between threads.
//!
//! ```sh
//! cargo run --example multithread
//! ```
//!
//! The desktop stand-in for "two Embassy tasks, or both RP2350 cores, logging to
//! the same flash". See `examples/multithread_async.rs` for the async form,
//! which is the one you actually want on Embassy.
//!
//! # `Mutex`, not `RwLock`
//!
//! `SensorDb<F, ..>` is `Send + Sync` whenever `F` is, so an `RwLock` compiles.
//! It would buy nothing. Reading flash goes through `ReadNorFlash::read(&mut
//! self)`, so *every* method — `latest` and `count` as much as `append` — needs
//! `&mut`, which means the write half of the lock. An `RwLock` whose read half
//! is never taken is a `Mutex` with extra steps.
//!
//! This is worth stating because it used to be a hard constraint rather than a
//! judgement: `SensorDb` held its driver in a `RefCell` to offer `&self` reads,
//! which made it `!Sync` and left `Mutex` as the only thing that compiled.
//!
//! # What the lock scope costs
//!
//! Hold it for one operation, not for a batch of them. A `sync()` is two page
//! writes — microseconds on real NOR — but a `sync()` that happens to seal a
//! sector also erases, and an erase is **100 ms or more**. Whoever is waiting on
//! the mutex waits for that too. If a reader has a latency budget, either sync
//! from one place on a known schedule or give the reader its own snapshot.

use std::sync::{Arc, Mutex};
use std::thread;

use sensor_db::mock::MockFlash;
use sensor_db::{Error, SensorData, SensorDb};
use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};

#[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Temperature {
    celsius_x100: i32,
}

impl SensorData for Temperature {
    const SENSOR_ID: u16 = 0x01;
}

const PAGE: usize = 256;
const SECTOR: usize = 4096;
const SECTORS: usize = 16;

type Db = SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS>;

/// Two producers, one consumer, this many readings each.
const PER_WRITER: u64 = 250;
const WRITERS: u64 = 2;

fn main() -> Result<(), Error> {
    println!("=== sharing one log between threads ===\n");

    // The property that makes this possible at all, checked at compile time.
    fn assert_shareable<T: Send + Sync>() {}
    assert_shareable::<Db>();

    let mut db: Db = SensorDb::new(
        MockFlash::new(SECTORS * SECTOR),
        0,
        SECTORS as u16,
        2, // reserved sectors
    )?;
    db.format()?;

    let db = Arc::new(Mutex::new(db));

    // -------------------------------------------------------------------
    // Writers. Each owns a disjoint timestamp range so the log can be checked
    // exactly afterwards, rather than approximately.
    // -------------------------------------------------------------------
    let writers: Vec<_> = (0..WRITERS)
        .map(|w| {
            let db = Arc::clone(&db);
            thread::spawn(move || {
                for i in 0..PER_WRITER {
                    let ts = w * PER_WRITER + i;
                    // Lock scope: one append. Reopening the mutex per reading
                    // is far cheaper than the flash write it guards.
                    let mut db = db.lock().unwrap();
                    db.append_sensor(
                        ts,
                        &Temperature {
                            celsius_x100: 2_000 + ts as i32,
                        },
                    )
                    .unwrap();
                }
            })
        })
        .collect();

    // -------------------------------------------------------------------
    // Reader. Runs concurrently and must never observe a torn or invented
    // entry — only ever fewer entries than have been written by then.
    // -------------------------------------------------------------------
    let reader = {
        let db = Arc::clone(&db);
        thread::spawn(move || {
            let mut observed = 0u32;
            for _ in 0..200 {
                let mut db = db.lock().unwrap();

                // Reads see the RAM page buffer as well as flash, so an
                // un-synced append is already visible here. `sync()` is for
                // durability, never for read visibility.
                let count = db.count_sensor::<Temperature>().unwrap();
                assert!(
                    count >= observed,
                    "the log is append-only: a count must never go backwards"
                );
                observed = count;

                if let Some((header, value)) = db.latest_sensor::<Temperature>().unwrap() {
                    // Whatever we get must be a reading someone actually wrote.
                    assert_eq!(value.celsius_x100, 2_000 + header.timestamp as i32);
                }
            }
            observed
        })
    };

    for w in writers {
        w.join().unwrap();
    }
    let seen_by_reader = reader.join().unwrap();

    // -------------------------------------------------------------------
    // Durability is a separate decision from visibility, so it gets a separate
    // call — once, at the end, by whoever owns the lifecycle.
    // -------------------------------------------------------------------
    let mut db = db.lock().unwrap();
    db.sync()?;

    let total = PER_WRITER * WRITERS;
    println!("  {WRITERS} writers x {PER_WRITER} readings = {total}");
    println!("  reader observed up to           {seen_by_reader} while they ran");
    println!(
        "  stored after join + sync        {}",
        db.count_sensor::<Temperature>()?
    );

    assert_eq!(
        db.count_sensor::<Temperature>()?,
        total as u32,
        "every append from every thread must be present"
    );

    // And every timestamp exactly once — no duplicates, no gaps.
    let mut seen = vec![false; total as usize];
    db.query_all_sensor::<Temperature, _>(|h, _| {
        assert!(!seen[h.timestamp as usize], "no reading may appear twice");
        seen[h.timestamp as usize] = true;
        true
    })?;
    assert!(seen.iter().all(|&s| s), "no reading may be missing");
    println!("  every timestamp present exactly once");

    println!("\nOK");
    Ok(())
}