datalogic_rs/

session.rs

//! Reusable evaluation handle that owns its arena.
//!
//! [`Session`] owns a [`bumpalo::Bump`] and exposes [`Session::reset`] for the
//! caller to bound peak memory between calls. The session itself never resets
//! the arena — every `evaluate*` method appends to the bump and the caller
//! decides when to release that memory back to the start-of-chunk position.
//! Inputs go through [`crate::EvalInput`] so callers pass whatever they have
//! on hand (`&str`, `&OwnedDataValue`, `&serde_json::Value`, …); outputs are
//! either owned ([`OwnedDataValue`] / `String` / `serde_json::Value`) or
//! borrowed from the arena ([`Self::eval_borrowed`]) — borrowed results are
//! invalidated by the next `&mut self` call (Rust's borrow checker enforces).
//!
//! For a one-shot evaluation that owns and drops its arena per call, use
//! [`crate::Engine::eval_str`] (convenience). For full caller control of
//! the arena lifecycle, use [`crate::Engine::evaluate`] directly with a
//! caller-passed `&Bump`.
//!
//! # What each input adds to the arena
//!
//! Every call brings its data into the arena before evaluating, and that
//! stays until [`Session::reset`]. What it costs depends on the input:
//!
//! | Input | Arena cost per call |
//! |-------|---------------------|
//! | `&ParsedData` | nothing: the tree already lives in the handle |
//! | `&DataValue` | nothing |
//! | `&OwnedDataValue` | the array and object spines; strings, keys and tensor bytes are borrowed |
//! | `&serde_json::Value` | the array and object spines; strings and keys are borrowed |
//! | `&str` | a parse tree; unescaped strings are borrowed from the text |
//!
//! For a large context evaluated many times, build a
//! [`crate::ParsedData`] once (`from_json`, `from_value` or `from_owned`)
//! and pass the handle: each call then costs only what the rule does.

use std::marker::PhantomData;
use std::ops::Deref;
use std::sync::Arc;

use bumpalo::Bump;
use datavalue::OwnedDataValue;

use crate::arena::DataValue;
use crate::{Engine, EvalInput, Logic, Result};

/// Reusable evaluation handle. Construct via [`Engine::session`].
///
/// Owns a [`bumpalo::Bump`]; the caller controls reset via [`Self::reset`].
/// Subsequent `evaluate*` calls append to the bump until the caller resets
/// or the session is dropped — letting the caller amortise reset cost across
/// logical batches and avoid resetting between calls that don't need it.
///
/// # Example
///
/// ```rust
/// use datalogic_rs::Engine;
///
/// let engine = Engine::new();
/// let compiled = engine.compile(r#"{"+": [{"var": "x"}, 1]}"#).unwrap();
/// let mut session = engine.session();
///
/// for x in 0..3 {
///     let payload = format!(r#"{{"x": {}}}"#, x);
///     let result = session.eval_str(&compiled, &payload).unwrap();
///     assert_eq!(result, (x + 1).to_string());
///     // Reset between iterations to keep peak memory bounded by the
///     // largest single evaluation rather than the cumulative loop.
///     session.reset();
/// }
/// ```
///
/// # Holding the engine
///
/// `E` is how the session holds its engine. [`Engine::session`] borrows it
/// (`Session<'_>`, the default). A [`SharedSession`] holds an
/// `Arc<Engine>` instead, so it is `'static + Send`: it can be stored in a
/// struct, moved to another thread or held across an `.await` without
/// tying it to the engine's lifetime. Both have the same methods.
pub struct Session<'engine, E = &'engine Engine> {
    engine: E,
    arena: Bump,
    _engine: PhantomData<&'engine Engine>,
}

/// A [`Session`] that holds its engine by `Arc`: `'static + Send`, with no
/// lifetime to thread through the caller's types. Build one with
/// [`SharedSession::new`] or `SharedSession::from(arc)`.
///
/// ```rust
/// use std::sync::Arc;
/// use datalogic_rs::{Engine, SharedSession};
///
/// let engine = Arc::new(Engine::new());
/// let logic = engine.compile(r#"{"var": "x"}"#).unwrap();
/// let mut session = SharedSession::new(engine);
/// let handle = std::thread::spawn(move || session.eval_str(&logic, r#"{"x": 1}"#).unwrap());
/// assert_eq!(handle.join().unwrap(), "1");
/// ```
pub type SharedSession = Session<'static, Arc<Engine>>;

impl SharedSession {
    /// A session over a shared engine. The session keeps the engine alive.
    pub fn new(engine: Arc<Engine>) -> Self {
        Session::with_engine(engine)
    }
}

impl From<Arc<Engine>> for SharedSession {
    fn from(engine: Arc<Engine>) -> Self {
        SharedSession::new(engine)
    }
}

impl<E: Deref<Target = Engine>> std::fmt::Debug for Session<'_, E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Print the engine handle plus the arena's currently-allocated byte
        // count — useful for tracking high-water marks across resets without
        // dumping every chunk's raw bytes.
        f.debug_struct("Session")
            .field("engine", &*self.engine)
            .field("arena_allocated_bytes", &self.arena.allocated_bytes())
            .finish_non_exhaustive()
    }
}

impl<'engine> Session<'engine> {
    #[inline]
    pub(crate) fn borrowing(engine: &'engine Engine) -> Self {
        Session::with_engine(engine)
    }
}

impl<'engine, E: Deref<Target = Engine>> Session<'engine, E> {
    #[inline]
    fn with_engine(engine: E) -> Self {
        Self {
            engine,
            arena: Bump::new(),
            _engine: PhantomData,
        }
    }

    /// The engine this session evaluates with.
    #[inline]
    pub fn engine(&self) -> &Engine {
        &self.engine
    }

    /// Reset the session's arena, returning every allocated chunk to the
    /// free list's start-of-chunk position without freeing OS memory.
    ///
    /// Call this between logical batches to bound peak memory. After reset,
    /// any borrowed reference previously returned by [`Self::eval_borrowed`]
    /// is invalidated — the borrow checker enforces this for the common case
    /// (the result borrow ends with the previous `&mut self` borrow).
    ///
    /// `Bump::reset` is constant-time (resets a few pointers); the freed
    /// chunks remain allocated and serve subsequent calls without re-asking
    /// the OS for memory.
    #[inline]
    pub fn reset(&mut self) {
        self.arena.reset();
    }

    /// Drop the session's arena and replace it with a fresh one whose
    /// initial chunk holds at least `capacity` bytes.
    ///
    /// Use this when you know the steady-state high-water mark of your
    /// workload (e.g. captured via [`Self::allocated_bytes`] after a
    /// warm-up pass) and want subsequent calls to run on a single
    /// pre-sized chunk — no chunk-growth events during the timed window.
    ///
    /// Unlike [`Self::reset`], which keeps the existing chunks and only
    /// rewinds the bump pointer, this drops the chunks entirely and
    /// allocates one new chunk of the requested capacity. Any reference
    /// previously returned by [`Self::eval_borrowed`] is invalidated; the
    /// `&mut self` signature lets the borrow checker enforce this.
    pub fn reset_with_capacity(&mut self, capacity: usize) {
        self.arena = Bump::with_capacity(capacity);
    }

    /// Total bytes currently occupied by the session's arena chunks.
    ///
    /// Useful for capturing a workload's steady-state high-water mark
    /// after a warm-up pass — feed the returned value into
    /// [`Self::reset_with_capacity`] to pre-size the arena before a timed
    /// loop. Stable across [`Self::reset`] calls (chunks aren't freed);
    /// drops to the new chunk size after [`Self::reset_with_capacity`].
    ///
    /// Forwards to [`bumpalo::Bump::allocated_bytes`].
    #[inline]
    pub fn allocated_bytes(&self) -> usize {
        self.arena.allocated_bytes()
    }

    /// Evaluate `compiled` against `data` and deep-clone the result into
    /// an [`OwnedDataValue`] that survives subsequent calls and resets.
    ///
    /// The intermediate arena allocations stay in the session's bump
    /// until the caller invokes [`Self::reset`]. For long-running loops,
    /// call `reset` between iterations to keep peak memory bounded.
    ///
    /// # Example
    ///
    /// ```rust
    /// use datalogic_rs::Engine;
    ///
    /// let engine = Engine::new();
    /// let compiled = engine.compile(r#"{"==": [{"var": "x"}, 1]}"#).unwrap();
    /// let mut session = engine.session();
    /// let result = session.eval(&compiled, r#"{"x": 1}"#).unwrap();
    /// assert_eq!(result.as_bool(), Some(true));
    /// ```
    pub fn eval<'a, D>(&'a mut self, compiled: &Logic, data: D) -> Result<OwnedDataValue>
    where
        D: EvalInput<'a>,
    {
        self.eval_as(compiled, data)
    }

    /// Evaluate and convert the result straight into `R`, any
    /// [`crate::FromDataValue`] output: [`OwnedDataValue`], a JSON
    /// [`String`], or a `serde_json::Value` (with `serde_json`). The shared
    /// body of [`Self::eval`] / [`Self::eval_str`] / `eval_into`.
    ///
    /// For a `serde_json::Value` result this is one conversion, where
    /// `eval_into::<serde_json::Value>` builds the value and then
    /// deserializes it into a second one.
    ///
    /// ```rust
    /// # #[cfg(feature = "serde_json")] {
    /// use datalogic_rs::Engine;
    ///
    /// let engine = Engine::new();
    /// let compiled = engine.compile(r#"{"var": "user"}"#).unwrap();
    /// let mut session = engine.session();
    /// let user: serde_json::Value = session
    ///     .eval_as(&compiled, r#"{"user": {"id": 7}}"#)
    ///     .unwrap();
    /// assert_eq!(user["id"], 7);
    /// # }
    /// ```
    pub fn eval_as<'a, R, D>(&'a mut self, compiled: &Logic, data: D) -> Result<R>
    where
        R: crate::FromDataValue,
        D: EvalInput<'a>,
    {
        let arena: &'a Bump = &self.arena;
        // Bring the input in against the rule as this engine runs it, so
        // a projection matches the tree `evaluate` dispatches.
        let compiled = compiled.for_engine(&self.engine);
        let av = data.into_arena_for(compiled, &self.engine, arena)?;
        R::from_arena(self.engine.evaluate(compiled, av, arena)?)
    }

    /// JSON-string convenience: evaluate against `data` and serialise
    /// the result back to a JSON [`String`]. Reuses the arena across
    /// calls; does not reset — see [`Self::reset`].
    pub fn eval_str<'a, D>(&'a mut self, compiled: &Logic, data: D) -> Result<String>
    where
        D: EvalInput<'a>,
    {
        self.eval_as(compiled, data)
    }

    /// Typed convenience: evaluate and deserialise the result into
    /// `T: DeserializeOwned`. Use `T = serde_json::Value` for a JSON
    /// `Value` result; use a typed struct for direct mapping. Internally
    /// routes through `serde_json`.
    #[cfg(feature = "serde_json")]
    #[cfg_attr(docsrs, doc(cfg(feature = "serde_json")))]
    pub fn eval_into<'a, T, D>(&'a mut self, compiled: &Logic, data: D) -> Result<T>
    where
        T: serde::de::DeserializeOwned,
        D: EvalInput<'a>,
    {
        let value: serde_json::Value = self.eval_as(compiled, data)?;
        serde_json::from_value(value).map_err(crate::Error::from)
    }

    /// Evaluate under an explicit operation budget, reporting what the
    /// evaluation spent.
    ///
    /// Session-arena counterpart to [`Engine::evaluate_metered`], which
    /// documents what one operation is. The value is deep-cloned out like
    /// [`Self::eval`]'s, so the count survives the next `reset`.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[cfg(feature = "budget")] {
    /// use datalogic_rs::{Engine, Metered};
    ///
    /// let engine = Engine::new();
    /// let compiled = engine.compile(r#"{"filter": [{"var": "xs"}, {">": [{"var": ""}, 1]}]}"#).unwrap();
    /// let mut session = engine.session();
    ///
    /// let Metered { value, ops } = session
    ///     .eval_metered(&compiled, r#"{"xs": [1, 2, 3]}"#, u64::MAX)
    ///     .unwrap();
    /// assert_eq!(value.to_json_string(), "[2,3]");
    /// assert!(ops >= 3, "at least one operation per item filtered");
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// [`ErrorKind::BudgetExceeded`](crate::ErrorKind::BudgetExceeded)
    /// when the rule charges past `budget`, plus every error
    /// [`Self::eval`] can return. To observe the operations spent even
    /// when evaluation fails, call [`Self::eval_metered_report`].
    #[cfg(feature = "budget")]
    #[cfg_attr(docsrs, doc(cfg(feature = "budget")))]
    pub fn eval_metered<'a, D>(
        &'a mut self,
        compiled: &Logic,
        data: D,
        budget: u64,
    ) -> Result<crate::Metered<OwnedDataValue>>
    where
        D: EvalInput<'a>,
    {
        self.eval_metered_report(compiled, data, budget).transpose()
    }

    /// Failure-inclusive counterpart to [`Self::eval_metered`]: evaluates
    /// under `budget` and returns a [`crate::Metered`] report whose `ops`
    /// is populated whether evaluation succeeds (`value: Ok(...)`) or
    /// fails (`value: Err(...)`).
    ///
    /// Session-arena counterpart to [`Engine::evaluate_metered_report`],
    /// which documents the failure charge semantics (ordinary runtime
    /// errors, `BudgetExceeded`, and pre-dispatch input adaptation errors).
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[cfg(feature = "budget")] {
    /// use datalogic_rs::{Engine, ErrorCode, Metered};
    ///
    /// let engine = Engine::new();
    /// let compiled = engine.compile(r#"{"/": [1, {"var": "zero"}]}"#).unwrap();
    /// let mut session = engine.session();
    ///
    /// let Metered { value, ops } = session
    ///     .eval_metered_report(&compiled, r#"{"zero": 0}"#, 100);
    /// let err = value.unwrap_err();
    /// assert_eq!(err.code(), ErrorCode::Thrown);
    /// assert_eq!(err.operator(), Some("/"));
    /// assert_eq!(ops, 2);
    /// # }
    /// ```
    #[cfg(feature = "budget")]
    #[cfg_attr(docsrs, doc(cfg(feature = "budget")))]
    pub fn eval_metered_report<'a, D>(
        &'a mut self,
        compiled: &Logic,
        data: D,
        budget: u64,
    ) -> crate::Metered<Result<OwnedDataValue>>
    where
        D: EvalInput<'a>,
    {
        let arena: &'a Bump = &self.arena;
        let compiled = compiled.for_engine(&self.engine);
        let av = match data.into_arena_for(compiled, &self.engine, arena) {
            Ok(av) => av,
            Err(e) => {
                return crate::Metered {
                    value: Err(e),
                    ops: 0,
                };
            }
        };
        let metered = self
            .engine
            .evaluate_metered_report(compiled, av, arena, budget);
        crate::Metered {
            value: metered.value.and_then(crate::FromDataValue::from_arena),
            ops: metered.ops,
        }
    }

    /// Evaluate and return a borrowed result tied to this session's
    /// arena. Same semantics as [`Self::eval`] but skips the deep-clone
    /// — the returned reference is invalidated by the next `&mut self`
    /// call (the borrow checker enforces). Use this when the result is
    /// consumed before the next session call; for cross-call retention
    /// use [`Self::eval`].
    ///
    /// Symmetric with [`Engine::evaluate`] (caller-managed bump,
    /// borrowed result) but with the bump owned by the session. Does
    /// not reset the arena — call [`Self::reset`] explicitly.
    ///
    /// # Example
    ///
    /// ```rust
    /// use datalogic_rs::Engine;
    ///
    /// let engine = Engine::new();
    /// let compiled = engine.compile(r#"{"+": [{"var": "x"}, 1]}"#).unwrap();
    /// let mut session = engine.session();
    /// let result = session.eval_borrowed(&compiled, r#"{"x": 5}"#).unwrap();
    /// assert_eq!(result.as_i64(), Some(6));
    /// ```
    pub fn eval_borrowed<'a, D>(
        &'a mut self,
        compiled: &'a Logic,
        data: D,
    ) -> Result<&'a DataValue<'a>>
    where
        D: EvalInput<'a>,
    {
        let arena: &'a Bump = &self.arena;
        self.engine.evaluate(compiled, data, arena)
    }
}