Skip to main content

decl_lang/
expression_diagnostics.rs

1//! Bounded, source-selected comprehension observations for diagnostic builds.
2//! Records contain scalars only. Inclusive nested intervals are not additive;
3//! returned lazy heads can be forced after the recorded expression has ended.
4use crate::ast::{self, DeclBody, Expr, Loc};
5use crate::module::Module;
6use crate::semantics::{Fail, R};
7use serde::Serialize;
8use std::cell::{Cell, RefCell};
9use std::marker::PhantomData;
10use std::rc::{Rc, Weak};
11
12/// Maximum registered syntax sites on one evaluation thread.
13pub const MAX_SITES: usize = 2;
14/// Maximum clauses counted separately in one selected comprehension.
15pub const MAX_CLAUSES: usize = 8;
16/// Maximum retained completed attempts; overflow invalidates attribution.
17pub const MAX_RECORDS: usize = 4096;
18const MAX_DEPTH: usize = 64;
19
20#[derive(Clone, Copy, Default, Serialize)]
21struct Stamp {
22    wall_ns: Option<u64>,
23    cpu_ns: Option<u64>,
24    sampled_until_ns: Option<u64>,
25    errno: [i32; 3],
26    allocation: crate::allocation_diagnostics::Snapshot,
27}
28fn clock(id: libc::clockid_t) -> (Option<u64>, i32) {
29    let mut ts = libc::timespec {
30        tv_sec: 0,
31        tv_nsec: 0,
32    };
33    // SAFETY: the initialized timespec is writable and no pointer escapes.
34    if unsafe { libc::clock_gettime(id, &mut ts) } != 0 {
35        return (
36            None,
37            std::io::Error::last_os_error().raw_os_error().unwrap_or(-1),
38        );
39    }
40    if ts.tv_sec < 0 || !(0..1_000_000_000).contains(&ts.tv_nsec) {
41        return (None, libc::EOVERFLOW);
42    }
43    let value = (ts.tv_sec as u64)
44        .checked_mul(1_000_000_000)
45        .and_then(|n| n.checked_add(ts.tv_nsec as u64));
46    (value, if value.is_some() { 0 } else { libc::EOVERFLOW })
47}
48impl Stamp {
49    fn now() -> Self {
50        let (wall_ns, a) = clock(libc::CLOCK_MONOTONIC);
51        let (cpu_ns, b) = clock(libc::CLOCK_PROCESS_CPUTIME_ID);
52        let (sampled_until_ns, c) = clock(libc::CLOCK_MONOTONIC);
53        Self {
54            wall_ns,
55            cpu_ns,
56            sampled_until_ns,
57            errno: [a, b, c],
58            allocation: crate::allocation_diagnostics::snapshot(),
59        }
60    }
61    fn valid(self) -> bool {
62        self.errno == [0; 3]
63            && self.wall_ns.is_some()
64            && self.cpu_ns.is_some()
65            && self.sampled_until_ns >= self.wall_ns
66    }
67}
68
69#[derive(Clone, Copy, Default, Serialize)]
70struct Work {
71    // Columns: iterator attempts, visited items, filter attempts, false filters,
72    // candidates passing every filter. A failed filter increments attempts only.
73    clauses: [[u64; 5]; MAX_CLAUSES],
74    emitted_heads: u64,
75    values_attempts: u64,
76    values_returns: u64,
77    values_items: u64,
78    values_capacity: u64,
79}
80#[derive(Clone, Copy, Serialize)]
81#[serde(rename_all = "snake_case")]
82enum Outcome {
83    Ok,
84    Defer,
85    EvalError,
86    Taint,
87    Unwound,
88    Incomplete,
89}
90#[derive(Serialize)]
91struct Record {
92    id: u64,
93    parent_id: Option<u64>,
94    site_id: u8,
95    compiled: bool,
96    engine_phase: u8,
97    start: Stamp,
98    end: Stamp,
99    outcome: Outcome,
100    work: Work,
101}
102#[derive(Serialize)]
103struct Site {
104    site_id: u8,
105    module: String,
106    location: [usize; 4],
107    clause_count: usize,
108    compiled_programs: u64,
109    #[serde(skip)]
110    expression: Weak<Expr>,
111}
112
113/// Scalar report drained after the measured worker's runtime owners are released.
114/// `valid` covers bookkeeping/clocks, not source quality, output or performance.
115#[derive(Serialize)]
116pub struct Report {
117    schema: u8,
118    clause_columns: [&'static str; 5],
119    values_counter_scope: &'static str,
120    generation: u64,
121    valid: bool,
122    max_records: usize,
123    record_capacity_bytes: usize,
124    frame_capacity_bytes: usize,
125    attempts: u64,
126    dropped_records: u64,
127    maximum_depth: usize,
128    open_attempts: usize,
129    counter_overflow: bool,
130    clock_failure: bool,
131    stack_failure: bool,
132    sites: Vec<Site>,
133    records: Vec<Record>,
134}
135struct State {
136    report: Report,
137    frames: Vec<Record>,
138}
139thread_local! {
140    static STATE: RefCell<Option<State>> = const { RefCell::new(None) };
141    static GENERATION: Cell<u64> = const { Cell::new(0) };
142}
143
144/// Installation guard. Closing removes the thread-local state before dropping it.
145/// Old attempt/program tokens cannot write into a later installation.
146/// The guard must be finished or dropped on its installing thread.
147pub struct SessionGuard {
148    generation: u64,
149    closed: bool,
150    thread: PhantomData<Rc<()>>,
151}
152
153/// Install a fresh bounded buffer before the measured timeline starts.
154/// Nested installation and capacities outside `1..=MAX_RECORDS` are rejected.
155pub fn install(max_records: usize) -> Result<SessionGuard, &'static str> {
156    if !(1..=MAX_RECORDS).contains(&max_records) {
157        return Err("invalid expression record limit");
158    }
159    STATE.with(|state| {
160        if state.borrow().is_some() { return Err("expression diagnostics already installed"); }
161        let generation = GENERATION.with(|g| {
162            let next = g.get().checked_add(1).ok_or("expression generation exhausted")?;
163            g.set(next); Ok::<u64, &'static str>(next)
164        })?;
165        let records = Vec::with_capacity(max_records);
166        let frames = Vec::with_capacity(MAX_DEPTH);
167        let report = Report { schema: 1,
168            clause_columns: ["iterator_attempts", "visited_items", "filter_attempts", "false_filters", "passed_candidates"],
169            values_counter_scope: "Nearest active watched attempt only; excludes nested watched attempts. Clock/allocation intervals are inclusive.",
170            generation, valid: true, max_records,
171            record_capacity_bytes: records.capacity() * std::mem::size_of::<Record>(),
172            frame_capacity_bytes: frames.capacity() * std::mem::size_of::<Record>(),
173            attempts: 0, dropped_records: 0, maximum_depth: 0, open_attempts: 0,
174            counter_overflow: false, clock_failure: false, stack_failure: false,
175            sites: Vec::with_capacity(MAX_SITES), records };
176        *state.borrow_mut() = Some(State { report, frames });
177        Ok(SessionGuard { generation, closed: false, thread: PhantomData })
178    })
179}
180impl SessionGuard {
181    /// Close this installation and return its records, with no runtime owners.
182    /// Open attempts invalidate the report; later stale guard drops are inert.
183    pub fn finish(mut self) -> Report {
184        self.closed = true;
185        let mut state = STATE
186            .with(|s| s.borrow_mut().take())
187            .expect("installed expression session");
188        debug_assert_eq!(state.report.generation, self.generation);
189        state.report.open_attempts = state.frames.len();
190        state.report.valid &= state.frames.is_empty();
191        state.report
192    }
193}
194impl Drop for SessionGuard {
195    fn drop(&mut self) {
196        if !self.closed {
197            let old = STATE
198                .try_with(|s| {
199                    let mut s = s.borrow_mut();
200                    if s.as_ref()
201                        .is_some_and(|s| s.report.generation == self.generation)
202                    {
203                        s.take()
204                    } else {
205                        None
206                    }
207                })
208                .ok()
209                .flatten();
210            drop(old);
211        }
212    }
213}
214
215/// Register one Comp selected by its loaded module and zero-based start line.
216/// Resolution must be unique, with the requested clause count. Full source
217/// coordinates are saved; the caller binds module bytes in its frozen manifest.
218/// Registration is allowed only before this installation's first attempt.
219pub fn register(
220    module: &Module,
221    site_id: u8,
222    start_line: usize,
223    clauses: usize,
224) -> Result<(), &'static str> {
225    if site_id as usize >= MAX_SITES || !(1..=MAX_CLAUSES).contains(&clauses) {
226        return Err("invalid expression site or clause count");
227    }
228    let path = module.path.to_str().ok_or("non-UTF8 expression module")?;
229    if path.len() > 4096 {
230        return Err("expression module path too long");
231    }
232    let mut found: Option<(Weak<Expr>, Loc)> = None;
233    let mut ambiguous = false;
234    let mut visit = |e: &Rc<Expr>| {
235        if let (Expr::Comp { clauses: cs, .. }, Some(loc)) = (&**e, ast::expr_loc(e)) {
236            if loc.sl == start_line && cs.len() == clauses {
237                if found
238                    .as_ref()
239                    .is_some_and(|(w, _)| w.as_ptr() != Rc::as_ptr(e))
240                {
241                    ambiguous = true;
242                }
243                found = Some((Rc::downgrade(e), loc));
244            }
245        }
246    };
247    for d in &module.decls {
248        match &d.body {
249            DeclBody::Type { ty, .. } | DeclBody::Input { ty, .. } => {
250                ast::walk_type_exprs(ty, true, &mut visit)
251            }
252            DeclBody::Const { ty, expr, .. } => {
253                if let Some(ty) = ty {
254                    ast::walk_type_exprs(ty, true, &mut visit);
255                }
256                ast::walk_expr_tree(expr, true, &mut visit);
257            }
258            DeclBody::Output { ty, expr, .. } => {
259                ast::walk_type_exprs(ty, true, &mut visit);
260                ast::walk_expr_tree(expr, true, &mut visit);
261            }
262            DeclBody::Func { body, .. } => ast::walk_expr_tree(body, true, &mut visit),
263            _ => {}
264        }
265    }
266    if ambiguous {
267        return Err("ambiguous expression selector");
268    }
269    let (expression, loc) = found.ok_or("expression selector not found")?;
270    let site = Site {
271        site_id,
272        module: path.to_owned(),
273        location: [loc.sl, loc.sc, loc.el, loc.ec],
274        clause_count: clauses,
275        compiled_programs: 0,
276        expression,
277    };
278    STATE.with(|s| {
279        let mut s = s.borrow_mut();
280        let s = s.as_mut().ok_or("expression diagnostics not installed")?;
281        if s.report.attempts != 0
282            || s.report.sites.len() == MAX_SITES
283            || s.report
284                .sites
285                .iter()
286                .any(|x| x.site_id == site_id || x.expression.as_ptr() == site.expression.as_ptr())
287        {
288            return Err("duplicate or late expression registration");
289        }
290        s.report.sites.push(site);
291        Ok(())
292    })
293}
294
295#[derive(Clone, Copy)]
296pub(crate) struct Token {
297    generation: u64,
298    site_id: u8,
299    compiled: bool,
300}
301pub(crate) fn selected(e: &Rc<Expr>, compiled: bool) -> Option<Token> {
302    STATE
303        .try_with(|s| {
304            let mut s = s.borrow_mut();
305            let s = s.as_mut()?;
306            let site = s
307                .report
308                .sites
309                .iter_mut()
310                .find(|x| x.expression.as_ptr() == Rc::as_ptr(e))?;
311            let overflow = compiled && add(&mut site.compiled_programs, 1);
312            let site_id = site.site_id;
313            if overflow {
314                s.report.valid = false;
315                s.report.counter_overflow = true;
316            }
317            Some(Token {
318                generation: s.report.generation,
319                site_id,
320                compiled,
321            })
322        })
323        .ok()
324        .flatten()
325}
326#[derive(Clone, Copy)]
327pub(crate) struct Handle {
328    generation: u64,
329    id: u64,
330}
331pub(crate) struct Attempt {
332    handle: Option<Handle>,
333    done: bool,
334}
335impl Attempt {
336    pub(crate) fn begin(token: Option<Token>, phase: u8) -> Self {
337        let handle = token.and_then(|token| {
338            STATE
339                .try_with(|s| {
340                    let mut s = s.borrow_mut();
341                    let s = s.as_mut()?;
342                    if token.generation != s.report.generation {
343                        return None;
344                    }
345                    if s.frames.len() == MAX_DEPTH || s.report.attempts == u64::MAX {
346                        s.report.valid = false;
347                        s.report.stack_failure = true;
348                        return None;
349                    }
350                    s.report.attempts += 1;
351                    let id = s.report.attempts;
352                    let parent_id = s.frames.last().map(|r| r.id);
353                    let start = Stamp::now();
354                    s.frames.push(Record {
355                        id,
356                        parent_id,
357                        site_id: token.site_id,
358                        compiled: token.compiled,
359                        engine_phase: phase,
360                        start,
361                        end: start,
362                        outcome: Outcome::Incomplete,
363                        work: Work::default(),
364                    });
365                    s.report.maximum_depth = s.report.maximum_depth.max(s.frames.len());
366                    Some(Handle {
367                        generation: token.generation,
368                        id,
369                    })
370                })
371                .ok()
372                .flatten()
373        });
374        Self {
375            handle,
376            done: false,
377        }
378    }
379    pub(crate) fn handle(&self) -> Option<Handle> {
380        self.handle
381    }
382    pub(crate) fn finish<T>(&mut self, result: &R<T>) {
383        let outcome = match result {
384            Ok(_) => Outcome::Ok,
385            Err(Fail::Defer) => Outcome::Defer,
386            Err(Fail::Eval(_)) => Outcome::EvalError,
387            Err(Fail::Taint) => Outcome::Taint,
388        };
389        self.close(outcome);
390    }
391    fn close(&mut self, outcome: Outcome) {
392        if self.done {
393            return;
394        }
395        self.done = true;
396        let Some(h) = self.handle else {
397            return;
398        };
399        let end = Stamp::now();
400        let _ = STATE.try_with(|s| {
401            let mut s = s.borrow_mut();
402            let Some(s) = s.as_mut() else {
403                return;
404            };
405            if s.report.generation != h.generation {
406                return;
407            }
408            if s.frames.last().map(|r| r.id) != Some(h.id) {
409                s.report.valid = false;
410                s.report.stack_failure = true;
411                return;
412            }
413            let mut record = s.frames.pop().unwrap();
414            record.end = end;
415            record.outcome = outcome;
416            if !record.start.valid()
417                || !end.valid()
418                || end.wall_ns < record.start.sampled_until_ns
419                || end.cpu_ns < record.start.cpu_ns
420            {
421                s.report.valid = false;
422                s.report.clock_failure = true;
423            }
424            if s.report.records.len() == s.report.max_records {
425                s.report.valid = false;
426                s.report.dropped_records = s.report.dropped_records.saturating_add(1);
427            } else {
428                s.report.records.push(record);
429            }
430        });
431    }
432}
433impl Drop for Attempt {
434    fn drop(&mut self) {
435        self.close(if std::thread::panicking() {
436            Outcome::Unwound
437        } else {
438            Outcome::Incomplete
439        });
440    }
441}
442fn add(target: &mut u64, n: u64) -> bool {
443    let (value, overflow) = target.overflowing_add(n);
444    *target = if overflow { u64::MAX } else { value };
445    overflow
446}
447fn update(handle: Option<Handle>, f: impl FnOnce(&mut Work) -> bool) {
448    let _ = STATE.try_with(|s| {
449        let mut s = s.borrow_mut();
450        let Some(s) = s.as_mut() else {
451            return;
452        };
453        let record = match handle {
454            Some(h) if h.generation == s.report.generation => {
455                s.frames.iter_mut().rev().find(|r| r.id == h.id)
456            }
457            Some(_) => None,
458            None => s.frames.last_mut(),
459        };
460        if record.is_some_and(|r| f(&mut r.work)) {
461            s.report.valid = false;
462            s.report.counter_overflow = true;
463        }
464    });
465}
466pub(crate) fn clause(handle: Option<Handle>, index: usize, column: usize) {
467    if let Some(h) = handle {
468        update(Some(h), |w| add(&mut w.clauses[index][column], 1));
469    }
470}
471pub(crate) fn emitted(handle: Option<Handle>) {
472    if let Some(h) = handle {
473        update(Some(h), |w| add(&mut w.emitted_heads, 1));
474    }
475}
476pub(crate) fn values_attempt() {
477    update(None, |w| add(&mut w.values_attempts, 1));
478}
479pub(crate) fn values_return(items: usize, capacity: usize) {
480    update(None, |w| {
481        let a = add(&mut w.values_returns, 1);
482        let b = add(&mut w.values_items, items as u64);
483        let c = add(&mut w.values_capacity, capacity as u64);
484        a || b || c
485    });
486}
487
488#[cfg(test)]
489#[path = "../tests/private/expression_diagnostics_test.rs"]
490mod tests;