Struct Wal 

pub struct Wal { /* private fields */ }

Write-Ahead Log with per-key segment sets.

The Wal struct provides the main interface for WAL operations, managing segment files and ensuring durability guarantees.

Implementations

impl Wal

pub fn new(filepath: &str, options: WalOptions) -> Result<Self>

Creates a new WAL instance.

Arguments

• filepath - Directory path for WAL files
• options - Configuration options

Errors

Returns WalError::InvalidConfig if options are invalid. Returns WalError::Io if directory creation fails.

Examples

use nano_wal::{Wal, WalOptions};

let wal = Wal::new("./my_wal", WalOptions::default())?;

pub fn append_entry<K: Hash + AsRef<[u8]> + Display>( &mut self, key: K, header: Option<Bytes>, content: Bytes, durable: bool, ) -> Result<EntryRef>

Appends an entry to the WAL.

Arguments

• key - Entry key for segment selection
• header - Optional metadata header (max 64KB)
• content - Entry content
• durable - If true, syncs to disk before returning

Errors

Returns WalError::HeaderTooLarge if header exceeds 64KB. Returns WalError::Io for I/O failures.

Examples

let entry_ref = wal.append_entry(
    "user_123",
    Some(Bytes::from("metadata")),
    Bytes::from("data"),
    true
)?;

pub fn append_batch<K, I>( &mut self, entries: I, durable: bool, ) -> Result<Vec<EntryRef>>

where K: Hash + AsRef<[u8]> + Display, I: IntoIterator<Item = (K, Option<Bytes>, Bytes)>,

Appends multiple entries in a batch.

Batch operations provide better throughput by reducing I/O overhead.

Arguments

• entries - Iterator of (key, header, content) tuples
• durable - If true, syncs after all entries are written

Errors

Returns first error encountered; partial writes may occur.

Examples

let entries = vec![
    ("key1", None, Bytes::from("data1")),
    ("key2", Some(Bytes::from("meta")), Bytes::from("data2")),
];
let refs = wal.append_batch(entries, true)?;

pub fn log_entry<K: Hash + AsRef<[u8]> + Display>( &mut self, key: K, header: Option<Bytes>, content: Bytes, ) -> Result<EntryRef>

Logs an entry with durability guarantee.

Convenience method equivalent to append_entry(key, header, content, true).

Examples

wal.log_entry("key", None, Bytes::from("data"))?;

pub fn enumerate_keys(&self) -> Result<impl Iterator<Item = String>>

Enumerates all keys in the WAL.

Errors

Returns WalError::Io for filesystem errors.

Examples

for key in wal.enumerate_keys()? {
    println!("Found key: {}", key);
}

pub fn enumerate_records<K: Hash + AsRef<[u8]> + Display>( &self, key: K, ) -> Result<impl Iterator<Item = Bytes>>

Enumerates records for a specific key.

Arguments

• key - Key to enumerate records for

Errors

Returns WalError::Io for filesystem errors.

Examples

for record in wal.enumerate_records("my_key")? {
    println!("Record size: {}", record.len());
}

pub fn read_entry_at(&self, entry_ref: EntryRef) -> Result<Bytes>

Reads entry at specified location.

Arguments

• entry_ref - Reference to the entry location

Errors

Returns WalError::EntryNotFound if segment doesn’t exist. Returns WalError::CorruptedData if signature is invalid.

Examples

let data = wal.read_entry_at(entry_ref)?;

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

Removes expired segments from disk.

Errors

Returns WalError::Io for filesystem errors.

Examples

wal.compact()?;

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

Syncs all active segments to disk.

Errors

Returns WalError::Io if sync fails.

Examples

wal.sync()?;

pub fn active_segment_count(&self) -> usize

Returns count of active segments.

Examples

println!("Active segments: {}", wal.active_segment_count());

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

Shuts down WAL and removes all storage.

Errors

Returns WalError::Io if removal fails.

Examples

wal.shutdown()?;

Trait Implementations

impl Debug for Wal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.