wal_store.h File Reference

Durable write-ahead store: A/B superblock + checkpoint over a block-device seam (DETWS_ENABLE_WAL). More...

#include "ServerConfig.h"
#include "services/wal/wal.h"
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Detailed Description

Durable write-ahead store: A/B superblock + checkpoint over a block-device seam (DETWS_ENABLE_WAL).

Increment 2 on top of the pure record codec in wal.h. It turns the codec into a mountable, power-loss-safe append log on a fixed backing region (a preallocated file on any fs::FS - SD card or LittleFS - or any RAM buffer for host tests). All I/O goes through a ::WalDev of three function pointers, so the superblock and checkpoint logic is pure and fully host-testable over a RAM device.

On-media layout of the backing region:

[ superblock A : WAL_SUPER_SIZE ][ superblock B : WAL_SUPER_SIZE ][ WAL data region ... ]

Records (wal.h framing) are appended sequentially into the data region and are not synced per op - that matches the measured envelope (docs/FEATURE_PERFORMANCE.md): batch, then checkpoint in bulk.

Checkpoint = the atomic commit. ::wal_store_checkpoint syncs the appended data, then writes an updated superblock (with an incremented generation, the new durable head, and the next seq) to the inactive of the two copies and syncs that. Flipping which copy is newest is the single durable pointer move. If a crash tears the new superblock, its CRC fails and mount falls back to the older copy; either way mount then replays the tail past the committed head - each record is self-validating (CRC), so records appended after the last checkpoint are still recovered, and recovery stops at the first torn record.

So durability is layered: the superblock bounds how far mount must scan, and the per-record CRC provides the actual atomicity. A crash costs at most the last, un-appended (torn) record.

Definition in file wal_store.h.