Merge #288: Generic BitMachine execution tracker

36ff961 CI: check that documentation builds without errors (Michael Zaikin)
8ff9bab Extend tracker trait with jet call tracing (Michael Zaikin)

Pull request description:

  This PR generalizes `CaseTracker` to `ExecTracker` that now supports tracking jet calls (in addition to case branches). It is also now possible to run BitMachine with a custom tracker created outside of the crate.

  This mechanim allows to implement jet tracer which pretty-prints jet arguments/result for each invocation, see https://github.com/m-kus/simfony/pull/2/files#diff-13e8b158f84f88059e0bd8631dfa9113112e30d7b8c21a15413d0ef36d2ea180

  As a follow up it is proposed to further extend `ExecTracker` trait to allow visitor pattern on case/assert expressions. That would enable debug logging, similar to https://github.com/uncomputable/simfony-webide/blob/adb60d4e60c0d6b019ea13f64b1a166da3467d8d/src/function.rs#L145

  Having these two features (jet calls tracking and debug symbols) combined it's fairly simple to output weighted stack traces (e.g. in pprof) and build a Simfony profiler.

ACKs for top commit:
  apoelstra:
    ACK 36ff961; successfully ran local tests
  uncomputable:
    ACK 36ff961

Tree-SHA512: e28f349eaf11dbe442413ebeb5018f9c7694d5a5d4d5cd37a05f793f89423cc2ca4e3337bc48128c551bf95e4617d016bf1fc8434d5090c9951773d8e5b469bd

Author: uncomputable

.github/workflows/main.yml

@@ -119,3 +119,16 @@ jobs:
         run: |
           cargo test --locked --manifest-path simplicity-sys/Cargo.toml
           cargo test --locked --workspace --all-features
+
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Crate
+        uses: actions/checkout@v4
+      - name: Checkout Toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - name: Check that documentation builds without errors
+        env:
+          RUSTDOCFLAGS: "--cfg docsrs -D warnings -D rustdoc::broken-intra-doc-links"
+        run: cargo doc -j1 --all-features

src/bit_machine/mod.rs

@@ -20,6 +20,7 @@ use crate::types::Final;
 use crate::{analysis, Ihr};
 use crate::{Cmr, FailEntropy, Value};
 use frame::Frame;
+use simplicity_sys::ffi::UWORD;
 
 pub use self::limits::LimitError;
 
@@ -242,7 +243,12 @@ impl BitMachine {
         Ok(tracker)
     }
 
-    fn exec_with_tracker<J: Jet, T: CaseTracker>(
+    /// Execute the given `program` on the Bit Machine, using the given environment and tracker.
+    ///
+    ///  ## Precondition
+    ///
+    /// The Bit Machine is constructed via [`Self::for_program()`] to ensure enough space.
+    pub fn exec_with_tracker<J: Jet, T: ExecTracker<J>>(
         &mut self,
         program: &RedeemNode<J>,
         env: &J::Environment,
@@ -371,7 +377,7 @@ impl BitMachine {
                     }
                 }
                 node::Inner::Witness(value) => self.write_value(value),
-                node::Inner::Jet(jet) => self.exec_jet(*jet, env)?,
+                node::Inner::Jet(jet) => self.exec_jet(*jet, env, tracker)?,
                 node::Inner::Word(value) => self.write_value(value.as_value()),
                 node::Inner::Fail(entropy) => {
                     return Err(ExecutionError::ReachedFailNode(*entropy))
@@ -408,7 +414,12 @@ impl BitMachine {
         }
     }
 
-    fn exec_jet<J: Jet>(&mut self, jet: J, env: &J::Environment) -> Result<(), JetFailed> {
+    fn exec_jet<J: Jet, T: ExecTracker<J>>(
+        &mut self,
+        jet: J,
+        env: &J::Environment,
+        tracker: &mut T,
+    ) -> 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;
@@ -494,13 +505,15 @@ 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 {
@@ -510,25 +523,33 @@ impl BitMachine {
     }
 }
 
-/// A type that keeps track of which case branches were executed
-/// during the execution of the Bit Machine.
+/// A type that keeps track of Bit Machine execution.
 ///
-/// The trait is implemented for [`SetTracker`], which does the actual tracking,
+/// 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.
 ///
 /// The trait enables us to turn tracking on or off depending on a generic parameter.
-trait CaseTracker {
+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(
+        &mut self,
+        jet: &J,
+        input_buffer: &[UWORD],
+        output_buffer: &[UWORD],
+        success: bool,
+    );
 }
 
 /// Tracker of executed left and right branches for each case node.
 #[derive(Clone, Debug, Default)]
-pub(crate) struct SetTracker {
+pub struct SetTracker {
     left: HashSet<Ihr>,
     right: HashSet<Ihr>,
 }
@@ -545,23 +566,28 @@ impl SetTracker {
     }
 }
 
+/// Tracker that does not do anything (noop).
 #[derive(Copy, Clone, Debug)]
-struct NoTracker;
+pub struct NoTracker;
 
-impl CaseTracker for 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) {}
 }
 
-impl CaseTracker for 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) {}
 }
 
 /// Errors related to simplicity Execution