Struct Wal 

pub struct Wal { /* private fields */ }

Live, append-side WAL handle.

Construct via Wal::open. The returned tuple includes the list of committed mutation events that need to be re-applied to the in-memory store before any new traffic is accepted.

Wal::open returns Arc<Self> because the optional Group-mode background flusher needs a Weak<Wal> to call back into without taking a strong reference (which would prevent shutdown).

Implementations

impl Wal

pub fn open( dir: impl Into<PathBuf>, sync_mode: SyncMode, segment_target_bytes: u64, checkpoint_lsn: Lsn, ) -> Result<(Arc<Self>, Vec<MutationEvent>), WalError>

Open or create the WAL directory at dir.

checkpoint_lsn is the LSN stamped into the most recent snapshot the caller is restoring from (or Lsn::ZERO if there is no snapshot). Replay skips records at or below this fence — they are already represented in the loaded state.

Returns (wal, committed_events). The caller is expected to apply every event in committed_events to its in-memory store in order before issuing any new begin / append calls.

pub fn dir(&self) -> &Path

pub fn sync_mode(&self) -> SyncMode

pub fn durable_lsn(&self) -> Lsn

pub fn bg_failure(&self) -> Option<String>

Latched durability failure, if any. None means the WAL is healthy. Once set, every commit / flush / force_fsync starts returning WalError::Poisoned and the WAL stops accepting new transactions until the operator restarts from the last consistent snapshot + WAL.

pub fn next_lsn(&self) -> Lsn

LSN that the next begin / append call will allocate. Exposed for tests and for sanity checks at boot; not part of any durability contract.

pub fn oldest_segment_id(&self) -> u64

pub fn active_segment_id(&self) -> u64

pub fn begin(&self) -> Result<Lsn, WalError>

Allocate a TxBegin record and return its LSN. Test/admin primitive. Production commits use Self::commit_tx.

Rotation happens here so a transaction is always wholly within one segment.

pub fn append( &self, tx_begin_lsn: Lsn, event: &MutationEvent, ) -> Result<Lsn, WalError>

Append a single mutation to the active segment’s pending buffer. Test/admin primitive. Not durable until flush() runs; production commits use Self::commit_tx.

pub fn append_batch( &self, tx_begin_lsn: Lsn, events: Vec<MutationEvent>, ) -> Result<Lsn, WalError>

Append many mutations as one framed record. Test/admin primitive. Production commits use Self::commit_tx, which writes the begin/batch/commit triple in a single critical section.

pub fn commit(&self, tx_begin_lsn: Lsn) -> Result<Lsn, WalError>

Append a standalone TxCommit marker. Test/admin primitive. Production commits use Self::commit_tx.

pub fn abort(&self, tx_begin_lsn: Lsn) -> Result<Lsn, WalError>

Append a TxAbort marker. Test/admin primitive. Production code never writes TxAbort: Self::commit_tx writes the begin/batch/commit triple atomically, so an aborted query has nothing on disk to mark as aborted.

pub fn commit_tx( &self, events: Vec<MutationEvent>, ) -> Result<WroteCommit, WalError>

One-shot transaction commit.

Encodes TxBegin + MutationBatch + TxCommit as a single contiguous run inside one short critical section, then applies the configured flush policy. Compared to the legacy begin → append_batch → commit → flush sequence this collapses four separate state-lock acquisitions into one while preserving the release’s single-writer execution model. Future concurrent commit plumbing can build around this one-shot boundary without changing the recorder contract.

Returns WroteCommit::No for an empty event list (no records are written, no fsync is issued).

pub fn checkpoint_marker(&self, snapshot_lsn: Lsn) -> Result<Lsn, WalError>

Append a Checkpoint marker. snapshot_lsn should equal the LSN written into the snapshot file’s header — replay uses it to defend against the snapshot-rename-but-no-marker race.

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

Flush the active segment’s pending buffer.

What “flush” means depends on SyncMode:

• PerCommit — write the buffer to the OS, fsync, and advance durable_lsn. The strongest contract: every record up to next_lsn - 1 is on disk.
• Group — write the buffer to the OS, but leave durable_lsn unchanged until an explicit force_fsync, checkpoint, sync, or clean drop.
• None — write the buffer to the OS only, but advance durable_lsn anyway. The mode opts out of crash durability, so the checkpoint fence reports “what’s been written” instead of “what’s actually safe”.

pub fn force_fsync(&self) -> Result<(), WalError>

Unconditionally write the buffer to the OS, fsync, and advance durable_lsn. Used by callers that need a durability point right now regardless of the configured cadence (e.g. checkpoint). Returns WalError::Poisoned if the WAL has already latched a durability failure.

pub fn truncate_up_to(&self, fence_lsn: Lsn) -> Result<(), WalError>

Drop sealed segments whose entire LSN range is at or below fence_lsn. Idempotent and safe to call repeatedly.

The active segment is never deleted — even if every record in it predates the fence, it is still the rotation target for new appends. The segment immediately before the active one is also kept as a tombstone so a subsequent crash before the next checkpoint still finds a self-describing log start.

Trait Implementations

impl Drop for Wal

fn drop(&mut self)

Executes the destructor for this type.