Struct QueryRuntime 

pub struct QueryRuntime { /* private fields */ }

The query runtime manages query execution, caching, and dependency tracking.

This is cheap to clone - all data is behind Arc.

Example

let runtime = QueryRuntime::new();

// Sync query execution
let result = runtime.query(MyQuery { ... })?;

// Async query execution (waits through Suspend)
let result = runtime.query_async(MyQuery { ... }).await?;

Implementations

impl QueryRuntime

pub fn new() -> Self

Create a new query runtime with default settings.

pub fn builder() -> QueryRuntimeBuilder

Create a builder for customizing the runtime.

Example

let runtime = QueryRuntime::builder()
    .error_comparator(|a, b| {
        // Custom error comparison logic
        match (a.downcast_ref::<MyError>(), b.downcast_ref::<MyError>()) {
            (Some(a), Some(b)) => a == b,
            _ => false,
        }
    })
    .build();

pub fn query<Q: Query>(&self, query: Q) -> Result<Arc<Q::Output>, QueryError>

Execute a query synchronously.

Returns the cached result if valid, otherwise executes the query.

Errors

• QueryError::Suspend - Query is waiting for async loading
• QueryError::Cycle - Dependency cycle detected

pub fn invalidate<Q: Query>(&self, key: &Q::CacheKey)

Invalidate a query, forcing recomputation on next access.

This also invalidates any queries that depend on this one.

pub fn clear_cache(&self)

Clear all cached values.

impl QueryRuntime

pub fn register_asset_locator<K, L>(&self, locator: L)

where K: AssetKey, L: AssetLocator<K>,

Register an asset locator for a specific asset key type.

Only one locator can be registered per key type. Later registrations replace earlier ones.

Example

let runtime = QueryRuntime::new();
runtime.register_asset_locator(FileSystemLocator::new("/assets"));

pub fn pending_assets(&self) -> Vec<PendingAsset>

Get an iterator over pending asset requests.

Returns assets that have been requested but not yet resolved. The user should fetch these externally and call resolve_asset().

Example

for pending in runtime.pending_assets() {
    if let Some(path) = pending.key::<FilePath>() {
        let content = fetch_file(path);
        runtime.resolve_asset(path.clone(), content);
    }
}

pub fn pending_assets_of<K: AssetKey>(&self) -> Vec<K>

Get pending assets filtered by key type.

pub fn has_pending_assets(&self) -> bool

Check if there are any pending assets.

pub fn resolve_asset<K: AssetKey>(&self, key: K, value: K::Asset)

Resolve an asset with its loaded value.

This marks the asset as ready and invalidates any queries that depend on it (if the value changed), triggering recomputation on next access.

This method is idempotent - resolving with the same value (via asset_eq) will not trigger downstream recomputation.

Uses the asset key’s default durability.

Example

let content = std::fs::read_to_string(&path)?;
runtime.resolve_asset(FilePath(path), content);

pub fn resolve_asset_with_durability<K: AssetKey>( &self, key: K, value: K::Asset, durability: DurabilityLevel, )

Resolve an asset with a specific durability level.

Use this to override the asset key’s default durability.

pub fn invalidate_asset<K: AssetKey>(&self, key: &K)

Invalidate an asset, forcing queries to re-request it.

The asset will be marked as loading and added to pending assets. Dependent queries will suspend until the asset is resolved again.

Example

// File was modified externally
runtime.invalidate_asset(&FilePath("config.json".into()));
// Queries depending on this asset will now suspend
// User should fetch the new value and call resolve_asset

pub fn remove_asset<K: AssetKey>(&self, key: &K)

Remove an asset from the cache entirely.

Unlike invalidate_asset, this removes all traces of the asset. Dependent queries will go through the locator again on next access.

Trait Implementations

impl Clone for QueryRuntime

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for QueryRuntime

fn default() -> Self

Returns the “default value” for a type.