sensor-db 0.1.0

Append-only sensor database for NOR flash on embedded devices
Documentation
//! Sharing one log between async tasks — the Embassy shape.
//!
//! ```sh
//! cargo run --example multithread_async --features async
//! ```
//!
//! Two tasks interleaving on one executor, contending for one
//! [`SensorDbAsync`] through an `embassy_sync::mutex::Mutex`. That is the same
//! crate and the same type you would use on the device, so the body of each task
//! transfers unchanged.
//!
//! # Mapping to RP2350
//!
//! | Here (std)                          | On the device                                            |
//! |-------------------------------------|----------------------------------------------------------|
//! | `run_both` (20 lines, below)        | `embassy_executor::Executor`, or `spawn_core1` for core 1 |
//! | `AsyncFlash<MockFlash<256, 4096>>`  | `embassy_rp::flash::Flash<'_, FLASH, Async, FLASH_SIZE>`  |
//! | `Ticks` counter                     | `embassy_time::Instant::now()`                            |
//! | returning from the task future      | `Timer::after_millis(..).await` in a `loop`               |
//! | `embassy_sync::mutex::Mutex`        | the identical `embassy_sync::mutex::Mutex`                |
//!
//! ```ignore
//! use embassy_rp::flash::{Async, Flash, FLASH_SIZE};
//! use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
//! use embassy_sync::mutex::Mutex;
//! use sensor_db::SensorDbAsync;
//!
//! type Db = SensorDbAsync<Flash<'static, FLASH, Async, FLASH_SIZE>, 256, 512>;
//! static DB: StaticCell<Mutex<CriticalSectionRawMutex, Db>> = StaticCell::new();
//!
//! #[embassy_executor::task]
//! async fn sampler(db: &'static Mutex<CriticalSectionRawMutex, Db>) {
//!     loop {
//!         {
//!             let mut db = db.lock().await;
//!             db.append_sensor(Instant::now().as_micros(), &read_sensor()).await.ok();
//!         } // lock released before the wait — never hold it across a Timer
//!         Timer::after_millis(100).await;
//!     }
//! }
//!
//! #[embassy_executor::task]
//! async fn flusher(db: &'static Mutex<CriticalSectionRawMutex, Db>) {
//!     loop {
//!         Timer::after_secs(10).await;
//!         db.lock().await.sync().await.ok();   // durability on a known schedule
//!     }
//! }
//! ```
//!
//! # Two rules that matter more here than on a thread
//!
//! **Never hold the lock across a wait.** An executor is cooperative: a task
//! holding the mutex across `Timer::after(..).await` blocks every other task for
//! that whole duration. Take it, do the operation, drop it.
//!
//! **Put `sync()` in one place.** It is two page writes normally, but the one
//! that seals a sector also erases — 100 ms or more on real NOR, during which
//! nothing else touches the log. Scheduling it from a single task makes that
//! latency predictable instead of arriving whenever a sampler happens to fill a
//! page.
//!
//! `CriticalSectionRawMutex` is the right raw mutex when the tasks may run on
//! different cores. Within one executor, `NoopRawMutex` is cheaper.

use core::future::Future;
use core::pin::pin;
use core::task::{Context, Waker};

use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::mutex::Mutex;

use sensor_db::mock::{AsyncFlash, MockFlash};
use sensor_db::{Error, SensorData, SensorDbAsync};
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 Flash = AsyncFlash<MockFlash<PAGE, SECTOR>>;
type Db = SensorDbAsync<Flash, PAGE, SECTORS>;
type SharedDb = Mutex<CriticalSectionRawMutex, Db>;

const SAMPLES: u64 = 400;

/// A cooperative round-robin over two tasks — the smallest thing that is
/// honestly an executor.
///
/// Polls each until both finish. `sensor_db::mock::block_on` deliberately
/// panics on `Poll::Pending`, because in the single-task tests a pending future
/// means the mock did something wrong; here contention on the mutex makes
/// `Pending` the normal case, which is the whole point of the example.
fn run_both(a: impl Future<Output = ()>, b: impl Future<Output = ()>) {
    let waker = Waker::noop();
    let mut cx = Context::from_waker(waker);
    let (mut a, mut b) = (pin!(a), pin!(b));
    let (mut a_done, mut b_done) = (false, false);

    while !(a_done && b_done) {
        if !a_done {
            a_done = a.as_mut().poll(&mut cx).is_ready();
        }
        if !b_done {
            b_done = b.as_mut().poll(&mut cx).is_ready();
        }
    }
}

/// Samples a sensor and appends. Holds the lock for exactly one append.
async fn sampler(db: &SharedDb, first: u64, count: u64) {
    for i in 0..count {
        let ts = first + i;
        let mut db = db.lock().await;
        db.append_sensor(
            ts,
            &Temperature {
                celsius_x100: 2_000 + ts as i32,
            },
        )
        .await
        .expect("append");
    }
}

/// Watches the log while it fills, then makes it durable once at the end.
///
/// On a device this is the task that owns `sync()`, so the erase latency lands
/// somewhere known rather than inside whichever sampler filled the page.
async fn monitor(db: &SharedDb, polls: u32) -> u32 {
    let mut highest = 0;
    for _ in 0..polls {
        let mut db = db.lock().await;

        // Reads see the RAM page buffer as well as flash, so this observes
        // appends that are not yet durable. `sync()` is for durability alone.
        let count = db.count_sensor::<Temperature>().await.expect("count");
        assert!(
            count >= highest,
            "an append-only log never counts backwards"
        );
        highest = count;

        if let Some((header, value)) = db.latest_sensor::<Temperature>().await.expect("latest") {
            assert_eq!(
                value.celsius_x100,
                2_000 + header.timestamp as i32,
                "a read must return a reading someone actually wrote"
            );
        }
    }
    highest
}

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

    let flash = AsyncFlash::wrap(MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR));
    let mut db: Db = SensorDbAsync::new(flash, 0, SECTORS as u16, 2)?;
    sensor_db::mock::block_on(db.format())?;

    let shared: SharedDb = Mutex::new(db);
    let mut observed = 0;

    // Two tasks, one executor, contending for the log at every append.
    run_both(sampler(&shared, 0, SAMPLES), async {
        observed = monitor(&shared, 150).await;
    });

    let mut db = shared.into_inner();
    sensor_db::mock::block_on(db.sync())?;

    println!("  sampler appended            {SAMPLES}");
    println!("  monitor observed up to      {observed} while it ran");
    println!(
        "  stored after sync           {}",
        sensor_db::mock::block_on(db.count_sensor::<Temperature>())?
    );

    assert_eq!(
        sensor_db::mock::block_on(db.count_sensor::<Temperature>())?,
        SAMPLES as u32,
        "every append must be present"
    );

    // Every timestamp exactly once — no duplicates from the interleaving, no
    // gaps from a lock released at the wrong moment.
    let mut seen = vec![false; SAMPLES as usize];
    sensor_db::mock::block_on(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(())
}