Skip to main content

spawn

Function spawn 

Source
pub fn spawn(
    pool: &ConnectionPool,
    capacity: usize,
) -> Result<WriterTaskHandle, SqliteError>
Expand description

Spawn the write-owner task (ADR-067 Component A) on the current Tokio runtime.

Opens a dedicated standalone writer connection independent of the pool’s Mutex-guarded writer() connection used by unmigrated paths. That one-time infrastructure open is uncounted; every dequeued top-level request or successful BEGIN IMMEDIATE increments the writer-task acquisition class. Returns the cloneable WriterTaskHandle sender half. The task normally runs until every handle clone is dropped and the channel closes; a request panic, failed rollback, or poisoned connection puts it into the permanent terminal state documented below.

§Terminal settlement

Retiring an unsettled writer, including when its blocking owner unwinds, releases the volume lease only after cleanup restored autocommit or the connection closed. If neither is possible, path, volume, and errors are reported to stderr and tracing and the pool is poisoned: that request reports SqliteError::WriterSettlementUnknown and every later write is refused with SqliteError::WriterPoisoned before it starts.

capacity bounds the channel (PoolConfig::write_queue_capacity / KHIVE_WRITE_QUEUE_CAPACITY, ADR-067 recommends 256).

§Errors

Must be called from within a Tokio runtime context (calls tokio::spawn). Returns an error if the pool cannot open a standalone writer connection (e.g. an in-memory pool has no standalone-connection support). See crates/khive-db/docs/api/writer-task.md for the migration-slice scope this commits per BEGIN IMMEDIATE.