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}