pub trait DerivedQuery:
Send
+ Sync
+ 'static {
type Key: Hash + Eq + Clone + Send + Serialize + 'static;
type Value: Clone + Send + Sync + Serialize + DeserializeOwned + 'static;
const QUERY_TYPE_ID: u32;
const PERSISTENT: bool = true;
const TRACKS_EDGE_REVISION: bool = false;
const TRACKS_METADATA_REVISION: bool = false;
// Required method
fn execute(
key: &Self::Key,
db: &QueryDb,
snapshot: &GraphSnapshot,
) -> Self::Value;
}Expand description
A derived query whose result is memoized in the [ShardedCache].
Concrete queries implement this trait. QueryDb::get::<Q>(key) checks
the cache, validates all applicable dependency tiers, and either returns
the cached value or calls Q::execute, records dependencies, and caches.
§Dependency tracking
During execute, the query should call record_file_dep
for every FileId it reads from. The thread-local recorder collects these
and pairs them with revision numbers after execution completes.
§Tier flags
TRACKS_EDGE_REVISION: Set totruefor queries that answer “who points at X” (callers, cycle membership, reachability). Invalidated when ANY file’s edges change.TRACKS_METADATA_REVISION: Set totruefor queries that read node metadata (entry-point classification forfind_unused). Invalidated when node metadata changes without edge changes.
Required Associated Constants§
Sourceconst QUERY_TYPE_ID: u32
const QUERY_TYPE_ID: u32
Stable on-disk discriminator for PN3 derived-cache persistence.
This u32 is the key written to .sqry/graph/derived.sqry to
identify the query type across process restarts. Unlike
TypeId::of::<Self>(), which is process-local and not stable
across compiler versions, this ID is fixed at authoring time and
must never change or be reused once any derived cache file
containing it has been written.
§Reserved ranges
0x0000— invalid / unknown. Must never appear on disk.0x0001..=0x000F— built-in queries (15 assigned).0x0010..=0x0FFF— reserved for additional built-ins.0x1000..=0xFFFF— reserved for downstream / future built-ins.
See sqry_db::queries::type_ids for the canonical constants.
There is no default value: every implementation must set this
explicitly to prevent accidental ID collisions.
Provided Associated Constants§
Sourceconst PERSISTENT: bool = true
const PERSISTENT: bool = true
Whether this query’s Value satisfies the serde bounds required
for PN3 cold-start persistence.
Set to false for queries whose Value type cannot (or should
not) be serialized to disk. When false, the PN3 persistence
layer skips this query entirely and will recompute it on demand
after a cold start.
The default is true; implementations opt out by overriding.
Sourceconst TRACKS_EDGE_REVISION: bool = false
const TRACKS_EDGE_REVISION: bool = false
Whether this query depends on the global edge topology.
When true, the cached result is invalidated whenever the global edge
revision counter advances (even if the specific files the query read
haven’t changed). This handles the “missing negative dependency”
problem: a new file could add an edge that the query never saw.
Sourceconst TRACKS_METADATA_REVISION: bool = false
const TRACKS_METADATA_REVISION: bool = false
Whether this query depends on node metadata.
When true, the cached result is invalidated whenever the global
metadata revision counter advances.
Required Associated Types§
Sourcetype Key: Hash + Eq + Clone + Send + Serialize + 'static
type Key: Hash + Eq + Clone + Send + Serialize + 'static
The input key for this query.
The serde::Serialize bound is required by the PN3 persistence layer:
[ShardedCache::insert_query] serialises the key to raw bytes at insert
time so that the key can be round-tripped to disk without re-running the
query. All built-in query keys already implement Serialize; downstream
or test keys using primitive types (u32, String, etc.) also satisfy
this bound automatically.
Sourcetype Value: Clone + Send + Sync + Serialize + DeserializeOwned + 'static
type Value: Clone + Send + Sync + Serialize + DeserializeOwned + 'static
The output value. Must be Clone for cache retrieval.
The serde::Serialize bound is required by the PN3 persistence layer
so that warm-path writes can be saved to disk.
The serde::de::DeserializeOwned bound is required by the PN3 cold-load
path: when a rehydrated entry is first found by a typed get::<Q>, the
raw result bytes must be decoded back into Q::Value before they can
be returned to the caller. Without this bound, “first query after cold
start is free” would degrade into “first query misses, second is free”,
which violates spec §2.
Non-serialisable value types must use PERSISTENT = false to opt out
of raw-byte retention.
Required Methods§
Sourcefn execute(
key: &Self::Key,
db: &QueryDb,
snapshot: &GraphSnapshot,
) -> Self::Value
fn execute( key: &Self::Key, db: &QueryDb, snapshot: &GraphSnapshot, ) -> Self::Value
Computes the query result.
Implementations MUST call record_file_dep
for every FileId they read from the snapshot.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.