Struct Session 

pub struct Session { /* private fields */ }

An index paired with a watcher, answering one request continuously.

Implementations

impl Session

pub fn start(request: Request, delivery: Delivery) -> Result<Self>

Open a tree and bind observation under the shared execution plan.

Startup persistence is joined before binding the session. A save failure is returned by the first persist_due call, so it does not discard a valid live answer. Filesystem and observation failures still fail startup.

pub fn start_with_progress( request: Request, delivery: Delivery, progress: &Progress, ) -> Result<Self>

Self::start, reporting the initial scan through progress as it runs.

The same session as Self::start; the handle observes the start and changes nothing about it. A start is two passes: the open (cold, or a load and revalidation) with its save, if it writes one, joined under ProgressPhase::Saving, and then the revalidation that closes the gap between that walk and the bound watcher. The second pass begins again at ProgressPhase::Revalidating with the walk counters restarted, so they end at the tree’s totals once, not twice. Once this returns the session reports nothing further through the handle; its repaints are the progress from there.

pub fn persist_due(&mut self, now: Instant) -> SaveOutcome

Persist pending changes when the watch delivery’s interval has elapsed.

Call this after batches and idle timeouts. Only a completed write clears pending changes; a refused or failed write is retried on a later interval. now is a monotonic caller-supplied clock so wall-clock corrections cannot postpone saves.

pub fn new( index: IndexHandle, request: Request, delivery: &Delivery, watch: WatchConfig, ) -> Result<Self>

Start watching an already-opened index, answering request as the tree changes.

request carries its own now, fixed when it was built: a watch answers one request as the tree changes, and a relative time window that slid under it would make two repaints answer two different questions.

delivery is the one its caller opened the index under. It is taken rather than composed here because the cache policy is part of it: a session built against a fabricated Delivery read cache: Auto whatever the caller had asked for, so RequestError::WatchCacheOnly could not fire inside the engine at all and the rule held only at the two front doors (fdu-i18y). Starting a session is what a watch is, so the delivery is read as a watch whether or not the caller remembered to say so.

Refusals are in the order every route publishes: what no delivery can carry first, then what this index was taken under, then what it holds. The request-level rule speaks first, so a library caller watching a depth-2 request is told the watch cannot narrow its scope rather than that the index has another scope.

Errors

Error::InvalidRequest when a watch cannot deliver the request – a narrowed scan scope, content analysis nothing re-reads, a snapshot nothing verified – or when this index cannot answer it, including a selection by ignored state over an index that observed no control state. Error::ScanScopeMismatch when the index was not taken under the request’s scope.

pub fn request(&self) -> &Request

The request this session answers.

pub fn query(&self) -> &Query

The query this session answers.

pub fn report(&self, generated_at: SystemTime) -> Result<Report>

Render the current answer.

The same report a one-shot run produces, from the same index, which is what makes “watch is the same query repeated” true rather than aspirational.

pub fn index_snapshot(&self) -> Result<Index>

A consistent copy of the current index.

Used to persist a live session without holding a lock across the write.

pub fn next_batch(&mut self, timeout: Duration) -> Result<Option<Batch>>

Wait for the next batch of changes, up to timeout.

Returns None when nothing arrived in the window, which is the idle case and costs no filesystem work.

Takes &mut self because consuming from the event queue is a mutation: two callers draining one session would each see an arbitrary half of the stream.