Struct WalWriter 

pub struct WalWriter { /* private fields */ }

Write-Ahead Log writer.

Appends records to WAL files, manages rotation, and enforces the configured fsync policy. Thread-safe: internal state is protected by a mutex.

Group commit

When using FsyncPolicy::PerBatch, the append_durable method enables group commit: concurrent callers write their records under the write lock, then coordinate so that a single fsync covers all pending writes. The first waiter becomes the sync leader and performs the flush; subsequent waiters piggy-back on the leader’s sync.

Implementations

impl WalWriter

pub fn open( dir: impl Into<PathBuf>, config: WalConfig, ) -> Result<Self, WalError>

Open or create a WAL writer in the given directory.

If existing WAL files are present, the writer resumes from the last sequence number. Otherwise, a new WAL file is created starting at sequence 1.

Errors

Returns WalError if the directory cannot be created or files cannot be opened.

pub fn is_poisoned(&self) -> bool

Returns true if the WAL writer has been poisoned due to an unrecoverable I/O error.

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

Clear the poison flag after operator-verified recovery.

Re-opens the current WAL file for appending to ensure the underlying file descriptor is in a known-good state. Returns an error if the WAL file cannot be reopened.

Safety (logical)

Call this only after verifying the WAL directory is intact (e.g. via WalReader replay). Clearing poison on a genuinely corrupt WAL risks silent data loss.

pub fn append(&self, payload: &[u8]) -> Result<u64, WalError>

Append a single payload to the WAL.

Returns the assigned sequence number.

Errors

Returns WalError on I/O failure, if the WAL is full, or if the internal lock was poisoned.

pub fn append_batch(&self, payloads: &[&[u8]]) -> Result<u64, WalError>

Append a batch of payloads as a single atomic WAL record, followed by a single fsync (when using PerBatch policy).

All payloads are serialized into a batch-framed compound record whose CRC covers the entire batch. On crash recovery, either all sub-payloads survive (CRC valid) or none (CRC mismatch / truncation), guaranteeing all-or-nothing batch atomicity.

Uses the same group-commit pattern as append_durable: the write lock is released before fsync, allowing concurrent writers to proceed while the sync leader fsyncs for all pending records.

Returns the sequence number of the batch record.

Errors

Returns WalError on I/O failure or if the internal lock was poisoned.

pub fn append_durable(&self, payload: &[u8]) -> Result<u64, WalError>

Append a single payload and ensure it is durably committed.

With FsyncPolicy::PerBatch this participates in group commit: the calling thread writes its record and then either becomes the sync leader (flushing and calling fsync for all pending records) or waits for an in-progress sync to complete. This amortises the cost of fsync across concurrent callers.

With FsyncPolicy::PerWrite this behaves identically to append.

With FsyncPolicy::Periodic the record is written and then unconditionally flushed + synced, because “durable” means the caller requires the data to be on stable storage before returning .

Errors

Returns WalError on I/O failure, if the WAL is full, or if the internal lock was poisoned.

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

Flush the WAL buffer and sync to disk.

Errors

Returns WalError on I/O failure or if the internal lock was poisoned.

pub fn fsync_count(&self) -> u64

Number of fsync calls issued against the WAL data file.

The observable form of the fsync policy: with FsyncPolicy::Periodic this grows with elapsed time, not with the number of appends.

pub fn start_periodic_sync(self: &Arc<Self>)

Start the background periodic sync thread.

When the WAL is configured with FsyncPolicy::Periodic(interval), this spawns a dedicated thread that calls flush + fsync at the configured interval. The thread runs until shutdown_periodic_sync is called or the WalWriter is dropped.

No-op if the policy is not Periodic.

pub fn shutdown_periodic_sync(&self)

Stop the periodic sync thread and wait for it to finish.

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

Force rotation to a new WAL file.

Errors

Returns WalError on I/O failure or if the internal lock was poisoned.

pub fn truncate_before(&self, sequence_no: u64) -> Result<usize, WalError>

Delete WAL files whose maximum sequence number is ≤ the threshold.

Never deletes the active WAL file. Idempotent.

Errors

Returns WalError on I/O failure or if the internal lock was poisoned.

pub fn memory_bytes(&self) -> usize

Approximate heap bytes held by the writer’s own buffers.

The BufWriter’s capacity, which is what stands between an append and an fsync. It is one of the three terms the memtable budget does not count, and unlike the other two it is fixed rather than a function of the workload — so it is worth having as a number precisely because it is easy to forget.

pub fn current_sequence(&self) -> u64

Returns the current sequence number (the last assigned).

pub fn dir(&self) -> &Path

Returns the path to the WAL directory.

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

Returns the number of WAL files in the directory.

Errors

Returns WalError if the directory cannot be read.

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

Returns the total size in bytes of all WAL files on disk.

Errors

Returns WalError if the directory cannot be read.

pub fn emit_metrics(&self)

Emit WAL gauge metrics for monitoring lag and resource usage.

Emits chronix_wal_file_count, chronix_wal_total_bytes, and chronix_wal_sequence_number gauges.

pub fn close(self) -> Result<(), WalError>

Explicitly close the WAL writer, flushing all data to stable storage.

Unlike the implicit Drop cleanup, this method returns I/O errors so close failures are not silently ignored.

The shutdown sequence is:

1. Stop the periodic sync thread (if running).
2. Flush all buffered data to the operating system.
3. Issue sync_all to commit data and metadata to stable storage.

Close-path efficiency

This method takes ownership of self (mut self), which guarantees exclusive access. The inner state is obtained via Mutex::get_mut (no-lock fast path), so flush and fsync execute outside any lock scope. This prevents mutex contention with concurrent readers or writers during shutdown.

Errors

Returns WalError if the flush or fsync fails.

Trait Implementations

impl Drop for WalWriter

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.