Skip to main content

Session

Struct Session 

Source
pub struct Session {
    pub entry_path: Option<PathBuf>,
    pub log: Vec<Op>,
    pub cursor: usize,
    pub last_timing: Cell<Option<Timing>>,
    pub full_recompute: bool,
    pub overlay: HashMap<PathBuf, String>,
    /* private fields */
}
Expand description

the session: the universe of an entry module, the documents bound, the session’s declarations, and the log of operations with its cursor

Fields§

§entry_path: Option<PathBuf>

the entry module, absolute

§log: Vec<Op>

the operations applied, in order

§cursor: usize

how many of them are in force (undo moves it back)

§last_timing: Cell<Option<Timing>>

the last run’s timing

§full_recompute: bool

Disable retained document queries for this Session (a fresh-evaluation oracle).

§overlay: HashMap<PathBuf, String>

texts that override the disk (the language server’s open buffers), by absolute path

Implementations§

Source§

impl Session

Source

pub fn new(entry: Option<&str>) -> Session

A session over an entry module (none: a scratch session).

Examples found in repository?
examples/serialization_census.rs (line 38)
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 (line 94)
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}
Source

pub fn with_overlay( entry: Option<&str>, overlay: Option<&HashMap<PathBuf, String>>, ) -> Session

overlay: texts that override the disk (the language server’s open buffers), by absolute path

Source

pub fn entry_abs(&self) -> PathBuf

The entry module’s absolute path.

Source

pub fn entry_name(&self) -> String

The entry module’s file name, as :roots shows it.

Source

pub fn apply(&mut self, op: Op) -> SResult<()>

Apply an operation and log it; a refused operation is an error and is not logged. An operation after undo discards what was undone.

Examples found in repository?
examples/serialization_census.rs (lines 40-45)
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 96-101)
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}
Source

pub fn undo(&mut self, n: usize) -> usize

Step back n operations; returns how many were undone.

Source

pub fn redo(&mut self, n: usize) -> usize

Step forward n operations; returns how many were redone.

Source

pub fn reload_op(&self) -> Op

The reload operation for the universe as it is on disk now.

Source

pub fn run(&self, mode: Mode) -> Run

load, check, and (unless mode says otherwise) evaluate the state

Examples found in repository?
examples/serialization_census.rs (line 58)
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 (line 104)
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}
Source

pub fn evaluate_expr(&self, text: &str) -> SResult<ExprResult>

partial evaluation of one expression (§2.1)

Source

pub fn roots(&self) -> Vec<RootInfo>

the roots of the universe and of the session (:roots)

Source

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

Every root’s name, the session’s included.

Source

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

Whether a root of that name exists.

Source

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

static diagnostics of every module, with the file each is reported against

Source

pub fn render( &self, run: &Run, name: &str, over: &RenderOverrides, ) -> Option<Rendered>

full evaluation of the named roots (:evaluate), or of the exported outputs a root in the form its module declares (docs/tooling/05_render.md §3, §8), with the overrides given: its text, or the files of a fan-out; None when nothing applies (canonical JSON, no override); an error as its diagnostic, with the template’s path when a template is at fault

Source

pub fn evaluate( &self, names: &[String], ) -> SResult<(Run, Vec<(String, Option<String>)>, bool)>

full evaluation of the named roots (:evaluate), or of the exported outputs: the run, each root’s document (None when invalid), and whether the exported outputs were asked for

Source

pub fn validate( &self, names: &[String], ) -> SResult<(Run, Vec<(String, usize, usize)>, Vec<Diag>)>

whole-document validation of the named roots (:validate), or of every root

Source

pub fn type_of(&self, text: &str) -> SResult<(String, bool, Vec<Diag>)>

the static type of an expression (:type)

Source

pub fn path_of(&self, text: &str) -> SResult<String>

the canonical path of the place a navigation names (:path)

Source

pub fn doc_of(&self, name: &str) -> SResult<Vec<String>>

the declaration a name resolves to, with its documentation (:doc)

Source

pub fn trace(&self, path_text: &str) -> SResult<Vec<String>>

the derivation of a valid place, or the root cause of an invalid one (:trace)

Source

pub fn complete(&self, text: &str, commands: &[&str]) -> Vec<String>

the candidates completion offers at the end of text (:complete)

Source

pub fn scratch_text(&self) -> String

The session’s declarations as a module’s text.

Source

pub fn module_text(&self) -> String

the scratch module as a file: imports of the entry’s exports it uses, then the declarations

Source

pub fn fmt(&self) -> SResult<String>

The scratch module, formatted.

Source

pub fn write(&self, file: &str) -> SResult<()>

Write the scratch module to a file.

Source

pub fn document_text(&self, name: &str) -> SResult<String>

A root’s document as JSON: the bound document, or the root evaluated.

Source

pub fn save(&self, name: &str, file: &str) -> SResult<()>

Save a root’s document to a file.

Source

pub fn diff(&self, name: &str) -> SResult<Vec<String>>

The lines of a document’s diff against what it started from.

Source

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

The session’s declarations and bindings, as :session prints them.

Source

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

The log with its cursor, as :history prints it.

Source

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

The log as a session script, replayable with --script.

Auto Trait Implementations§

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.