Struct WriterTaskHandle

Source

pub struct WriterTaskHandle { /* private fields */ }

Expand description

Sender half of the write queue. Cheaply cloneable (wraps an mpsc::Sender) — every migrated store that shares one writer task holds a clone of this handle.

Implementations§

Source §

impl WriterTaskHandle

Source

pub async fn send<R, F>(&self, op: F) -> Result<R, StorageError>
where R: Send + 'static, F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,

Send a write operation to the writer task and await its typed reply.

Backpressure: this suspends on the channel’s send().await when the bounded queue is full (ADR-067 “Channel capacity and queue-full policy”) — there is no try_send escape hatch. Callers that need a deadline on that wait should use Self::send_with_timeout instead.

Source

pub async fn send_with_timeout<R, F>( &self, op: F, timeout: Duration, ) -> Result<R, StorageError>
where R: Send + 'static, F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,

Like Self::send, but bounds the wait for the bounded channel to free capacity with timeout.

The timeout applies ONLY to enqueueing the request (the channel send().await that can suspend on a full queue) — never to waiting for the writer task’s reply once the request has been accepted. StorageError::WriteQueueFull means exactly “the bounded channel was full and this request was never accepted”; it must never be returned for a request that was accepted and is still executing (or already committed) by the time timeout elapses — that would misreport a slow op or a lock wait as a queue-capacity failure, and could tell a caller a write failed when it actually landed. ADR-067’s queue-full policy has no immediate-error try_send path — only this caller-side deadline on the enqueue step.

Source

pub async fn send_top_level<R, F>(&self, op: F) -> Result<R, StorageError>
where R: Send + 'static, F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,

Send a write operation that MUST run outside any open transaction (e.g. VACUUM, which SQLite forbids inside BEGIN/COMMIT) and await its typed reply.

Still serialized through the same single writer owner as Self::send — the request goes through the identical bounded channel and drain loop, one request at a time — but the drain loop skips the per-request BEGIN IMMEDIATE/COMMIT/ROLLBACK wrap entirely for this request (ADR-067 Component A, Fork C slice 2 round 2, BLOCKER A). The single-writer guarantee is preserved; only the transaction wrap is skipped.

Source

pub fn queue_depth(&self) -> usize

Current write-queue backlog depth: requests enqueued but not yet accepted by the writer task’s drain loop.

Reads mpsc::Sender::max_capacity() - capacity(), so it is a point-in-time snapshot racy under concurrent senders/the drain loop draining concurrently — acceptable for a monitoring gauge (the load/perf harness metrics read-surface), never used for any correctness decision.

Source