onedrop_eval/

compiled_block.rs

//! Compiled block: bundles a [`Vec<Node>`] (evalexpr fallback) with an
//! optional [`CompiledBytecode`] lowering.
//!
//! Most preset hot loops (per-frame eqs, per-vertex warp eqs, custom-shape
//! per-frame, custom-wave per-frame / per_frame_init, …) want the same
//! "prefer bytecode VM, fall back to evalexpr Node walk" branching that
//! [`onedrop-engine::engine::wave_phase`] already wires by hand for the
//! per_point hot path. This newtype hoists that pattern into the eval
//! crate so every call site picks it up uniformly.
//!
//! - `from_nodes(Vec<Node>)` — try-compiles the bytecode lazily; on
//!   failure (an op the VM doesn't support: `rand`, `gmegabuf`, …) the
//!   block keeps the Nodes and runtime falls back transparently.
//! - `run(&mut MilkContext)` — single entry point that picks the
//!   bytecode path when available. The bytecode path is infallible by
//!   construction (`try_compile` is the only failure point); the
//!   fallback discards per-equation errors silently.
//! - `nodes()` / `bytecode()` — exposed for call sites that still want
//!   per-equation error logging or special handling (sequential vs
//!   parallel-samples in [`onedrop-engine::engine::wave_phase`]).

use crate::bytecode::CompiledBytecode;
use crate::context::MilkContext;
use evalexpr::Node;

/// A pre-compiled block of expressions ready to execute against a
/// [`MilkContext`]. See module docs.
#[derive(Debug, Clone)]
pub struct CompiledBlock {
    nodes: Vec<Node>,
    bytecode: Option<CompiledBytecode>,
}

impl CompiledBlock {
    /// Take ownership of `nodes` and try to lower them to bytecode
    /// against `ctx`. Cold-variable names referenced by the block are
    /// interned into `ctx.cold` so the emitted opcodes carry slab
    /// indices.
    ///
    /// On lowering failure (any unsupported operator/function) the
    /// block stores `bytecode: None` and the runtime falls back to
    /// evalexpr's tree-walking interpreter — same observable
    /// behaviour, just slower.
    pub fn from_nodes(nodes: Vec<Node>, ctx: &mut MilkContext) -> Self {
        let bytecode = if nodes.is_empty() {
            None
        } else {
            CompiledBytecode::try_compile(&nodes, ctx).ok()
        };
        Self { nodes, bytecode }
    }

    /// Empty block — `run` is a no-op.
    pub fn empty() -> Self {
        Self {
            nodes: Vec::new(),
            bytecode: None,
        }
    }

    /// Underlying evalexpr nodes. Always populated, even when bytecode
    /// is also available (kept around as the fallback path for the few
    /// runtime decisions that need per-node access — e.g. per-equation
    /// error logging).
    pub fn nodes(&self) -> &[Node] {
        &self.nodes
    }

    /// Bytecode lowering when available. `None` means at least one
    /// node uses an op the VM doesn't support; runtime falls back to
    /// the Nodes path.
    pub fn bytecode(&self) -> Option<&CompiledBytecode> {
        self.bytecode.as_ref()
    }

    pub fn is_empty(&self) -> bool {
        self.nodes.is_empty()
    }

    pub fn len(&self) -> usize {
        self.nodes.len()
    }

    /// Execute the block against `ctx`. Prefers the bytecode VM when
    /// available; otherwise iterates the evalexpr nodes and discards
    /// per-equation errors silently. Call sites that want to log
    /// per-equation failures should use [`CompiledBlock::nodes`] +
    /// [`CompiledBlock::bytecode`] directly.
    pub fn run(&self, ctx: &mut MilkContext) {
        if let Some(bc) = &self.bytecode {
            bc.run(ctx);
        } else {
            for node in &self.nodes {
                let _ = node.eval_with_context_mut(ctx);
            }
        }
    }
}

impl Default for CompiledBlock {
    fn default() -> Self {
        Self::empty()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::MilkEvaluator;

    fn compile(eqs: &[&str]) -> CompiledBlock {
        let mut ev = MilkEvaluator::new();
        let owned: Vec<String> = eqs.iter().map(|s| s.to_string()).collect();
        let nodes = ev.compile_batch(&owned).unwrap();
        CompiledBlock::from_nodes(nodes, ev.context_mut())
    }

    #[test]
    fn lowers_to_bytecode_when_supported() {
        let block = compile(&["x = 0.5", "y = x * 2.0"]);
        assert!(
            block.bytecode().is_some(),
            "simple arithmetic must lower to bytecode"
        );
        assert_eq!(block.len(), 2);
    }

    #[test]
    fn falls_back_to_nodes_on_unsupported_op() {
        // `lerp` has no bytecode opcode and isn't a registered evalexpr
        // builtin either — the compile-fallback path keeps the block on
        // the Node walker so the renderer doesn't crash on it.
        let block = compile(&["x = lerp(0, 1, 0.5)"]);
        assert!(
            block.bytecode().is_none(),
            "lerp() must keep block on Node path"
        );
        assert_eq!(block.len(), 1);
    }

    #[test]
    fn empty_run_is_noop() {
        let block = CompiledBlock::empty();
        let mut ctx = MilkContext::new();
        block.run(&mut ctx); // no panic
        assert!(block.is_empty());
        assert_eq!(block.len(), 0);
    }

    #[test]
    fn run_bytecode_and_nodes_paths_match() {
        // Bytecode-lowerable block.
        let bc_block = compile(&["x = 0.25", "y = x * 4.0", "r = sin(x)"]);
        assert!(bc_block.bytecode().is_some());
        let mut ctx_bc = MilkContext::new();
        bc_block.run(&mut ctx_bc);

        // Force the Node fallback: same eqs, but discard the bytecode.
        let mut nodes_block = bc_block.clone();
        nodes_block.bytecode = None;
        let mut ctx_nodes = MilkContext::new();
        nodes_block.run(&mut ctx_nodes);

        for name in ["x", "y", "r"] {
            let a = ctx_bc.get(name).unwrap();
            let b = ctx_nodes.get(name).unwrap();
            assert!((a - b).abs() < 1e-12, "{name}: bytecode={a} nodes={b}");
        }
    }
}