Struct InputSession 

pub struct InputSession<'x, 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.

Example

use qbice::Engine;

// Initial setup
{
    let mut session = engine.input_session();
    session.set_input(UserId, 42);
    session.set_input(UserName, "Alice");
} // Changes committed and dirty propagation occurs here

// Query dependent values
let profile = engine.query(UserProfile(42)).await;

// Update an input
{
    let mut session = engine.input_session();
    session.set_input(UserName, "Alice Smith"); // Only this query marked dirty
} // Dirty propagation recomputes affected queries

Implementations

impl<C: Config> InputSession<'_, C>

pub 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 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.

Example

// Assume ConfigFileQuery reads configuration from disk
// and was executed with ExecutionStyle::ExternalInput

// When you know the config file has changed:
{
    let mut session = engine.input_session();
    session.refresh::<ConfigFileQuery>().await;
} // Only changed ConfigFileQuery instances will trigger dirty
  // propagation

Type Parameters

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

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.