bit_machine: replace ExecTracker API with a much more general one

This replaces the `ExecTracker` API with one which is able to detect
every node, not just cases and jets; which is able to read the input
value for every node (as a bit iterator which can be converted to a
value with Value::from_padded_bits) and the output value for terminal
nodes; and which can do all the existing things that the tracker can
do.

I suspect we want to add some examples or unit tests, in particular
around "debug nodes".

Fixes #324

Author: apoelstra

src/bit_machine/frame.rs

@@ -43,6 +43,19 @@ impl Frame {
         self.len
     }
 
+    /// Makes a copy of the frame.
+    ///
+    /// This copies *only the indices* and none of the underlying
+    /// data. It is the caller's responsibility to make sure that
+    /// the indices are not invalidated.
+    pub(super) fn shallow_copy(&self) -> Self {
+        Self {
+            cursor: self.cursor,
+            start: self.start,
+            len: self.len,
+        }
+    }
+
     /// Reset the cursor to the start.
     pub(super) fn reset_cursor(&mut self) {
         self.cursor = self.start;

src/bit_machine/mod.rs

@@ -271,6 +271,9 @@ impl BitMachine {
         }
 
         'main_loop: loop {
+            // Make a copy of the input frame to give to the tracker.
+            let input_frame = self.read.last().map(Frame::shallow_copy);
+
             match ip.inner() {
                 node::Inner::Unit => {}
                 node::Inner::Iden => {
@@ -336,32 +339,18 @@ impl BitMachine {
                     let (sum_a_b, _c) = ip.arrow().source.as_product().unwrap();
                     let (a, b) = sum_a_b.as_sum().unwrap();
 
-                    if tracker.is_track_debug_enabled() {
-                        if let node::Inner::AssertL(_, cmr) = ip.inner() {
-                            let mut bits = in_frame.as_bit_iter(&self.data);
-                            // Skips 1 + max(a.bit_width, b.bit_width) - a.bit_width
-                            bits.nth(a.pad_left(b))
-                                .expect("AssertL: unexpected end of frame");
-                            let value = Value::from_padded_bits(&mut bits, _c)
-                                .expect("AssertL: decode `C` value");
-                            tracker.track_dbg_call(cmr, value);
-                        }
-                    }
-
                     match (ip.inner(), choice_bit) {
                         (node::Inner::Case(_, right), true)
                         | (node::Inner::AssertR(_, right), true) => {
                             self.fwd(1 + a.pad_right(b));
                             call_stack.push(CallStack::Back(1 + a.pad_right(b)));
                             call_stack.push(CallStack::Goto(right));
-                            tracker.track_right(ip.ihr());
                         }
                         (node::Inner::Case(left, _), false)
                         | (node::Inner::AssertL(left, _), false) => {
                             self.fwd(1 + a.pad_left(b));
                             call_stack.push(CallStack::Back(1 + a.pad_left(b)));
                             call_stack.push(CallStack::Goto(left));
-                            tracker.track_left(ip.ihr());
                         }
                         (node::Inner::AssertL(_, r_cmr), true) => {
                             return Err(ExecutionError::ReachedPrunedBranch(*r_cmr))
@@ -373,13 +362,37 @@ impl BitMachine {
                     }
                 }
                 node::Inner::Witness(value) => self.write_value(value),
-                node::Inner::Jet(jet) => self.exec_jet(*jet, env, tracker)?,
+                node::Inner::Jet(jet) => self.exec_jet(*jet, env)?,
                 node::Inner::Word(value) => self.write_value(value.as_value()),
                 node::Inner::Fail(entropy) => {
                     return Err(ExecutionError::ReachedFailNode(*entropy))
                 }
             }
 
+            // Notify the tracker.
+            {
+                // Notice that, because the read frame stack is only ever
+                // shortened by `drop_read_frame`, and that method was not
+                // called above, this frame is still valid and correctly
+                // describes the Bit Machine "input" to the current node,
+                // no matter the node.
+                let read_iter = input_frame
+                    .map(|frame| frame.as_bit_iter(&self.data))
+                    .unwrap_or(crate::BitIter::from([].iter().copied()));
+                // Ideally we could also provide the Bit Machine "output" here,
+                // but for nonterminal nodes, we have not computed it and may
+                // not even have allocated space for it. So instead we provide an
+                // iterator which gives the output of terminal nodes (unit iden
+                // witness jets) and document on [`ExecTracker::visit_node`] that
+                // this iterator's contents are otherwise unspecified.
+                let write_iter = self
+                    .write
+                    .last()
+                    .map(|r| r.as_bit_iter(&self.data))
+                    .unwrap_or(crate::BitIter::from([].iter().copied()));
+                tracker.visit_node(ip, read_iter, write_iter);
+            }
+
             ip = loop {
                 match call_stack.pop() {
                     Some(CallStack::Goto(next)) => break next,
@@ -410,12 +423,7 @@ impl BitMachine {
         }
     }
 
-    fn exec_jet<J: Jet, T: ExecTracker<J>>(
-        &mut self,
-        jet: J,
-        env: &J::Environment,
-        tracker: &mut T,
-    ) -> Result<(), JetFailed> {
+    fn exec_jet<J: Jet>(&mut self, jet: J, env: &J::Environment) -> Result<(), JetFailed> {
         use crate::ffi::c_jets::frame_ffi::{c_readBit, c_writeBit, CFrameItem};
         use crate::ffi::c_jets::uword_width;
         use crate::ffi::ffi::UWORD;
@@ -501,15 +509,13 @@ impl BitMachine {
         let output_width = jet.target_ty().to_bit_width();
         // Input buffer is implicitly referenced by input read frame!
         // Same goes for output buffer
-        let (input_read_frame, input_buffer) = unsafe { get_input_frame(self, input_width) };
+        let (input_read_frame, _input_buffer) = unsafe { get_input_frame(self, input_width) };
         let (mut output_write_frame, output_buffer) = unsafe { get_output_frame(output_width) };
 
         let jet_fn = jet.c_jet_ptr();
         let c_env = J::c_jet_env(env);
         let success = jet_fn(&mut output_write_frame, input_read_frame, c_env);
 
-        tracker.track_jet_call(&jet, &input_buffer, &output_buffer, success);
-
         if !success {
             Err(JetFailed)
         } else {

src/bit_machine/tracker.rs

@@ -6,40 +6,47 @@
 //! frame management optimizations which can be used to great benefit.
 //!
 
-use simplicity_sys::ffi::UWORD;
 use std::collections::HashSet;
 
 use crate::jet::Jet;
-use crate::{Cmr, Ihr, Value};
+use crate::node::Inner;
+use crate::{Ihr, RedeemNode, Value};
 
-/// A type that keeps track of Bit Machine execution.
+/// An object which can be used to introspect the execution of the Bit Machine.
 ///
-/// The trait is implemented for [`SetTracker`], that tracks which case branches were executed,
-/// and it is implemented for [`NoTracker`], which is a dummy tracker that is
-/// optimized out by the compiler.
+/// As an example of what you can do with this
 ///
-/// The trait enables us to turn tracking on or off depending on a generic parameter.
+/// If this tracker records accesses to the left and right children of `Case` nodes, you
+/// may want to also implement [`PruningTracker`] so that this data can be used by
+/// [`RedeemNode::prune_with_tracking`] to prune the program. The most straightforward
+/// way to do this is to embed a [`SetTracker`] in your tracker and forward all the trait
+/// methods to that.
 pub trait ExecTracker<J: Jet> {
-    /// Track the execution of the left branch of the case node with the given `ihr`.
-    fn track_left(&mut self, ihr: Ihr);
-
-    /// Track the execution of the right branch of the case node with the given `ihr`.
-    fn track_right(&mut self, ihr: Ihr);
-
-    /// Track the execution of a `jet` call with the given `input_buffer`, `output_buffer`, and call result `success`.
-    fn track_jet_call(
+    /// Called immediately after a specific node of the program is executed, but before
+    /// its children are executed.
+    ///
+    /// More precisely, this iterates through the through the Simplicity program tree in
+    /// *pre* ordering. That is, for the program `comp iden unit` the nodes will be visited
+    /// in the order `comp`, `iden`, `unit`.
+    ///
+    /// This method be used for logging, to track left or write accesses of the children of a
+    /// `Case` node (to do this, call `input.peek_bit()`; false means left and true means right),
+    /// to extract debug information (which may be embedded in the hidden CMR in `AssertL`
+    /// and `AssertR` nodes, depending how the program was constructed), and so on.
+    ///
+    /// The provided arguments are:
+    ///   * `node` is the node which was just visited.
+    ///   * `input` is an iterator over the read frame when the node's execution began
+    ///   * for terminal nodes (`witness`, `unit`, `iden` and jets), `output` is an iterator
+    ///     the write frame after the node has executed. For non-terminal nodes, the contents
+    ///     of this iterator are unspecified and should not be relied upon.
+    fn visit_node<'d>(
         &mut self,
-        jet: &J,
-        input_buffer: &[UWORD],
-        output_buffer: &[UWORD],
-        success: bool,
-    );
-
-    /// Track the potential execution of a `dbg!` call with the given `cmr` and `value`.
-    fn track_dbg_call(&mut self, cmr: &Cmr, value: Value);
-
-    /// Check if tracking debug calls is enabled.
-    fn is_track_debug_enabled(&self) -> bool;
+        _node: &RedeemNode<J>,
+        _input: super::FrameIter,
+        _output: super::FrameIter,
+    ) {
+    }
 }
 
 pub trait PruneTracker<J: Jet>: ExecTracker<J> {
@@ -58,20 +65,21 @@ pub struct SetTracker {
 }
 
 impl<J: Jet> ExecTracker<J> for SetTracker {
-    fn track_left(&mut self, ihr: Ihr) {
-        self.left.insert(ihr);
-    }
-
-    fn track_right(&mut self, ihr: Ihr) {
-        self.right.insert(ihr);
-    }
-
-    fn track_jet_call(&mut self, _: &J, _: &[UWORD], _: &[UWORD], _: bool) {}
-
-    fn track_dbg_call(&mut self, _: &Cmr, _: Value) {}
-
-    fn is_track_debug_enabled(&self) -> bool {
-        false
+    fn visit_node<'d>(
+        &mut self,
+        node: &RedeemNode<J>,
+        mut input: super::FrameIter,
+        _output: super::FrameIter,
+    ) {
+        match (node.inner(), input.next()) {
+            (Inner::AssertL(..) | Inner::Case(..), Some(false)) => {
+                self.left.insert(node.ihr());
+            }
+            (Inner::AssertR(..) | Inner::Case(..), Some(true)) => {
+                self.right.insert(node.ihr());
+            }
+            _ => {}
+        }
     }
 }
 
@@ -90,16 +98,17 @@ impl<J: Jet> PruneTracker<J> for SetTracker {
 pub struct NoTracker;
 
 impl<J: Jet> ExecTracker<J> for NoTracker {
-    fn track_left(&mut self, _: Ihr) {}
-
-    fn track_right(&mut self, _: Ihr) {}
-
-    fn track_jet_call(&mut self, _: &J, _: &[UWORD], _: &[UWORD], _: bool) {}
-
-    fn track_dbg_call(&mut self, _: &Cmr, _: Value) {}
-
-    fn is_track_debug_enabled(&self) -> bool {
-        // Set flag to test frame decoding in unit tests
-        cfg!(test)
+    fn visit_node<'d>(
+        &mut self,
+        node: &RedeemNode<J>,
+        mut input: super::FrameIter,
+        mut output: super::FrameIter,
+    ) {
+        if cfg!(test) {
+            // In unit tests, attempt to decode values from the frames, confirming that
+            // these work.
+            let _input_val = Value::from_padded_bits(&mut input, &node.arrow().source);
+            let _output_val = Value::from_padded_bits(&mut output, &node.arrow().source);
+        }
     }
 }