Module wal 

Write-ahead log implementation - WAL for durability and exactly-once semantics Write-Ahead Log for durability and exactly-once semantics.

The WAL provides durability by persisting all state mutations before they are applied. This enables recovery after crashes and supports exactly-once processing semantics.

Record Format

Each WAL record is stored as:

+----------+----------+------------------+
| Length   | CRC32C   | Entry Data       |
| (4 bytes)| (4 bytes)| (Length bytes)   |
+----------+----------+------------------+

• Length: 4-byte little-endian u32, size of Entry Data
• CRC32C: 4-byte little-endian u32, CRC32C checksum of Entry Data
• Entry Data: rkyv-serialized WalEntry

Durability

Uses fdatasync (via sync_data()) instead of fsync for better performance. This syncs file data without updating metadata (atime, mtime), saving 50-100μs per sync.

Torn Write Detection

On recovery, the WAL reader detects partial writes:

• Incomplete length prefix (< 4 bytes at EOF)
• Incomplete CRC field (< 4 bytes after length)
• Incomplete data (< length bytes after CRC)
• CRC32 mismatch (data corruption)

Use repair() to truncate the WAL to the last valid record.

Structs

ArchivedWalPosition

An archived WalPosition

WalPosition

WAL position for checkpointing.

WalPositionResolver

The resolver for an archived WalPosition

WalReader

WAL reader for recovery replay.

WriteAheadLog

Write-Ahead Log implementation.

Enums

WalEntry

WAL entry types representing different operations.

WalError

Error type for WAL operations.

WalReadResult

Result of reading a WAL record.