polydat_core/iteration/comprehension/surfaces/
mod.rs

1// Copyright 2024-2026 Jonathan Shook
2// SPDX-License-Identifier: Apache-2.0
3
4//! Consumption surfaces — spec §9.5.
5//!
6//! Three independent first-class consumption surfaces over a
7//! shared compiled IR:
8//!
9//! - [`CoordinateStream`] (first-order) — dispenses coordinate
10//!   tuples (`Vec<(String, TupleValue)>`).
11//! - [`ScopedKernelStream<K>`] (second-order) — dispenses
12//!   scoped kernel instances; functor over the first-order
13//!   via `K`'s `KernelScope` impl.
14//! - [`scope_once`](fn@scope_once) (one-shot) — non-streamed; takes a single
15//!   coord tuple and produces a single scoped kernel instance.
16//!
17//! All three surfaces share the underlying `Program` via
18//! `Arc<Program>` but maintain independent dispense state per
19//! spec §9.5.2's independence contract:
20//!
21//! > Each call to `coordinate_stream` or
22//! > `scoped_kernel_stream` returns a fresh streamer with its
23//! > own dispense cursor. The streamers share the underlying
24//! > compiled IR but allocate their own per-streamer state.
25//!
26//! The entry point is [`CompiledComprehension`], obtained via
27//! [`compile`]`(&ast)` or `CompiledComprehension::from_ast`.
28
29use std::sync::Arc;
30
31use super::ast::Comprehension;
32use super::ir::compile as compile_to_ir;
33
34pub mod compiled;
35pub mod coord_stream;
36pub mod instance;
37pub mod polydat_kernel;
38pub mod scope_once;
39pub mod scoped_stream;
40
41pub use compiled::CompiledComprehension;
42pub use coord_stream::CoordinateStream;
43pub use instance::{KernelScope, ScopedKernelInstance};
44pub use polydat_kernel::{
45    PolydatKernelScope, polydat_value_to_tuple_value, tuple_value_to_polydat_value,
46};
47pub use scope_once::scope_once;
48pub use scoped_stream::ScopedKernelStream;
49
50/// Convenience: compile an AST into a [`CompiledComprehension`]
51/// ready to dispense. Equivalent to
52/// `CompiledComprehension::from_ast(ast)`.
53pub fn compile(ast: &Comprehension) -> CompiledComprehension {
54    let program = Arc::new(compile_to_ir(ast));
55    CompiledComprehension::from_program(program)
56}
polydat_core/iteration/comprehension/surfaces/mod.rs

polydat_core/iteration/comprehension/surfaces/
mod.rs
