Skip to main content

dive_core/
random.rs

1//! Random draws (`TLC!RandomElement`): the run's streams, which the engine
2//! supplies.
3//!
4//! The core defines the interface only. `dive-api` implements it with
5//! `dive-stdlib`'s seeded streams and `dive-store`'s TLC state fingerprint,
6//! so that the core's draws continue the streams start-up evaluation drew
7//! from.
8
9use dive_ir::StdOp;
10use dive_value::{Ctx, Value};
11
12use crate::Error;
13use crate::handle::Handle;
14use crate::heap::Heap;
15
16/// A random stream in use: the startup stream, or one expanded state's.
17pub trait DrawStream: Send + std::fmt::Debug {
18    /// Applies the random operator `op` to `args`, drawing from the stream.
19    ///
20    /// # Errors
21    /// TLC's evaluation error of the operator, or a refusal.
22    fn draw(&mut self, op: StdOp, args: &[Value], ctx: Ctx) -> Result<Value, Error>;
23}
24
25/// The run's random streams.
26pub trait Draws: Send + Sync {
27    /// The startup stream, where the constant definitions and `ASSUME`s
28    /// left it: `Init` draws from it.
29    fn startup(&self) -> Box<dyn DrawStream>;
30
31    /// The stream for expanding the state whose variables (in IR order)
32    /// are `vars`: TLC's `fingerprint(state) ^ seed`, or dive's replayable
33    /// stream keyed by the fingerprint.
34    ///
35    /// # Errors
36    /// A state that cannot be converted or fingerprinted.
37    fn state(&self, heap: &mut Heap, vars: &[Handle]) -> Result<Box<dyn DrawStream>, Error>;
38}
39
40/// The run's `TLCSet`/`TLCGet` registers: the
41/// dive-eval evaluator's, which constant definitions and `ASSUME`s wrote.
42pub trait Registers: Send + Sync {
43    /// Applies `TLCSet(key, value)` or `TLCGet(key)` to evaluated
44    /// arguments. `TLCGet("level")` never reaches it.
45    ///
46    /// # Errors
47    /// TLC's evaluation error, or a refusal.
48    fn call(&self, op: StdOp, args: &[Value]) -> Result<Value, Error>;
49}