Struct DerivationPool 

pub struct DerivationPool { /* private fields */ }

The worker-pool seam for an external writer. See the module docs. Single-thread-use, like Cluster: the pool handle lives on the writer’s thread (the hooks fire there), and only Send data crosses to the workers.

Implementations

impl DerivationPool

pub fn spawn( path: impl AsRef<Path>, n_workers: usize, opts: OpenOptions, ) -> Result<(DerivationPool, Receiver<ClusterEvent>), ReplicaError>

Spawn n_workers IVM worker threads over the file-backed database at path, using the planner, operator-storage, journal, and foreign-key options. The host owns its writer’s wal_autocheckpoint; the pool does not configure it. Returns the pool and the bounded channel-out of derived ClusterEvents (max(256, n_workers · 16) events — FOLLOWER-LAG-SHED §4, rung 0b; see the module docs’ draining contract). Asserts sqlite3_threadsafe() != 0.

pub fn n_workers(&self) -> usize

The number of worker slots (fixed at spawn; the query_id % n shard count).

pub fn worker_of(&self, query_id: QueryId) -> usize

The worker slot that hosts (or would host) query_id. The pool owns the shard mapping; callers key per-query progress by this index rather than recomputing it.

pub fn register_table( &self, table: &str, schema: TableSchema, ) -> Result<(), ReplicaError>

Build the table’s source on every worker (any may host a query referencing it). Idempotence and the PK-UNIQUE-index prerequisite are the caller’s concern — the discovery/ensure half lives with whoever owns a connection (the host), e.g. discover_table_schema + ensure_unique_pk_index. Must not be called while the writer’s transaction is open: the workers build sources against committed state.

pub fn register_query( &self, query_id: QueryId, ast: Ast, hydrated_tx: u64, ) -> Result<usize, ReplicaError>

Register + hydrate a live query on its shard (worker_of); blocks until the worker built + hydrated it (a BuildError surfaces here), then the worker emits the Hydrated baseline — stamped hydrated_tx, the caller’s committed watermark — to the channel-out. Returns the hosting worker’s index.

pub fn deregister_query(&self, query_id: QueryId) -> bool

Gracefully tear down a query (solicited — no Faulted event; after this returns no further events arrive for query_id). Returns true if a live query was found and removed; idempotent.

pub fn read_snapshot( &self, query_id: QueryId, ) -> Result<Vec<ChangeEvent>, ReplicaError>

Re-read the current assembled view of query_id from its hosting worker as hydration Adds (the SSR one-shot). FIFO with commits on that worker, so the returned view reflects every transaction whose gate was released before this call. A degraded shard or unregistered query reads as an empty snapshot; a raised read boundary on a live worker is Err. Must not be called between begin and the gate release.

pub fn begin(&self, tx_id: u64) -> Option<PoolTxn>

The begin-barrier for one committing transaction: every live worker opens + pins its read snapshot at the pre-commit state and acks. Some ⇒ all pinned — stream the capture with PoolTxn::push and finish for the gate. None ⇒ a worker died or stalled at the barrier: the workers that did pin were rolled back cleanly (nothing was pushed) and the offender was reaped/respawned (its lost queries got terminal Faulted events) — but every OTHER worker now misses this transaction too, so if the host’s commit proceeds anyway, the caller must fault + re-register every remaining query (see the module docs).

pub fn reap(&self)

Liveness sweep: block until every worker has drained its command queue, respawning any that died or hung (their lost queries get terminal Faulted events). The quiesce point — a returned sweep implies all prior registrations and released gates have emitted their events to the channel-out. Mirrors Cluster::sync.

pub fn set_push_deadline_ms(&self, ms: u64)

Set the per-push derive deadline (FOLLOWER-LAG-SHED §6.6), in ms; 0 disables it. Applies immediately to every worker, respawns included. Default 10 s.

pub fn set_max_delta_bytes(&self, bytes: usize)

Override every worker engine’s design-306 D4 delta-byte budget (see Db::set_max_delta_bytes). Workers re-read it at each commit barrier, so it lands on the next transaction, respawns included. A worker whose batch delta overflows the budget sheds itself: tear down + terminal Faulted per hosted query.