feat(tvix/eval): implement (compilation) observer trait r/4774

This trait will enable library users of tvix-eval to observe internal
happenings of the compilation and runtime processes.

The initial methods of the observer will be called whenever the
compiler emits a chunk.

Change-Id: I668f6c2cfe3d6f4c1a1612c0f293831011768437
Reviewed-on: https://cl.tvl.fyi/c/depot/+/6448
Reviewed-by: sterni <sternenseemann@systemli.org>
Tested-by: BuildkiteCI

2 files changed, 37 insertions, 0 deletions

diff --git a/tvix/eval/src/lib.rs b/tvix/eval/src/lib.rs
index 7156a03b6444..e088ef3ee4e3 100644
--- a/tvix/eval/src/lib.rs
+++ b/tvix/eval/src/lib.rs
@@ -3,6 +3,7 @@ mod chunk;
 mod compiler;
 mod errors;
 mod eval;
+mod observer;
 mod opcode;
 mod upvalues;
 mod value;
diff --git a/tvix/eval/src/observer.rs b/tvix/eval/src/observer.rs
new file mode 100644
index 000000000000..bf05295ac356
--- /dev/null
+++ b/tvix/eval/src/observer.rs
@@ -0,0 +1,36 @@
+//! Implements a trait for things that wish to observe internal state
+//! changes of tvix-eval.
+//!
+//! This can be used to gain insights from compilation, to trace the
+//! runtime, and so on.
+
+use crate::value::Lambda;
+
+use std::rc::Rc;
+
+/// Implemented by types that wish to observe internal happenings of
+/// Tvix.
+///
+/// All methods are optional, that is, observers can implement only
+/// what they are interested in observing.
+pub trait Observer {
+    /// Called when the compiler finishes compilation of the top-level
+    /// of an expression (usually the root Nix expression of a file).
+    fn observe_compiled_toplevel(&mut self, _: &Rc<Lambda>) {}
+
+    /// Called when the compiler finishes compilation of a
+    /// user-defined function.
+    ///
+    /// Note that in Nix there are only single argument functions, so
+    /// in an expression like `a: b: c: ...` this method will be
+    /// called three times.
+    fn observe_compiled_lambda(&mut self, _: &Rc<Lambda>) {}
+
+    /// Called when the compiler finishes compilation of a thunk.
+    fn observe_compiled_thunk(&mut self, _: &Rc<Lambda>) {}
+}
+
+#[derive(Default)]
+pub struct NoOpObserver {}
+
+impl Observer for NoOpObserver {}