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 GroupSync 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 commit_tx_lsn( &self, events: Vec<MutationEvent>, ) -> Result<Option<Lsn>, WalError>

Same as Self::commit_tx, but returns the LSN of the TxCommit record it wrote (None when events was empty and nothing was written). Change feeds use it as the transaction’s resume token.

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.

Under SyncMode::GroupSync, a normal flush writes bytes to the OS but leaves durable_lsn unchanged until an explicit force_fsync, checkpoint, sync, the background flusher, or clean drop.

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.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.