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 handle observes one more thing: the first answer’s build, asked for through Self::changed_report_with_progress. The session’s 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 changed_report( &mut self, generated_at: SystemTime, format: Format, options: RenderOptions, ) -> Result<Option<Report>>

The current answer, unless a reader of format would see nothing new in it.

A tree changes more often than its answer does. A touch that leaves a file’s size alone, or a write to an entry the selection leaves out, moves the index and marks its batch dirty, and a caller that repaints on every dirty batch then prints the rows it printed a moment ago under a new timestamp (fdu-wb5n). The answer’s identity is what format renders of it with its generation instant held fixed, together with its tree status, its source and freshness, and the diagnostics a frontend writes beside it: its notes and tips (diagnostic_lines) and its warnings (report_warnings). So a tree that shows sizes repaints when a size moves, a listing that shows dates repaints when a date does, machine output repaints when any field it carries does, and a retained observation gap, a coverage change, a freshness change, or a new note such as a .gitignore refused for its limits repaints whether or not format shows it, while the instant a repaint is generated at never counts on its own. A caller that prints no notes, as a quiet one does, may repaint once more than it had to, never once fewer. A session keeps a 128-bit digest of the identity, not the identity. The change records of Self::next_batch are never deduplicated; only this repaint is. The first call always answers, and Self::report always answers.

Errors

As Self::report, and Error::Io when format cannot render the answer.

pub fn changed_report_with_progress( &mut self, generated_at: SystemTime, format: Format, options: RenderOptions, progress: &Progress, ) -> Result<Option<Report>>

Self::changed_report, reporting the answer’s construction through progress.

The same answer as Self::changed_report; the handle observes the build and changes nothing about it. The build enters ProgressPhase::Summarizing, as a one-shot report’s does, so a caller that drew the start through Self::start_with_progress can keep drawing until the first answer exists: a heavy view over a large tree takes seconds to build, and a line stopped when the start returned said nothing about them (fdu-wku3). Later repaints are the progress from there and take Self::changed_report.

Errors

As Self::changed_report.

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.