Struct WriteAheadLog

Source

pub struct WriteAheadLog { /* private fields */ }

Expand description

Write-ahead log for crash recovery

Provides durable storage for mutations before they reach the memtable. Every mutation is serialized to an append-only log and fsync’d to disk.

§Usage

use cqlite_core::storage::write_engine::{WriteAheadLog, Mutation};
use std::path::Path;

// Create a new WAL
let mut wal = WriteAheadLog::create(Path::new("/data"))?;

// Append mutations (serialized with CRC32)
// let mutation = Mutation::new(...);
// wal.append(&mutation)?;

// Explicit sync to disk
wal.sync()?;

// On recovery, replay all valid entries
// let mutations = wal.replay()?;

Implementations§

Source §

impl WriteAheadLog

Source

pub const DEFAULT_BUFFER_SIZE: usize = 4096

Default buffer size (4 KB)

Source

pub const WAL_FILENAME: &'static str = "commitlog.wal"

WAL file name

Source

pub fn create(dir: &Path) -> Result<Self>

Create a new WAL in the specified directory

This creates a new WAL file with the default buffer size (4 KB). If a WAL already exists in the directory, it will be truncated.

§Arguments

dir - Directory where the WAL file will be created

§Returns

A new WriteAheadLog instance ready for appending.

§Errors

Returns an error if the directory doesn’t exist or the file cannot be created.

Source

pub fn create_with_buffer_size(dir: &Path, buffer_size: usize) -> Result<Self>

Create a new WAL with a custom buffer size

§Arguments

dir - Directory where the WAL file will be created
buffer_size - Size of the append buffer in bytes

Source

pub fn open_existing(path: &Path) -> Result<Self>

Open an existing WAL file for appending

This opens an existing WAL and seeks to the end, ready for new appends. Use this for recovery scenarios where you want to append to an existing log.

§Arguments

path - Path to the existing WAL file

§Returns

A WriteAheadLog positioned at the end of the file.

§Errors

Returns an error if the file doesn’t exist or cannot be opened.

Source

pub fn append(&mut self, mutation: &Mutation) -> Result<()>

Append a mutation to the WAL

This serializes the mutation using bincode and writes it to the buffer. The entry is not guaranteed to be on disk until sync() is called.

§Entry Format

[u32 LE: entry_length]
[u32 LE: crc32]
[bytes: serialized mutation]

§Arguments

mutation - The mutation to append

§Errors

Returns an error if serialization fails or the write fails.

Source

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

Sync the WAL to disk (fsync)

This flushes the buffer and calls fsync to ensure all data is written to persistent storage. This is required for durability guarantees.

§Errors

Returns an error if the flush or sync operation fails.

Source

pub fn replay(&self) -> Result<Vec<Mutation>>

Replay all valid entries from the WAL

Reads the WAL from the beginning and deserializes all valid entries. This is used during crash recovery to rebuild the memtable.

§Corruption Handling

Corrupted entries (CRC mismatch): Logged as warnings, skipped
Truncated entries (incomplete write): Stops replay, returns valid entries
Valid entries: Deserialized and returned in order

§Returns

A vector of all valid mutations read from the WAL.

§Errors

Returns an error if the WAL file cannot be opened or read.

Source

pub fn truncate(&mut self) -> Result<()>

Truncate the WAL (clear all entries)

This is used after a successful flush to memtable/SSTable, removing old entries that are no longer needed for recovery.

§Errors

Returns an error if the truncate operation fails.

Source

pub fn size(&self) -> u64

Get the current size of the WAL in bytes

Source

pub fn path(&self) -> &Path

Get the path to the WAL file

Source

pub fn rotate(self, dir: &Path) -> Result<Self>

Rotate the WAL (create a new one, keeping the old)

This creates a new WAL file with a timestamp suffix and returns a new WriteAheadLog instance. The old WAL file is left intact for archival or backup purposes.

The old file is renamed to: commitlog.wal.{timestamp}