Trait Wal 

pub trait Wal:
    Debug
    + Send
    + Sync {
    // Required methods
    fn begin_read_tx(&self) -> Result<bool>;
    fn mvcc_refresh_if_db_changed(&self) -> bool;
    fn begin_write_tx(&self, allowed_auto_actions: WalAutoActions) -> Result<()>;
    fn end_read_tx(&self);
    fn end_write_tx(&self);
    fn holds_read_lock(&self) -> bool;
    fn holds_write_lock(&self) -> bool;
    fn should_checkpoint_on_close(&self) -> bool;
    fn find_frame(
        &self,
        page_id: u64,
        frame_watermark: Option<u64>,
    ) -> Result<Option<u64>>;
    fn read_frame(
        &self,
        frame_id: u64,
        page: PageRef,
        buffer_pool: Arc<BufferPool>,
    ) -> Result<Completion>;
    fn read_frames_batch(
        &self,
        start_frame: u64,
        pages: &[PageRef],
        buffer_pool: Arc<BufferPool>,
        scratch_buf: Option<Arc<Buffer>>,
    ) -> Result<Completion>;
    fn read_frame_raw(
        &self,
        frame_id: u64,
        frame: &mut [u8],
    ) -> Result<Completion>;
    fn write_frame_raw(
        &self,
        buffer_pool: Arc<BufferPool>,
        frame_id: u64,
        page_id: u64,
        db_size: u64,
        page: &[u8],
        sync_type: FileSyncType,
    ) -> Result<()>;
    fn prepare_wal_start(&self, page_sz: PageSize) -> Result<Option<Completion>>;
    fn prepare_wal_finish(&self, sync_type: FileSyncType) -> Result<Completion>;
    fn prepare_frames(
        &self,
        pages: &[PageRef],
        page_sz: PageSize,
        db_size_on_commit: Option<u32>,
        prev: Option<&PreparedFrames>,
    ) -> Result<PreparedFrames>;
    fn commit_prepared_frames(&self, prepared: &[PreparedFrames]);
    fn finalize_committed_pages(&self, prepared: &[PreparedFrames]);
    fn wal_file(&self) -> Result<Arc<dyn File>>;
    fn append_frames_vectored(
        &self,
        pages: Vec<PageRef>,
        page_sz: PageSize,
    ) -> Result<Completion>;
    fn finish_append_frames_commit(&self) -> Result<()>;
    fn should_checkpoint(&self) -> bool;
    fn checkpoint(
        &self,
        pager: &Pager,
        mode: CheckpointMode,
    ) -> Result<IOResult<CheckpointResult>>;
    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;
    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);
    fn min_pinned_read_frame(&self) -> Option<u64>;
    fn get_min_frame(&self) -> u64;
    fn backfill_frame(&self) -> u64;
    fn rollback(&self, rollback_to: Option<RollbackTo>);
    fn abort_checkpoint(&self);
    fn get_last_checksum(&self) -> (u32, u32);
    fn changed_pages_after(&self, frame_watermark: u64) -> Result<Vec<u32>>;
    fn set_io_context(&self, ctx: IOContext);
    fn update_max_frame(&self);
    fn truncate_wal(
        &self,
        result: &mut CheckpointResult,
        sync_type: FileSyncType,
    ) -> Result<IOResult<()>>;
    fn try_begin_vacuum_checkpoint_lock(&self) -> Result<()>;
    fn release_vacuum_checkpoint_lock(&self);
    fn begin_vacuum_blocking_tx(&self) -> Result<()>;
    fn vacuum_checkpoint_with_held_lock(
        &self,
        pager: &Pager,
    ) -> Result<IOResult<CheckpointResult>>;
    fn release_vacuum_lock(&self);
    fn as_any(&self) -> &dyn Any;
}

Write-ahead log (WAL).

Required Methods

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 begin_write_tx(&self, allowed_auto_actions: WalAutoActions) -> Result<()>

Begin a write transaction.

allowed_auto_actions controls which automatic WAL maintenance actions are permitted within this call — currently only WalAutoActions::Restart is consulted (it gates try_restart_log_before_write). Callers that own WAL state externally (e.g. the sync engine) pass an empty set to opt out.

fn end_read_tx(&self)

End a read 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 should_checkpoint_on_close(&self) -> bool

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

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

Find the latest frame containing a page.

optional frame_watermark parameter can be passed to force WAL to find frame not larger than watermark value caller must guarantee, that frame_watermark must be greater than last checkpointed frame, otherwise method will panic

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

Read a frame from the WAL.

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.

If scratch_buf is Some, it is used as the pread destination (must have length exactly (page_size + WAL_FRAME_HEADER_SIZE) * pages.len()). Otherwise a fresh temporary buffer is allocated. VACUUM passes a pre-allocated buffer to amortize the ~batch-size allocation across batches.

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 prepare_wal_start(&self, page_sz: 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 prepare_frames( &self, pages: &[PageRef], page_sz: PageSize, db_size_on_commit: Option<u32>, prev: Option<&PreparedFrames>, ) -> Result<PreparedFrames>

Prepare a batch of WAL frames for durable commit/append to the log.

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

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

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

Mark in-memory pages clean and set WAL tags after durable commit.

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

Return a handle to the underlying File.

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

Write a bunch of frames to the WAL. db_size is the database size in pages after the transaction finishes. db_size is set -> last frame written in transaction db_size is none -> non-last frame written in transaction

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

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

fn should_checkpoint(&self) -> bool

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

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 rollback(&self, rollback_to: Option<RollbackTo>)

fn abort_checkpoint(&self)

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

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 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).

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.

VACUUM: take vacuum_lock exclusively, take the WAL write lock, and install the source snapshot that VACUUM will copy from.

This does not acquire a physical read-mark lock. The exclusive snapshot is protected by vacuum_lock: normal readers hold that lock shared for their read transaction, so once the exclusive lock is acquired no new normal reader or writer can enter.

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 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 as_any(&self) -> &dyn Any

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Wal for WalFile