bit_machine: add example StderrTracker which outputs stuff to stderr

Outputting to stderr is not super useful but this can be used as a demo
of what the tracker is able to do.

Author: apoelstra

src/bit_machine/mod.rs

@@ -22,7 +22,9 @@ use crate::{Cmr, FailEntropy, Value};
 use frame::Frame;
 
 pub use self::limits::LimitError;
-pub use self::tracker::{ExecTracker, NoTracker, NodeOutput, PruneTracker, SetTracker};
+pub use self::tracker::{
+    ExecTracker, NoTracker, NodeOutput, PruneTracker, SetTracker, StderrTracker,
+};
 
 /// An iterator over the contents of a read or write frame which yields bits.
 pub type FrameIter<'a> = crate::BitIter<core::iter::Copied<core::slice::Iter<'a, u8>>>;
@@ -228,6 +230,9 @@ impl BitMachine {
 
     /// Execute the given `program` on the Bit Machine, using the given environment and tracker.
     ///
+    /// See [`crate::bit_machine::StderrTracker`] as an example which outputs various debug
+    /// data for each node, providing a track of the bit machine's operation.
+    ///
     ///  ## Precondition
     ///
     /// The Bit Machine is constructed via [`Self::for_program()`] to ensure enough space.

src/bit_machine/tracker.rs

@@ -129,3 +129,77 @@ impl<J: Jet> ExecTracker<J> for NoTracker {
         }
     }
 }
+
+/// Tracker that just outputs all its activity to stderr.
+#[derive(Clone, Debug, Default)]
+pub struct StderrTracker {
+    exec_count: usize,
+    inner: SetTracker,
+}
+
+impl StderrTracker {
+    /// Constructs a new empty [`StderrTracker`], ready for use.
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl<J: Jet> ExecTracker<J> for StderrTracker {
+    fn visit_node(
+        &mut self,
+        node: &RedeemNode<J>,
+        mut input: super::FrameIter,
+        output: NodeOutput,
+    ) {
+        let input_val = Value::from_padded_bits(&mut input, &node.arrow().source)
+            .expect("input from bit machine will always be well-formed");
+        eprintln!(
+            "[{:4}] exec {:10} {}",
+            self.exec_count,
+            node.inner(),
+            node.arrow()
+        );
+        eprintln!("       input {input_val}");
+        match output {
+            NodeOutput::NonTerminal => { /* don't bother describing non-terminal output */ }
+            NodeOutput::JetFailed => eprintln!("    JET FAILED"),
+            NodeOutput::Success(mut output) => {
+                let output_val = Value::from_padded_bits(&mut output, &node.arrow().target)
+                    .expect("input from bit machine will always be well-formed");
+                eprintln!("      output {output_val}");
+            }
+        }
+
+        if let crate::node::Inner::AssertL(_, cmr) = node.inner() {
+            // SimplicityHL, when compiling in "debug mode", tags nodes by inserting
+            // synthetic AssertL nodes where the "cmr" is actually a key into a lookup
+            // table of debug information. An implementation of ExecTracker within
+            // the compiler itself might do a lookup here to output more useful
+            // information to the user.
+            eprintln!("      [debug] assertL CMR {cmr}");
+        }
+
+        self.exec_count += 1;
+        eprintln!();
+    }
+}
+
+impl<J: Jet> PruneTracker<J> for StderrTracker {
+    fn contains_left(&self, ihr: Ihr) -> bool {
+        if PruneTracker::<J>::contains_left(&self.inner, ihr) {
+            true
+        } else {
+            eprintln!("Pruning unexecuted left child of IHR {ihr}");
+            false
+        }
+    }
+
+    fn contains_right(&self, ihr: Ihr) -> bool {
+        if PruneTracker::<J>::contains_right(&self.inner, ihr) {
+            true
+        } else {
+            eprintln!("Pruning unexecuted right child of IHR {ihr}");
+            false
+        }
+    }
+}

src/node/redeem.rs

@@ -293,6 +293,11 @@ impl<J: Jet> RedeemNode<J> {
         self.prune_with_tracker(env, &mut SetTracker::default())
     }
 
+    /// Prune the redeem program, as in [`Self::prune`], but with a custom tracker which
+    /// can introspect or control pruning.
+    ///
+    /// See [`crate::bit_machine::StderrTracker`] as an example which outputs the IHR of
+    /// each case combinator that we prune a child of.
     pub fn prune_with_tracker<T: PruneTracker<J>>(
         &self,
         env: &J::Environment,