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
impl WriterTaskHandle
Sourcepub async fn send<R, F>(&self, op: F) -> Result<R, StorageError>
pub async fn send<R, F>(&self, op: F) -> Result<R, StorageError>
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.
Sourcepub async fn send_with_timeout<R, F>(
&self,
op: F,
timeout: Duration,
) -> Result<R, StorageError>
pub async fn send_with_timeout<R, F>( &self, op: F, timeout: Duration, ) -> Result<R, StorageError>
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.
Sourcepub async fn send_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
pub async fn send_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
Like Self::send, but bounds the enqueue-capacity wait with this
handle’s configured enqueue_timeout
(PoolConfig::write_admission_deadline_ms at spawn time, ADR-131
Decision 2) instead of waiting indefinitely (#1382).
Once the request is accepted onto the channel, the reply wait is
unbounded by this method, identical to Self::send — this bounds
only queue-capacity admission, never SQLite execution or reply
latency. Callers that need a non-default deadline should use
Self::send_with_timeout directly.
Sourcepub async fn send_top_level<R, F>(&self, op: F) -> Result<R, StorageError>
pub async fn send_top_level<R, F>(&self, op: F) -> Result<R, StorageError>
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). The single-writer
guarantee is preserved; only
the transaction wrap is skipped.
Sourcepub async fn send_top_level_bounded<R, F>(
&self,
op: F,
) -> Result<R, StorageError>
pub async fn send_top_level_bounded<R, F>( &self, op: F, ) -> Result<R, StorageError>
Like Self::send_top_level, but bounds the enqueue-capacity wait
with this handle’s configured enqueue_timeout, mirroring
Self::send_bounded for top-level (transaction-skipping) requests
(#1382).
Sourcepub fn queue_depth(&self) -> usize
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.