Skip to main content

snix_eval/
observer.rs

1//! Implements traits for things that wish to observe internal state
2//! changes of snix-eval.
3//!
4//! This can be used to gain insights from compilation, to trace the
5//! runtime, and so on.
6//!
7//! All methods are optional, that is, observers can implement only
8/// what they are interested in observing.
9use std::io::Write;
10use std::rc::Rc;
11use std::time::Instant;
12use tabwriter::TabWriter;
13
14use crate::SourceCode;
15use crate::Value;
16use crate::chunk::Chunk;
17use crate::generators::VMRequest;
18use crate::opcode::{CodeIdx, Op};
19use crate::value::Lambda;
20
21/// Implemented by types that wish to observe internal happenings of
22/// the Snix compiler.
23pub trait CompilerObserver {
24    /// Called when the compiler finishes compilation of the top-level
25    /// of an expression (usually the root Nix expression of a file).
26    fn observe_compiled_toplevel(&mut self, _: &Rc<Lambda>) {}
27
28    /// Called when the compiler finishes compilation of a
29    /// user-defined function.
30    ///
31    /// Note that in Nix there are only single argument functions, so
32    /// in an expression like `a: b: c: ...` this method will be
33    /// called three times.
34    fn observe_compiled_lambda(&mut self, _: &Rc<Lambda>) {}
35
36    /// Called when the compiler finishes compilation of a thunk.
37    fn observe_compiled_thunk(&mut self, _: &Rc<Lambda>) {}
38}
39
40/// Implemented by types that wish to observe internal happenings of
41/// the Snix virtual machine at runtime.
42pub trait RuntimeObserver {
43    /// Called when the runtime enters a new bytecode frame.
44    fn observe_enter_bytecode_frame(
45        &mut self,
46        _arg_count: usize,
47        _: &Rc<Lambda>,
48        _call_depth: usize,
49    ) {
50    }
51
52    /// Called when the runtime exits a bytecode frame.
53    fn observe_exit_bytecode_frame(&mut self, _frame_at: usize, _stack: &[Value]) {}
54
55    /// Called when the runtime suspends a bytecode frame.
56    fn observe_suspend_bytecode_frame(&mut self, _frame_at: usize, _stack: &[Value]) {}
57
58    /// Called when the runtime enters a generator frame.
59    fn observe_enter_generator(&mut self, _frame_at: usize, _name: &str, _stack: &[Value]) {}
60
61    /// Called when the runtime exits a generator frame.
62    fn observe_exit_generator(&mut self, _frame_at: usize, _name: &str, _stack: &[Value]) {}
63
64    /// Called when the runtime suspends a generator frame.
65    fn observe_suspend_generator(&mut self, _frame_at: usize, _name: &str, _stack: &[Value]) {}
66
67    /// Called when a generator requests an action from the VM.
68    fn observe_generator_request(&mut self, _name: &str, _msg: &VMRequest) {}
69
70    /// Called when the runtime replaces the current bytecode frame for a
71    /// tail call.
72    fn observe_tail_call(&mut self, _frame_at: usize, _: &Rc<Lambda>) {}
73
74    /// Called when the runtime enters a builtin.
75    fn observe_enter_builtin(&mut self, _name: &'static str) {}
76
77    /// Called when the runtime exits a builtin.
78    fn observe_exit_builtin(&mut self, _name: &'static str, _stack: &[Value]) {}
79
80    /// Called when the runtime *begins* executing an instruction. The
81    /// provided stack is the state at the beginning of the operation.
82    fn observe_execute_op(&mut self, _ip: CodeIdx, _: &Op, _: &[Value]) {}
83}
84
85#[derive(Default)]
86pub struct NoOpObserver {}
87
88impl CompilerObserver for NoOpObserver {}
89impl RuntimeObserver for NoOpObserver {}
90
91/// Compiler observer that is optimised for the case where no observer is being used.
92///
93/// The trait [CompilerObserver] is implemented on `Option<dyn CompilerObserver>`.
94/// This removes the dynamic dispatch overhead when no observer is being used.
95#[derive(Default)]
96pub struct OptionalCompilerObserver<'o>(pub Option<&'o mut dyn CompilerObserver>);
97impl<'o> CompilerObserver for OptionalCompilerObserver<'o> {
98    fn observe_compiled_toplevel(&mut self, lambda: &Rc<Lambda>) {
99        if let Some(ref mut obs) = self.0 {
100            obs.observe_compiled_toplevel(lambda);
101        }
102    }
103
104    fn observe_compiled_lambda(&mut self, lambda: &Rc<Lambda>) {
105        if let Some(ref mut obs) = self.0 {
106            obs.observe_compiled_lambda(lambda);
107        }
108    }
109
110    fn observe_compiled_thunk(&mut self, lambda: &Rc<Lambda>) {
111        if let Some(ref mut obs) = self.0 {
112            obs.observe_compiled_thunk(lambda)
113        }
114    }
115}
116
117impl<'o> From<&'o mut dyn CompilerObserver> for OptionalCompilerObserver<'o> {
118    fn from(val: &'o mut dyn CompilerObserver) -> Self {
119        OptionalCompilerObserver(Some(val))
120    }
121}
122
123impl<'o> From<Option<&'o mut dyn CompilerObserver>> for OptionalCompilerObserver<'o> {
124    fn from(val: Option<&'o mut dyn CompilerObserver>) -> Self {
125        Self(val)
126    }
127}
128
129/// Runtime observer that is optimised for the case where no observer is being used.
130///
131/// The trait [RuntimeObserver] is implemented on `Option<dyn RuntimeObserver>`.
132/// This removes the dynamic dispatch overhead when no observer is being used.
133pub struct OptionalRuntimeObserver<'o>(pub Option<&'o mut dyn RuntimeObserver>);
134
135impl<'o> From<&'o mut dyn RuntimeObserver> for OptionalRuntimeObserver<'o> {
136    fn from(val: &'o mut dyn RuntimeObserver) -> Self {
137        OptionalRuntimeObserver(Some(val))
138    }
139}
140
141impl<'o> RuntimeObserver for OptionalRuntimeObserver<'o> {
142    #[inline(always)]
143    fn observe_enter_bytecode_frame(
144        &mut self,
145        arg_count: usize,
146        lambda: &Rc<Lambda>,
147        call_depth: usize,
148    ) {
149        if let Some(ref mut obs) = self.0 {
150            obs.observe_enter_bytecode_frame(arg_count, lambda, call_depth);
151        }
152    }
153
154    #[inline(always)]
155    fn observe_exit_bytecode_frame(&mut self, frame_at: usize, stack: &[Value]) {
156        if let Some(ref mut obs) = self.0 {
157            obs.observe_exit_bytecode_frame(frame_at, stack);
158        }
159    }
160
161    #[inline(always)]
162    fn observe_suspend_bytecode_frame(&mut self, frame_at: usize, stack: &[Value]) {
163        if let Some(ref mut obs) = self.0 {
164            obs.observe_suspend_bytecode_frame(frame_at, stack);
165        }
166    }
167
168    #[inline(always)]
169    fn observe_enter_generator(&mut self, frame_at: usize, name: &str, stack: &[Value]) {
170        if let Some(ref mut obs) = self.0 {
171            obs.observe_enter_generator(frame_at, name, stack);
172        }
173    }
174
175    #[inline(always)]
176    fn observe_exit_generator(&mut self, frame_at: usize, name: &str, stack: &[Value]) {
177        if let Some(ref mut obs) = self.0 {
178            obs.observe_exit_generator(frame_at, name, stack);
179        }
180    }
181
182    #[inline(always)]
183    fn observe_suspend_generator(&mut self, frame_at: usize, name: &str, stack: &[Value]) {
184        if let Some(ref mut obs) = self.0 {
185            obs.observe_suspend_generator(frame_at, name, stack);
186        }
187    }
188
189    #[inline(always)]
190    fn observe_generator_request(&mut self, name: &str, msg: &VMRequest) {
191        if let Some(ref mut obs) = self.0 {
192            obs.observe_generator_request(name, msg);
193        }
194    }
195
196    #[inline(always)]
197    fn observe_tail_call(&mut self, frame_at: usize, lambda: &Rc<Lambda>) {
198        if let Some(ref mut obs) = self.0 {
199            obs.observe_tail_call(frame_at, lambda);
200        }
201    }
202
203    #[inline(always)]
204    fn observe_enter_builtin(&mut self, name: &'static str) {
205        if let Some(ref mut obs) = self.0 {
206            obs.observe_enter_builtin(name);
207        }
208    }
209
210    #[inline(always)]
211    fn observe_exit_builtin(&mut self, name: &'static str, stack: &[Value]) {
212        if let Some(ref mut obs) = self.0 {
213            obs.observe_exit_builtin(name, stack);
214        }
215    }
216
217    #[inline(always)]
218    fn observe_execute_op(&mut self, ip: CodeIdx, op: &Op, stack: &[Value]) {
219        if let Some(ref mut obs) = self.0 {
220            obs.observe_execute_op(ip, op, stack);
221        }
222    }
223}
224
225/// An observer that prints disassembled chunk information to its
226/// internal writer whenwever the compiler emits a toplevel function,
227/// closure or thunk.
228pub struct DisassemblingObserver<W: Write> {
229    source: SourceCode,
230    writer: TabWriter<W>,
231}
232
233impl<W: Write> DisassemblingObserver<W> {
234    pub fn new(source: SourceCode, writer: W) -> Self {
235        Self {
236            source,
237            writer: TabWriter::new(writer),
238        }
239    }
240
241    fn lambda_header(&mut self, kind: &str, lambda: &Rc<Lambda>) {
242        let _ = writeln!(
243            &mut self.writer,
244            "=== compiled {} @ {:p} ({} ops, {} length) ===",
245            kind,
246            *lambda,
247            lambda.chunk.op_count(),
248            lambda.chunk.code.len(),
249        );
250    }
251
252    fn disassemble_chunk(&mut self, chunk: &Chunk) {
253        // calculate width of the widest address in the chunk
254        let width = format!("{:#x}", chunk.code.len() - 1).len();
255
256        let mut idx = 0;
257        while idx < chunk.code.len() {
258            let size = chunk
259                .disassemble_op(&mut self.writer, &self.source, width, CodeIdx(idx))
260                .expect("writing debug output should work");
261            idx += size;
262        }
263    }
264}
265
266impl<W: Write> CompilerObserver for DisassemblingObserver<W> {
267    fn observe_compiled_toplevel(&mut self, lambda: &Rc<Lambda>) {
268        self.lambda_header("toplevel", lambda);
269        self.disassemble_chunk(&lambda.chunk);
270        let _ = self.writer.flush();
271    }
272
273    fn observe_compiled_lambda(&mut self, lambda: &Rc<Lambda>) {
274        self.lambda_header("lambda", lambda);
275        self.disassemble_chunk(&lambda.chunk);
276        let _ = self.writer.flush();
277    }
278
279    fn observe_compiled_thunk(&mut self, lambda: &Rc<Lambda>) {
280        self.lambda_header("thunk", lambda);
281        self.disassemble_chunk(&lambda.chunk);
282        let _ = self.writer.flush();
283    }
284}
285
286/// An observer that collects a textual representation of an entire
287/// runtime execution.
288pub struct TracingObserver<W: Write> {
289    // If timing is enabled, contains the timestamp of the last-emitted trace event
290    last_event: Option<Instant>,
291    writer: TabWriter<W>,
292}
293
294impl<W: Write> TracingObserver<W> {
295    pub fn new(writer: W) -> Self {
296        Self {
297            last_event: None,
298            writer: TabWriter::new(writer),
299        }
300    }
301
302    /// Write the time of each runtime event, relative to when this method is called
303    pub fn enable_timing(&mut self) {
304        self.last_event = Some(Instant::now());
305    }
306
307    fn maybe_write_time(&mut self) {
308        if let Some(last_event) = &mut self.last_event {
309            let _ = write!(&mut self.writer, "+{}ns\t", last_event.elapsed().as_nanos());
310            *last_event = Instant::now();
311        }
312    }
313
314    fn write_value(&mut self, val: &Value) {
315        let _ = match val {
316            // Potentially large types which we only want to print
317            // the type of (and avoid recursing).
318            Value::List(l) => write!(&mut self.writer, "list[{}] ", l.len()),
319            Value::Attrs(a) => write!(&mut self.writer, "attrs[{}] ", a.len()),
320            Value::Thunk(t) if t.is_evaluated() => {
321                self.write_value(&t.value());
322                Ok(())
323            }
324
325            // For other value types, defer to the standard value printer.
326            _ => write!(&mut self.writer, "{val} "),
327        };
328    }
329
330    fn write_stack(&mut self, stack: &[Value]) {
331        let _ = write!(&mut self.writer, "[ ");
332
333        // Print out a maximum of 6 values from the top of the stack,
334        // before abbreviating it to `...`.
335        for (i, val) in stack.iter().rev().enumerate() {
336            if i == 6 {
337                let _ = write!(&mut self.writer, "...");
338                break;
339            }
340
341            self.write_value(val);
342        }
343
344        let _ = writeln!(&mut self.writer, "]");
345    }
346}
347
348impl<W: Write> RuntimeObserver for TracingObserver<W> {
349    fn observe_enter_bytecode_frame(
350        &mut self,
351        arg_count: usize,
352        lambda: &Rc<Lambda>,
353        call_depth: usize,
354    ) {
355        self.maybe_write_time();
356
357        let _ = write!(&mut self.writer, "=== entering ");
358
359        let _ = if arg_count == 0 {
360            write!(&mut self.writer, "thunk ")
361        } else {
362            write!(&mut self.writer, "closure ")
363        };
364
365        if let Some(name) = &lambda.name {
366            let _ = write!(&mut self.writer, "'{name}' ");
367        }
368
369        let _ = writeln!(
370            &mut self.writer,
371            "in frame[{}] @ {:p} ===",
372            call_depth, *lambda
373        );
374    }
375
376    /// Called when the runtime exits a bytecode frame.
377    fn observe_exit_bytecode_frame(&mut self, frame_at: usize, stack: &[Value]) {
378        self.maybe_write_time();
379        let _ = write!(&mut self.writer, "=== exiting frame {frame_at} ===\t ");
380        self.write_stack(stack);
381    }
382
383    fn observe_suspend_bytecode_frame(&mut self, frame_at: usize, stack: &[Value]) {
384        self.maybe_write_time();
385        let _ = write!(&mut self.writer, "=== suspending frame {frame_at} ===\t");
386
387        self.write_stack(stack);
388    }
389
390    fn observe_enter_generator(&mut self, frame_at: usize, name: &str, stack: &[Value]) {
391        self.maybe_write_time();
392        let _ = write!(
393            &mut self.writer,
394            "=== entering generator frame '{name}' [{frame_at}] ===\t",
395        );
396
397        self.write_stack(stack);
398    }
399
400    fn observe_exit_generator(&mut self, frame_at: usize, name: &str, stack: &[Value]) {
401        self.maybe_write_time();
402        let _ = write!(
403            &mut self.writer,
404            "=== exiting generator '{name}' [{frame_at}] ===\t"
405        );
406
407        self.write_stack(stack);
408    }
409
410    fn observe_suspend_generator(&mut self, frame_at: usize, name: &str, stack: &[Value]) {
411        self.maybe_write_time();
412        let _ = write!(
413            &mut self.writer,
414            "=== suspending generator '{name}' [{frame_at}] ===\t"
415        );
416
417        self.write_stack(stack);
418    }
419
420    fn observe_generator_request(&mut self, name: &str, msg: &VMRequest) {
421        self.maybe_write_time();
422        let _ = writeln!(
423            &mut self.writer,
424            "=== generator '{name}' requested {msg} ==="
425        );
426    }
427
428    fn observe_enter_builtin(&mut self, name: &'static str) {
429        self.maybe_write_time();
430        let _ = writeln!(&mut self.writer, "=== entering builtin {name} ===");
431    }
432
433    fn observe_exit_builtin(&mut self, name: &'static str, stack: &[Value]) {
434        self.maybe_write_time();
435        let _ = write!(&mut self.writer, "=== exiting builtin {name} ===\t");
436        self.write_stack(stack);
437    }
438
439    fn observe_tail_call(&mut self, frame_at: usize, lambda: &Rc<Lambda>) {
440        self.maybe_write_time();
441        let _ = writeln!(
442            &mut self.writer,
443            "=== tail-calling {:p} in frame[{}] ===",
444            *lambda, frame_at
445        );
446    }
447
448    fn observe_execute_op(&mut self, ip: CodeIdx, op: &Op, stack: &[Value]) {
449        self.maybe_write_time();
450        let _ = write!(&mut self.writer, "{:04} {:?}\t", ip.0, op);
451        self.write_stack(stack);
452    }
453}
454
455impl<W: Write> Drop for TracingObserver<W> {
456    fn drop(&mut self) {
457        let _ = self.writer.flush();
458    }
459}