Struct WalFile 

pub struct WalFile { /* private fields */ }

Implementations

impl WalFile

pub fn new( io: Arc<dyn IO>, shared: Arc<RwLock<WalFileShared>>, (last_checksum, max_frame): ((u32, u32), u64), buffer_pool: Arc<BufferPool>, ) -> Self

pub fn try_restart_log_before_write(&self) -> Result<()>

attempt to restart WAL header before write in order to keep WAL file size under the control The conditions for WAL restart are following:

1. we can do that only under write transaction
2. max_frame_read_lock_index == 0 - this means that transaction was initiated to read data from DB file
3. nbackfills > 0 - otherwise nothing was backfilled and there is no reason to truncate header
4. max_frame == nbackfills - otherwise there are some non-checkpointed frames in the WAL and we can’t truncate the log

pub fn mvcc_refresh_if_db_changed(&self) -> bool

MVCC helper: check if WAL state changed and refresh local snapshot without starting a read tx. FIXME: this isn’t TOCTOU safe because we’re not taking WAL read locks.

This is only used to invalidate page cache, so false positives are sort of acceptable since MVCC reads currently don’t read from WAL frames ever. FIXME: MVCC should start using pager read transactions anyway so that we can get rid of the stop-the-world MVCC checkpoint that blocks all reads.

Trait Implementations

impl Debug for WalFile

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

Formats the value using the given formatter.

impl Wal for WalFile

fn end_read_tx(&self)

End a read transaction.

fn begin_write_tx(&self, allowed_auto_actions: WalAutoActions) -> Result<()>

Begin a write transaction

fn end_write_tx(&self)

End a write transaction

fn holds_read_lock(&self) -> bool

Returns true if this WAL instance currently holds a read lock.

fn holds_write_lock(&self) -> bool

Returns true if this WAL instance currently holds the write lock.

fn find_frame( &self, page_id: u64, frame_watermark: Option<u64>, ) -> Result<Option<u64>>

Find the latest frame containing a page.

fn read_frame( &self, frame_id: u64, page: PageRef, buffer_pool: Arc<BufferPool>, ) -> Result<Completion>

Read a frame from the WAL.

fn prepare_frames( &self, pages: &[PageRef], page_sz: PageSize, db_size_on_commit: Option<u32>, prev: Option<&PreparedFrames>, ) -> Result<PreparedFrames>

Prepares a batch of dirty pages as WAL frames without modifying WAL state.

This is the first phase of a three-phase commit protocol:

1. prepare (prepare_frames) - serialize frames, compute checksums
2. write + fsync - caller submits I/O and waits for durability
3. commit/finalize (commit_prepared_frames) - update WAL index and page metadata

WAL frames form a checksum chain for corruption detection. When writing multiple batches in a single transaction, pass the previous batch via prev to continue the chain. For the first batch, pass None to start from the committed WAL state.

fn commit_prepared_frames(&self, batches: &[PreparedFrames])

For each prepared frame, update in-memory WAL index and rolling checksum. and advance max_frame to make frames visible to readers.

fn finalize_committed_pages(&self, prepared: &[PreparedFrames])

Mark pages clean and set WAL tags after durable commit.

fn wal_file(&self) -> Result<Arc<dyn File>>

Get WAL file for durable writes.

fn append_frames_vectored( &self, pages: Vec<PageRef>, page_sz: PageSize, ) -> Result<Completion>

Use pwritev to append many frames to the log at once.

Safety:

this method should only be used for cacheflush/spilling, the commit path should use prepare_frames + commit_prepared_frames instead, as it prevents prematurely modifing WAL state before durability is ensured.

fn begin_read_tx(&self) -> Result<bool>

Begin a read transaction. Returns whether the database state has changed since the last read transaction.

fn mvcc_refresh_if_db_changed(&self) -> bool

MVCC helper: check if WAL state changed without starting a read tx.

fn should_checkpoint_on_close(&self) -> bool

Whether shutdown checkpointing is valid when this process closes its last connection.

fn read_frames_batch( &self, start_frame: u64, pages: &[PageRef], buffer_pool: Arc<BufferPool>, scratch_buf: Option<Arc<Buffer>>, ) -> Result<Completion>

Read a contiguous run of WAL frames with a single pread. For each i, pages[i] receives the decoded page body of frame start_frame + i. This method is a batched version of read_frame.

fn read_frame_raw(&self, frame_id: u64, frame: &mut [u8]) -> Result<Completion>

Read a raw frame (header included) from the WAL.

fn write_frame_raw( &self, buffer_pool: Arc<BufferPool>, frame_id: u64, page_id: u64, db_size: u64, page: &[u8], sync_type: FileSyncType, ) -> Result<()>

Write a raw frame (header included) from the WAL. Note, that turso-db will use page_no and size_after fields from the header, but will overwrite checksum with proper value

fn should_checkpoint(&self) -> bool

fn checkpoint( &self, pager: &Pager, mode: CheckpointMode, ) -> Result<IOResult<CheckpointResult>>

fn vacuum_checkpoint_with_held_lock( &self, pager: &Pager, ) -> Result<IOResult<CheckpointResult>>

Checkpoint using a checkpoint lock already held by the caller. The method consumes that raw checkpoint-lock ownership: on success the guard is held by the checkpoint state machine, and on early failure it is released before returning.

fn install_durable_backfill_proof( &self, max_frame: u64, db_size_pages: u32, db_header_crc32c: u32, sync_type: FileSyncType, ) -> Result<Option<Completion>>

fn publish_backfill(&self, max_frame: u64)

fn sync(&self, sync_type: FileSyncType) -> Result<Completion>

fn is_syncing(&self) -> bool

fn is_dirty(&self) -> bool

Whether the WAL file is dirty: frames were appended that no successful WAL fsync has covered yet. A dirty WAL owes an fsync before a commit may be reported durable, even when the committer itself has no dirty pages to write (e.g. frames inserted through Wal::write_frame_raw).

fn get_max_frame_in_wal(&self) -> u64

fn get_checkpoint_seq(&self) -> u32

fn get_max_frame(&self) -> u64

fn connection_wal_pos(&self) -> (u32, u64)

This connection’s frozen (checkpoint_seq, max_frame): for a reader it is the WAL read mark installed at begin_read_tx; for a writer it is the position after its last commit. Used by MVCC to gate btree reads on physical reachability (a materialization at WAL position P is reachable iff P <= this, lexicographically). See RootEntry.

fn min_pinned_read_frame(&self) -> Option<u64>

The lowest WAL frame any active reader is currently pinned at (across the read-mark slots), or None if no reader holds a slot. This is the authoritative set of pinned readers — it includes a reader that has called begin_read_tx but not yet published an MVCC transaction — so the MVCC checkpoint uses it as the version-store GC floor (a row whose btree page was materialized past a pinned reader’s frame is invisible in that reader’s snapshot, so its version-store copy must be retained).

fn get_min_frame(&self) -> u64

fn backfill_frame(&self) -> u64

The shared backfill boundary: WAL frames at or below this are durably copied into the DB file, so a version materialized there is reachable by EVERY snapshot (including a db-file reader pinned at the boundary). Used as the passive-checkpoint version-store GC floor.

fn get_last_checksum(&self) -> (u32, u32)

fn rollback(&self, rollback_to: Option<RollbackTo>)

fn abort_checkpoint(&self)

fn try_begin_vacuum_checkpoint_lock(&self) -> Result<()>

Try to acquire the checkpoint serialization lock. Returns Busy if another checkpointer or VACUUM already holds it. Used by plain VACUUM to fail fast if a concurrent checkpoint would block later.

fn release_vacuum_checkpoint_lock(&self)

Release the checkpoint serialization lock acquired by try_begin_vacuum_checkpoint_lock.

fn begin_vacuum_blocking_tx(&self) -> Result<()>

Acquire exclusive WAL access. This will block all new readers and writers. Also, this routine succeeds only if no other transactions are active. This is used by VACUUM routine.

fn release_vacuum_lock(&self)

Release the exclusive VACUUM lock acquired by begin_vacuum_blocking_tx. VACUUM calls this once done, after which new readers and writers may proceed again.

fn finish_append_frames_commit(&self) -> Result<()>

Complete append of frames by updating shared wal state. Before this all changes were stored locally.

fn changed_pages_after(&self, frame_watermark: u64) -> Result<Vec<u32>>

Return unique set of pages changed after frame_watermark position and until current WAL session max_frame_no

fn prepare_wal_start(&self, page_size: PageSize) -> Result<Option<Completion>>

Prepare WAL header for the future append Most of the time this method will return Ok(None)

fn prepare_wal_finish(&self, sync_type: FileSyncType) -> Result<Completion>

fn as_any(&self) -> &dyn Any

fn set_io_context(&self, ctx: IOContext)

fn update_max_frame(&self)

Update the max frame to the current shared max frame. Currently this is only used for MVCC as it takes care of write conflicts on its own. This should’t be used with regular WAL mode.

fn truncate_wal( &self, result: &mut CheckpointResult, sync_type: FileSyncType, ) -> Result<IOResult<()>>

Truncate WAL file to zero and sync it. This is called AFTER the DB file has been synced during TRUNCATE checkpoint mode, ensuring data durability. The result parameter is used to track I/O progress (wal_truncate_sent, wal_sync_sent).