Struct Wal 

pub struct Wal { /* private fields */ }

The main write-ahead log.

Create instances exclusively via Wal::open. All methods are safe for concurrent use from multiple threads.

A WAL progresses through four lifecycle states: Init → Running → Draining → Closed. Once closed, a WAL instance cannot be reopened. To continue using the same file, call Wal::open again.

Implementations

impl Wal

pub fn open(path: impl AsRef<Path>) -> WalBuilder

Starts building a WAL at the given path.

Returns a WalBuilder to configure options before opening. Call build() to finalize.

let wal = Wal::open("/tmp/my.wal").build()?;

pub fn append(&self, payload: impl Into<Vec<u8>>) -> Result<Lsn>

Writes a single event. Returns the assigned LSN.

pub fn append_with_meta( &self, payload: impl Into<Vec<u8>>, meta: impl Into<Vec<u8>>, ) -> Result<Lsn>

Writes a single event with metadata. Returns the assigned LSN.

pub fn append_batch(&self, batch: Batch) -> Result<Lsn>

Writes a batch of events atomically. Returns the last assigned LSN.

Takes Batch by value to avoid cloning payloads (move semantics). Build a new Batch for each call, or .clone() explicitly if reuse is needed.

pub fn flush(&self) -> Result<()>

Blocks until the writer has processed all queued batches.

Does NOT call fsync. For full durability: flush() then sync().

pub fn sync(&self) -> Result<()>

Calls fsync on the underlying storage, making written data durable.

pub fn replay( &self, from: Lsn, f: impl FnMut(Event) -> Result<()>, ) -> Result<()>

Reads all events with LSN >= from, calling f for each.

Uses mmap for zero-copy access. The Event passed to f has payload and meta that are owned copies; they are safe to keep.

pub fn iterator(&self, from: Lsn) -> Result<WalIterator>

Returns a pull-based iterator starting from the given LSN.

pub fn last_lsn(&self) -> Lsn

Most recently persisted LSN. May lag behind append return values.

pub fn stats(&self) -> Stats

Point-in-time snapshot of WAL statistics.

pub fn shutdown(&self, timeout: Duration) -> Result<()>

Graceful shutdown: drains queue, flushes, syncs, closes storage.

Transitions to Draining (new appends rejected), then to Closed. Respects the timeout — returns Error::Io on timeout. Idempotent: calling on a closed WAL returns Ok(()).

pub fn close(&self) -> Result<()>

Immediate close without draining the write queue.

Pending batches are discarded. For graceful shutdown, use shutdown. Idempotent.

Trait Implementations

impl Drop for Wal

fn drop(&mut self)

Executes the destructor for this type.