polydat 0.2.0

Polydat — a variates construction engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

// Copyright 2024-2026 Jonathan Shook
// SPDX-License-Identifier: Apache-2.0

//! Consumption surfaces — spec §9.5.
//!
//! Three independent first-class consumption surfaces over a
//! shared compiled IR:
//!
//! - [`CoordinateStream`] (first-order) — dispenses coordinate
//!   tuples (`Vec<(String, TupleValue)>`).
//! - [`ScopedKernelStream<K>`] (second-order) — dispenses
//!   scoped kernel instances; functor over the first-order
//!   via `K`'s `KernelScope` impl.
//! - [`scope_once`] (one-shot) — non-streamed; takes a single
//!   coord tuple and produces a single scoped kernel instance.
//!
//! All three surfaces share the underlying [`Program`] via
//! `Arc<Program>` but maintain independent dispense state per
//! spec §9.5.2's independence contract:
//!
//! > Each call to `coordinate_stream` or
//! > `scoped_kernel_stream` returns a fresh streamer with its
//! > own dispense cursor. The streamers share the underlying
//! > compiled IR but allocate their own per-streamer state.
//!
//! The entry point is [`CompiledComprehension`], obtained via
//! [`Comprehension::compile`] (an extension method on the AST
//! type).

use std::sync::Arc;

use super::ast::Comprehension;
use super::ir::compile as compile_to_ir;

pub mod compiled;
pub mod coord_stream;
pub mod polydat_kernel;
pub mod instance;
pub mod scope_once;
pub mod scoped_stream;

pub use compiled::CompiledComprehension;
pub use coord_stream::CoordinateStream;
pub use polydat_kernel::{
    polydat_value_to_tuple_value, tuple_value_to_polydat_value, PolydatKernelScope,
};
pub use instance::{KernelScope, ScopedKernelInstance};
pub use scope_once::scope_once;
pub use scoped_stream::ScopedKernelStream;

/// Convenience: compile an AST into a [`CompiledComprehension`]
/// ready to dispense. Equivalent to
/// `CompiledComprehension::from_ast(ast)`.
pub fn compile(ast: &Comprehension) -> CompiledComprehension {
    let program = Arc::new(compile_to_ir(ast));
    CompiledComprehension::from_program(program)
}