Struct WalHandle 

pub struct WalHandle { /* private fields */ }

Control plane for a running WAL engine.

This handle is intentionally single-owner and not cloneable. Calling enqueue_append through &mut self gives the database one linear admission point for its caller-assigned sequence numbers, while returned AppendCompletion values remain independently awaitable by the database’s apply pipeline.

Implementations

impl WalHandle

pub async fn enqueue_append( &mut self, seqno: WalSeqNo, record: Bytes, ) -> Result<AppendCompletion, Error>

Admit one caller-numbered opaque record without waiting for durability.

Before waiting, this method verifies that seqno is exactly the next contiguous sequence number and that the record fits the configured limits. If the manifest has no slot recovery could use to seal this active object, admission returns Error::SegmentDirectoryFull. If the active object is at its hard ceiling, admission returns Error::ActiveSegmentFull. Neither condition consumes seqno; truncation may free directory capacity, after which the same append can be retried. Otherwise this waits for encoded-byte admission capacity and a bounded queue slot. On success the WAL owns the record and the returned AppendCompletion may be moved to another task. Await that completion before applying the transaction to the database.

The payload should be the database’s complete encoded transaction batch. The WAL treats it as opaque bytes and never merges it with another call. Dropping the completion does not cancel admitted work. On an eventual completion error, use Error::may_have_committed before deciding whether recovery must resolve the sequence number.

pub async fn truncate_before( &self, floor: WalSeqNo, ) -> Result<TruncationReport, Error>

Advance the application checkpoint floor and delete eligible sealed segments.

floor is the first record the database still needs. Call this only after the database has durably checkpointed every record before that boundary. The WAL deletes only whole sealed segments; it never truncates the active segment or deletes a segment containing floor.

Deletion is best effort across zones. The returned report contains only deletion statistics; the database remains the authority for the durable checkpoint it supplied. Startup and periodic maintenance retry tombstones whose zones were unavailable during this call. A successful truncation also makes the engine re-read directory capacity, so an active segment held at Error::ActiveSegmentFull can rotate and resume admission once enough entries are removed.

pub async fn abort(self)

Consume the admission handle, abort every owned task, and await their termination.

Accepted completions may resolve as closed or ambiguous. Use shutdown when accepted work must drain gracefully.

pub async fn shutdown(self) -> Result<(), Error>

Consume the admission handle, drain accepted work, finish every committed seal, and wait for all owned tasks to exit.