Struct InputSession 

pub struct InputSession<C: Config> { /* private fields */ }

A transactional session for setting and updating input query values.

InputSession provides a batch interface for modifying input queries with automatic dirty propagation. All changes are buffered during the session lifetime and committed atomically when the session is dropped.

Lifecycle

1. Creation: Obtained via Engine::input_session()
   • Acquires a write lock on the computation graph
   • Increments the global timestamp to invalidate running queries
2. Modification: Use set_input or refresh
   • Changes are buffered in memory
   • Dirty queries are tracked for later propagation
3. Commit: Automatically triggered on drop
   • Dirty propagation executes in parallel via the Rayon thread pool
   • Write buffer is submitted to persistent storage
   • Statistics are reset and internal state is cleaned up

Dirty Propagation

When the session ends, the engine:

• Compares new values with stored values via fingerprint hashing
• Marks queries whose values changed as dirty
• Recursively marks all dependent queries as dirty
• Ensures downstream queries will recompute on next access

Concurrency

Only one input session can be active at a time. Creating a new session while another exists will deadlock, as the write lock cannot be acquired.

The session increments the timestamp on creation, causing any in-flight queries to become stale and await cancellation. This ensures consistency between the input changes and query results.

Implementations

impl<C: Config> InputSession<C>

pub async fn commit(self)

Commits the input session, performing dirty propagation and submitting the write buffer.

impl<C: Config> InputSession<C>

pub async fn set_input<Q: Query>( &mut self, query: Q, new_value: Q::Value, ) -> SetInputResult

Sets the value for an input query.

This method updates the value associated with the given query. If the new value differs from the existing value (based on fingerprint comparison), the query and its dependents will be marked as dirty for recomputation.

Behavior

• New queries: If the query has never been set before, a new entry is created
• Changed values: If the value fingerprint differs from the stored value, dirty propagation is scheduled
• Timestamp management: The first change in a session increments the global timestamp

All dirty propagation happens when the InputSession is dropped, not when this method is called.

Type Parameters

• Q: The query type, must implement Query

Arguments

• query: The input query key
• new_value: The new value to associate with this query

pub async fn update<Q: Query>( &mut self, query: Q, update_fn: impl FnOnce(Option<Q::Value>) -> Q::Value, ) -> SetInputResult

Inspects the current value and performs an update based on the provided function.

This method allows you to read the existing value of an input query, compute a new value based on it, and update the query atomically. The update function receives an Option<Q::Value>, which is None if the query has never been set before, or Some(value) if it has an existing value.

pub async fn refresh<Q: Query>(&mut self)

Refreshes all external input queries of type Q.

This method re-executes all queries of type Q that were previously computed with [ExecutionStyle::ExternalInput]. For each query:

1. The executor is re-invoked to fetch the latest external data
2. The new result is compared with the old result via fingerprints
3. Only if the result changed, the query is marked dirty for propagation

Use Case

External input queries represent data from the outside world (files, network, databases, etc.). When you know the external data has changed, call this method to refresh and update all queries of that type.

Type Parameters

• Q: The query type to refresh. Must implement Query.

Cancellation

This method can be cancelled. However, if cancelled midway, not all queries of type Q may be refreshed, potentially leaving some stale data in the computation graph. Nevertheless, it’s guaranteed that the engine’s internal state will remain consistent.

pub fn intern<T: StableHash + Identifiable + Send + Sync + 'static>( &self, value: T, ) -> Interned<T>

Interns a value, returning a reference-counted handle to the shared allocation.

This is a delegation to Engine::intern. See its documentation for more details.

pub fn intern_unsized<T: StableHash + Identifiable + Send + Sync + 'static + ?Sized, Q: Borrow<T> + Send + Sync + 'static>( &self, value: Q, ) -> Interned<T>

where Arc<T>: From<Q>,

Interns an unsized value, returning a reference-counted handle to the shared allocation.

This is a delegation to Engine::intern_unsized. See its documentation for more details.

Trait Implementations

impl<C: Config> Debug for InputSession<C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C: Config> Drop for InputSession<C>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.