Struct TrackedEngine 

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

A wrapper around Arc<Engine> that enables query execution.

TrackedEngine is the primary interface for executing queries in QBICE. It wraps an Arc<Engine> and provides dependency tracking during query execution, which is essential for the incremental computation system.

Purpose

The TrackedEngine serves two key purposes:

1. Dependency Tracking: Records which queries depend on which other queries during execution
2. Local Caching: Maintains a fast local cache for frequently accessed query results

Creating a TrackedEngine

Create from an Arc<Engine> using the tracked method:

use std::sync::Arc;
use qbice::Engine;

let engine: Engine<_> = /* ... */;
let engine = Arc::new(engine);
let tracked = engine.tracked();

Executing Queries

Use the query method to execute queries:

let result = tracked.query(&my_query).await?;

Thread Safety

TrackedEngine implements Clone, Send, and Sync:

• Clone: Cheap to clone, shares the underlying engine and local cache
• Send: Can be moved to other threads
• Sync: Can be shared across threads via Arc or references

This enables concurrent query execution:

let tracked = engine.tracked();

// Clone for concurrent execution
let tracked1 = tracked.clone();
let tracked2 = tracked.clone();

tokio::spawn(async move {
    tracked1.query(&query1).await
});

tokio::spawn(async move {
    tracked2.query(&query2).await
});

Local Caching

Each TrackedEngine maintains a local cache of query results. Clones share this cache:

TrackedEngine
  ├─ Arc<Engine>           (shared)
  └─ Arc<LocalCache>       (shared among clones)

Benefits:

• Fast repeated access to the same query within a “session”
• Reduces contention on the central database

Lifecycle Management

The typical pattern for using TrackedEngine:

// 1. Create and use
let mut engine_arc = Arc::new(engine);
let tracked = engine_arc.clone().tracked();
let result = tracked.query(&query).await?;

// 2. Drop to release Arc reference
drop(tracked);

// 3. Modify inputs
let mut session = engine_arc.input_session();
session.set_input(input_query, new_value);
drop(session);

// 4. Create new TrackedEngine for next round
let tracked = engine_arc.clone().tracked();

Relationship to Engine

TrackedEngine doesn’t own the Engine; it holds an Arc reference. This design allows:

• Multiple concurrent query executors
• Proper cleanup of local state between input updates
• Clear separation between querying and modification phases

Implementations

impl<C: Config> TrackedEngine<C>

pub fn get_dirtied_edges_count(&self) -> usize

Gets the number of dirtied edges in the current timestamp.

impl<C: Config> TrackedEngine<C>

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

Executes a query and returns its value.

This is the primary method for retrieving computed values from the engine. The engine will:

1. Check the local cache for a cached result
2. Check if the query has a valid cached result in the database
3. If not valid, execute the query’s registered executor
4. Track dependencies if called from within another executor

Incremental Behavior

Results are cached and reused when possible. A query is recomputed only if:

• It has never been computed before
• Any of its dependencies have changed since the last computation

Errors

Returns CyclicError if a cyclic dependency is detected (the query directly or indirectly depends on itself).

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 Interner::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 Interner::intern_unsized. See its documentation for more details.

Trait Implementations

impl<C: Config> Clone for TrackedEngine<C>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.