Skip to main content

Engine

Struct Engine 

Source
pub struct Engine {
    pub env: Rc<Env>,
    pub deferred_slots: RefCell<Vec<(Inst, String)>>,
    pub failed_inputs: RefCell<HashSet<String>>,
    pub track: Cell<bool>,
    pub deferred_roots: RefCell<Vec<DeferredRoot>>,
    pub prev: RefCell<Option<Rc<Engine>>>,
    pub programs: RefCell<Option<Rc<Programs>>>,
    pub revisions: RefCell<Option<Rc<Revisions>>>,
    pub edits: RefCell<Option<Rc<Edits>>>,
    pub round_cache: RefCell<Option<Rc<RoundCache>>>,
    /* private fields */
}
Expand description

the evaluator (§9): binds documents and expressions to types, forces slots lazily with dependency tracking, validates, serializes

Fields§

§env: Rc<Env>

the environment the roots live in

§deferred_slots: RefCell<Vec<(Inst, String)>>

slots whose forcing was deferred to phase 2 (a $referrers read, a reference not yet bound)

§failed_inputs: RefCell<HashSet<String>>

inputs whose fallback failed to bind: later demands are tainted, not re-reported

§track: Cell<bool>

Sessions and retained reference rounds enable dependency recording. Ordinary one-shot work avoids the per-slot graph allocation (F21).

§deferred_roots: RefCell<Vec<DeferredRoot>>

roots whose binding deferred through $referrers in phase 1: bound again after the deferred slots

§prev: RefCell<Option<Rc<Engine>>>

the previous round, frozen

§programs: RefCell<Option<Rc<Programs>>>

Shared executable programs, enabled by the query evaluator.

§revisions: RefCell<Option<Rc<Revisions>>>

Revision stamps for retained queries.

§edits: RefCell<Option<Rc<Edits>>>

Retained queries for document edits in a Session.

§round_cache: RefCell<Option<Rc<RoundCache>>>

Reference-round reuse state, enabled by the query evaluator.

Implementations§

Source§

impl Engine

Source

pub const ROUNDS: u32 = 8

how many rounds a universe may take to settle (§7.6)

Source

pub fn cached_literals(&self) -> usize

Number of retained unbound-literal materializations (a diagnostic counter).

Source

pub fn materialization_diagnostics(&self) -> Value

Diagnostic cache table/root-handle counts; no entry or reachable-graph scan.

Source

pub fn bare(env: Rc<Env>) -> Rc<Engine>

an engine without registering itself as the environment’s evaluator

Source

pub fn retained_path(&self, segments: &[Seg]) -> Rc<PrefixPath>

Retain an immutable container path, sharing prefixes within this engine. The returned outer Rc is new even when its full prefix chain is shared.

Source

pub fn container_path(&self, segments: &[Seg]) -> PrefixPath

Retain an inline container path, sharing immutable prefix nodes. Use this for ArrV::path and MapV::path; no outer Rc is allocated.

Source

pub fn retained_path_pool_stats(&self) -> PrefixPathPoolStats

Explicit diagnostic scan of the bounded path pool, outside hot binding.

Source

pub fn query_slot(&self, key: &str) -> Option<(Inst, String)>

Find an indexed member by its textual query key.

The returned instance is a shared live handle, not a copied record. Retaining it retains that value; the query index itself is not exposed.

Source

pub fn dependency_queries(&self) -> usize

Number of computations with a retained read set, including empty sets.

Source

pub fn indexed_slots(&self) -> usize

Number of registered member slots in the query index.

Source

pub fn query_dependencies_for(&self, key: &str) -> Option<Vec<String>>

Export one computation’s sorted dependencies without copying other owners.

An absent owner returns None; a retained empty read set returns Some(Vec::new()). Changing the owned result does not change the graph.

Source

pub fn query_stack(&self) -> Vec<String>

Export active computation keys, outermost first and innermost last.

The owned snapshot preserves order and does not retain the live stack.

Source

pub fn query_dependencies(&self) -> Vec<(String, Vec<String>)>

Export a sorted textual dependency graph for explicit inspection.

The returned owned snapshot does not mutate or retain the live graph. An owner with an empty list is distinct from an absent owner.

Source

pub fn query_slot_keys(&self) -> Vec<String>

Export the sorted logical keys of registered slots for inspection.

Source

pub fn query_storage(&self) -> BTreeMap<&'static str, usize>

Inspect query representation storage without copying graph text.

Pool counts cover the shared evaluation lineage, including identities held by old runs or snapshots. Read-set and index counts cover this engine. Capacities are usable entries and payload sizes exclude allocator metadata; these counters are not process RSS. This method does not prune.

Source

pub fn root(&self, name: &str) -> Option<Value>

The root’s value as this engine’s expressions read it: its own universe once frozen.

Source

pub fn slot_key(inst: &Inst, name: &str) -> String

The key of a slot in the dependency graph: the instance’s path and the member’s name.

Source

pub fn record(&self, read: String)

Record that the computation in progress read a slot (dependency tracking).

Source

pub fn step<T>(&self, key: &str, f: impl FnOnce() -> T) -> T

Run a computation as a step of the dependency graph, its reads recorded under key.

Source

pub fn phase(&self) -> u8

The evaluation phase: 1 while the roots bind, 2 while the deferred slots force (§9.3).

Source

pub fn new(env: Rc<Env>) -> Rc<Engine>

An engine over an environment, wired in as its constant and expression evaluator.

Source

pub fn install_hooks(self: &Rc<Self>, env: &Rc<Env>, with_menv: bool)

§4.13 / unit factors: let the environment evaluate constants through this engine

Source

pub fn ev(&self, e: &Rc<Expr>, sc: &Scope) -> R<Value>

Evaluate an expression in a scope (§4, §9).

Source

pub fn member_of(&self, v: &Value, rt: &RT, sc: &Scope) -> bool

Whether a value belongs to a type, as in and match decide it (§4.9).

Source

pub fn demand_input(&self, menv: &Rc<Env>, name: &str) -> R<Option<Value>>

An input read by an output: the bound document, its fallback, or none (§5.6, §9.4).

Source

pub fn should_bind_root(&self, name: &str) -> bool

Bind a root — an output’s expression or an input’s document — to its declared type (§9.2). Whether this root needs binding in the retained round.

Source

pub fn bind_root(&self, name: &str, src: RootSrc<'_>, rt: &RT, sc: &Scope)

Bind a root, retaining its source when it must defer to phase two.

Source

pub fn bind_deferred_roots(&self)

phase 2: the roots that deferred are bound again (after the deferred slots)

Source

pub fn iterate(&self, v: &Value) -> R<Vec<Value>>

the items of an array (or a range); an error for anything else

Source

pub fn deref(&self, v: Value) -> R<Value>

Read through a reference to the value it names (§7.4).

Source

pub fn resolve_segs(&self, segs: &[Seg]) -> R<Value>

The value at a canonical path from a root (§7.2), forcing what the path crosses.

Source

pub fn resolve_canonical(&self, segs: &[Seg]) -> R<Value>

The value at a canonical path as a document’s reference string names it (§7.5).

Source

pub fn access(&self, x: &Value, name: &str) -> R<Value>

a member of a record (or an unbound literal) by name; ABSENT when absent

Source

pub fn call(&self, f: &Value, args: Vec<Value>, sc: &Scope) -> R<Value>

Apply a function value — a closure, a native, a standard-library function — to arguments (§4.8).

Source

pub fn mat_val(&self, v: Value) -> R<Value>

A value with its literal (or document) form materialized.

Source

pub fn entries_of(&self, es: &[(String, Value)]) -> R<Vec<(String, Value)>>

The entries of an unbound object literal with its spreads (§4.2) expanded in place: a spread copies the entries of an object-valued operand — a record’s value members (hidden ones are not entries), a map’s entries, or another literal’s — and a key produced twice is E5004. Spread operands evaluate in the literal’s own scope.

Source

pub fn settle( &self, env: &Env, edges: HashMap<String, BTreeMap<String, (SegPath, Vec<SegPath>)>>, ) -> Settled

Phase 2, one round: the deferred slots and roots, then everything; stable when the queried edges did not change.

Source

pub fn muted<T>(&self, f: impl FnOnce() -> T) -> T

Run inside a frozen round: what it reports is not this evaluation’s.

Source

pub fn evaluate( env: &Rc<Env>, bind: &dyn Fn(&Rc<Engine>), track: bool, ) -> Rc<Engine>

Evaluate a universe (§7.6, §9.3): bind binds every root on a fresh engine; the rounds repeat, each answering $referrers from the previous round, until the queried edges are stable — the settled engine is the result. A universe still changing after ROUNDS rounds is E5009.

Source

pub fn evaluate_query(env: &Rc<Env>, bind: &dyn Fn(&Rc<Engine>)) -> Rc<Engine>

Evaluate with retained member, structure and reference dependencies.

Source

pub fn evaluate_session( env: &Rc<Env>, bind: &dyn Fn(&Rc<Engine>), initial: Option<Rc<Engine>>, ) -> Rc<Engine>

Evaluate a Session, reusing its engine after an edited materialization.

Source

pub fn bind( &self, raw: Value, rt: &RT, path: &[Seg], parent: Option<&Inst>, sc: &Scope, ) -> R<Value>

Bind a raw value to a type at a path (§9.2): a record instance with its slots, an array, a map, or a scalar checked against the type.

Source

pub fn eval_place(&self, e: &Rc<Expr>, sc: &Scope) -> R<Option<SegPath>>

Evaluate an expression as a place — a canonical path — where a reference is expected (§7.4); none when it names no place.

Source

pub fn materialize(&self, v: Value, path: &[Seg]) -> R<Value>

Force a value whole, recursively, so it can be serialized or compared.

Source

pub fn force_state(&self, inst: &Inst, name: &str) -> SlotState

Force a slot and tell how it ended: ok, invalid, absent.

Source

pub fn force_slot_safe(&self, inst: &Inst, name: &str)

Force a slot, a failure recorded as its state rather than raised.

Source

pub fn force_slot(&self, inst: &Inst, name: &str) -> R<Value>

Force a slot — its check, default, or derived expression — once, with dependency tracking (§9.3).

Source

pub fn force_const_in( &self, env: &Rc<Env>, name: &str, root_name: &str, ) -> R<Value>

The value of a module-level constant, evaluated once in its module’s environment.

Source

pub fn force_all(&self, v: &Value)

Force every slot under a value, recursively.

Source

pub fn set_phase(&self, p: u8)

the evaluation phase: 1 materialization, 2 universe complete ($referrers answers)

Source

pub fn force_roots(&self, env: &Env)

force every root, run the $referrers phase, then the assertion pass force every root, the roots demanded on the way included (an input bound through its fallback while another root is forced becomes a root too, and is forced in the same pass — the reference walks the live root map)

Source

pub fn validate_all(&self, root_name: &str)

Run every assertion of every instance, reporting under the root’s name (§6).

Source

pub fn validate_inst(&self, inst: &Inst, root_name: &str)

Run one instance’s assertions, invalidating it on an error-severity failure (§6.6).

Source

pub fn reset_slot(&self, key: &str) -> bool

reset a computed slot so that it is computed again (dependency tracking)

Source

pub fn serialize( &self, v: &Value, root_name: &str, settable_only: bool, ) -> String

canonical JSON of a value (§10.4, D29): derived members included, hidden never; settable_only is the tool option D29 provides — the settable projection (required, optional, defaulted members) that a document for the same type would carry

Examples found in repository?
examples/serialization_census.rs (line 62)
27fn run() {
28    let args: Vec<String> = std::env::args().collect();
29    assert!(args.len() == 6 || args.len() >= 8, "{USAGE}");
30    let model = Path::new(&args[1]).canonicalize().unwrap();
31    let input = Path::new(&args[3]).canonicalize().unwrap();
32    let (input_name, root, output_file) = (&args[2], &args[4], Path::new(&args[5]));
33    assert!(!output_file.exists(), "refusing to overwrite the output");
34    let edit_path = args.get(6);
35    let mut steps: Vec<(&str, Option<&String>)> = vec![("initial", None), ("repeated", None)];
36    steps.extend(args.iter().skip(7).map(|value| ("update", Some(value))));
37
38    let mut session = Session::new(Some(model.to_str().unwrap()));
39    session
40        .apply(Op::Bind {
41            name: input_name.clone(),
42            src: BindSource::Inline {
43                text: std::fs::read_to_string(&input).unwrap(),
44            },
45        })
46        .unwrap();
47    let mut rows = Vec::with_capacity(steps.len());
48    for (index, (operation, value)) in steps.into_iter().enumerate() {
49        if let Some(value) = value {
50            session
51                .apply(Op::Edit {
52                    kind: EditKind::Update,
53                    path: edit_path.expect("an edit value without a path").clone(),
54                    expr: Some(value.clone()),
55                })
56                .unwrap();
57        }
58        let run = session.run(Mode::Full);
59        let eng = run.eng.as_ref().expect("Session did not return an engine");
60        let value_root = eng.env.root(root).expect("the root was not evaluated");
61        // The census follows the emission it describes and shares no work with it.
62        let output_bytes = eng.serialize(&value_root, root, false).len();
63        let counted = census(&value_root, false);
64        rows.push(json!({
65            "operation": operation, "index": index, "value": value, "output_bytes": output_bytes,
66            "diagnostics": {
67                "load": run.load_diags.len(), "checks": run.checks.len(),
68                "session_checks": run.session_checks.len(), "evaluation": run.diags.len(),
69            },
70            "census": counted,
71        }));
72    }
73    let report = json!({
74        "schema": 1, "kind": "serialization-census", "timing_claim": false,
75        "allocator": "MiMalloc", "root": root, "input_name": input_name, "edit_path": edit_path,
76        "query_engine_environment": {
77            "DECL_QENGINE": std::env::var("DECL_QENGINE").ok(),
78            "DECL_QENGINE_STRICT": std::env::var("DECL_QENGINE_STRICT").ok(),
79        },
80        "rows": rows,
81    });
82    let mut file = std::fs::OpenOptions::new()
83        .write(true)
84        .create_new(true)
85        .open(output_file)
86        .unwrap();
87    file.write_all(&serde_json::to_vec_pretty(&report).unwrap())
88        .unwrap();
89    file.write_all(b"\n").unwrap();
90}
More examples
Hide additional examples
examples/session_initial.rs (lines 108-114)
73fn run() {
74    assert_eq!(std::env::var("DECL_QENGINE").as_deref(), Ok("1"));
75    assert_eq!(std::env::var("DECL_QENGINE_STRICT").as_deref(), Ok("1"));
76    let args: Vec<String> = std::env::args().collect();
77    assert_eq!(
78        args.len(),
79        5,
80        "usage: session-initial MODEL INPUT_ROOT=INPUT_FILE OUTPUT_ROOT OUTPUT_PREFIX"
81    );
82    let model = Path::new(&args[1]).canonicalize().unwrap();
83    // The command line's own spelling of a bound input: `--input name=file`.
84    let (input_root, input_path) = args[2]
85        .split_once('=')
86        .expect("the input is written INPUT_ROOT=INPUT_FILE");
87    let input = Path::new(input_path).canonicalize().unwrap();
88    let output_root = args[3].as_str();
89    let output_file = format!("{}-{output_root}.json", args[4]);
90    let metrics_file = format!("{}-initial.json", args[4]);
91    assert!(!Path::new(&output_file).exists() && !Path::new(&metrics_file).exists());
92    let mut stamps = [Stamp::default(); 9];
93    stamps[0] = stamp();
94    let mut session = Session::new(Some(model.to_str().unwrap()));
95    session
96        .apply(Op::Bind {
97            name: input_root.into(),
98            src: BindSource::Inline {
99                text: std::fs::read_to_string(&input).unwrap(),
100            },
101        })
102        .unwrap();
103    stamps[1] = stamp();
104    let run = session.run(Mode::Full);
105    stamps[2] = stamp();
106    let eng = run.eng.as_ref().expect("Session did not return an engine");
107    stamps[3] = stamp();
108    let output = eng.serialize(
109        &eng.env
110            .root(output_root)
111            .expect("the model declares no such output root"),
112        output_root,
113        false,
114    );
115    stamps[4] = stamp();
116
117    // Plain copies only. The Edits owner survives the write as in the old probe.
118    let edits = eng.edits.borrow().as_ref().unwrap().clone();
119    let rev = &edits.revisions;
120    let counters = [
121        rev.revision.get(),
122        rev.verified_cutoffs.get(),
123        rev.value_cutoffs.get(),
124        rev.recomputed.get(),
125        edits.slot_computes.get(),
126        edits.prepared_queries.get(),
127        edits.retained_records.get(),
128    ];
129    let diagnostics = [
130        run.load_diags.len(),
131        run.checks.len(),
132        run.session_checks.len(),
133        run.diags.len(),
134    ];
135    let post_serialize_diags = eng.env.diag_len();
136    let timing = run.timing;
137    let output_bytes = output.len();
138    let module_count = run.modules.len();
139    stamps[5] = stamp();
140    write_new(Path::new(&output_file), output.as_bytes());
141    stamps[6] = stamp();
142    // These are the ordinary end-of-request owners, followed by Session itself.
143    // No manual cycle collection, early owner release, or graph census is added.
144    drop(edits);
145    drop(output);
146    drop(run);
147    stamps[7] = stamp();
148    drop(session);
149    stamps[8] = stamp();
150
151    // Only scalar diagnostic metadata escapes the ordinary runtime lifetime.
152    let gc = decl_lang::semantics::take_gc_diagnostics();
153    let evaluation = decl_lang::evaluation_diagnostics::take_evaluation_diagnostics();
154    assert_eq!(diagnostics, [0; 4], "initial Session diagnostics");
155    assert_eq!(post_serialize_diags, 0, "serialization diagnostics");
156    let setup_s = seconds(stamps[0], stamps[1]);
157    let full_s = seconds(stamps[1], stamps[2]);
158    let serialize_s = seconds(stamps[3], stamps[4]);
159    let request = json!({
160        "operation": "initial", "index": 0, "value": null,
161        "setup_s": setup_s, "apply_s": 0.0,
162        "evaluate_validate_s": full_s, "serialize_s": serialize_s,
163        "total_s": full_s + serialize_s,
164        "measurement_boundary": "apply + Session.run(Full) + serialize the output root; setup, counters, diagnostics inspection, output writes, and teardown excluded",
165        "internal_timing_s": timing.total / 1000.0,
166        "internal_recomputed": timing.recomputed, "internal_slots": timing.slots,
167        "revision_total": counters[0],
168        "revision_delta": {"revision": counters[0], "verified_cutoffs": counters[1],
169            "value_cutoffs": counters[2], "recomputed": counters[3]},
170        "revision_counters_total": {"verified_cutoffs": counters[1],
171            "value_cutoffs": counters[2], "recomputed": counters[3]},
172        "prepared_queries_latest_edit": counters[5], "prepared_queries_this_request": 0,
173        "prepared_counter_semantics": "latest-edit gauge; this_request is zero when the revision did not advance",
174        "slot_computes_total": counters[4], "slot_computes_delta": counters[4],
175        "retained_records_latest_edit": counters[6],
176        "diagnostics": {"load": diagnostics[0], "check": diagnostics[1],
177            "session_check": diagnostics[2], "evaluation": diagnostics[3]},
178        "output_bytes": output_bytes,
179    });
180    let boundaries: Vec<_> = stamps
181        .iter()
182        .enumerate()
183        .map(|(i, s)| {
184            json!({
185                "after": if i == 0 { "start" } else { PHASES[i - 1] },
186                "wall_ns": s.wall_ns, "cpu_ns": s.cpu_ns,
187                "sampled_until_ns": s.sampled_until_ns, "allocation": s.allocation,
188            })
189        })
190        .collect();
191    let row = json!({
192        "schema": 1, "role": "initial-session-support", "primary_timing": false,
193        "build_manifest_dir": env!("CARGO_MANIFEST_DIR"), "model": model, "input": input,
194        "input_root": input_root, "output_root": output_root,
195        "output_file": output_file, "output_bytes": output_bytes,
196        "module_count": module_count, "request": request,
197        "diagnostic_counts": diagnostics, "post_serialize_diags": post_serialize_diags,
198        "run_timing_ms": {"load": timing.load, "check": timing.check,
199            "bind": timing.bind, "evaluate": timing.evaluate, "total": timing.total},
200        "phase_order": PHASES, "boundaries": boundaries,
201        "gc": gc, "evaluation": evaluation,
202        "wall_clock": "CLOCK_MONOTONIC; first sample defines boundary",
203        "cpu_clock": "CLOCK_PROCESS_CPUTIME_ID; process user+system across threads",
204        "ownership": "Normal request Edits/output/Run release, then Session release; no explicit collection; scalar metrics emitted afterwards",
205        "limits": "Instrumented initial request only; Run.timing.bind is closure/setup, actual binding is inside evaluation round spans; not native paired timing",
206    });
207    let text = format!("{}\n", serde_json::to_string(&row).unwrap());
208    write_new(Path::new(&metrics_file), text.as_bytes());
209    print!("{text}");
210}

Auto Trait Implementations§

§

impl !Freeze for Engine

§

impl !RefUnwindSafe for Engine

§

impl !Send for Engine

§

impl !Sync for Engine

§

impl !UnwindSafe for Engine

§

impl Forget for Engine

§

impl Move for Engine

§

impl Unpin for Engine

§

impl UnsafeUnpin for Engine

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.