Skip to main content

zero_client/ivm/
operator.rs

1//! Operators, their inputs and outputs, and sources
2//! (`packages/zql/src/ivm/operator.ts`, `schema.ts`, `source.ts`, and
3//! `filter-operators.ts`).
4
5use super::{Change, Comparator, Constraint, Node, NodeStream, PipelineError, Row, SourceChange};
6use crate::ast::{Condition, OrderPart, System};
7use crate::map::OrderedMap;
8use crate::schema::{Column, Table};
9use std::collections::HashSet;
10use std::rc::{Rc, Weak};
11
12/// The schema of an operator's output (`SourceSchema` in `schema.ts`).
13#[derive(Clone)]
14pub struct SourceSchema {
15    pub table_name: String,
16    pub columns: OrderedMap<Column>,
17    pub primary_key: Vec<String>,
18    /// Relationship schemas, in the order they were added.
19    pub relationships: Vec<(String, Rc<SourceSchema>)>,
20    pub is_hidden: bool,
21    pub system: System,
22    pub compare_rows: Comparator,
23    /// `None` for an unordered input.
24    pub sort: Option<Vec<OrderPart>>,
25}
26
27impl SourceSchema {
28    pub fn relationship(&self, name: &str) -> Option<&Rc<SourceSchema>> {
29        self.relationships
30            .iter()
31            .find(|(n, _)| n == name)
32            .map(|(_, s)| s)
33    }
34
35    pub fn relationship_names(&self) -> Vec<&str> {
36        self.relationships.iter().map(|(n, _)| n.as_str()).collect()
37    }
38
39    /// This schema with `schema` added (or replaced) as relationship `name`.
40    pub fn adding(&self, name: &str, schema: Rc<SourceSchema>) -> SourceSchema {
41        let mut copy = self.clone();
42        match copy.relationships.iter_mut().find(|(n, _)| n == name) {
43            Some(entry) => entry.1 = schema,
44            None => copy.relationships.push((name.to_owned(), schema)),
45        }
46        copy
47    }
48}
49
50impl std::fmt::Debug for SourceSchema {
51    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        f.debug_struct("SourceSchema")
53            .field("table_name", &self.table_name)
54            .field("primary_key", &self.primary_key)
55            .field("relationships", &self.relationship_names())
56            .field("is_hidden", &self.is_hidden)
57            .field("system", &self.system)
58            .field("sort", &self.sort)
59            .finish()
60    }
61}
62
63/// Whether a fetch starts at its start row or after it.
64#[derive(Clone, Copy, Debug, PartialEq, Eq)]
65pub enum Basis {
66    At,
67    After,
68}
69
70/// Where a fetch starts (`Start` in `operator.ts`).
71#[derive(Clone, Debug)]
72pub struct Start {
73    pub row: Row,
74    pub basis: Basis,
75}
76
77/// `FetchRequest` in `operator.ts`.
78#[derive(Clone, Debug, Default)]
79pub struct FetchRequest {
80    pub constraint: Option<Constraint>,
81    /// Multi-row IN clauses, all ANDed together and with `constraint`.
82    pub multi_constraints: Option<Vec<Vec<Constraint>>>,
83    /// If supplied, `start.row` must have previously been output by fetch or
84    /// push.
85    pub start: Option<Start>,
86    /// Whether to fetch in reverse order of the schema's sort.
87    pub reverse: bool,
88    /// A predicate without subqueries for the source to apply. Only
89    /// `FilterStart` introduces one; pass-through operators keep it.
90    pub filter: Option<Condition>,
91}
92
93/// `InputBase` in `operator.ts`.
94pub trait InputBase {
95    fn get_schema(&self) -> Rc<SourceSchema>;
96    fn destroy(&self);
97}
98
99/// An operator's input: something that can be fetched from and pushes to an
100/// output.
101pub trait Input: InputBase {
102    fn set_output(&self, output: Weak<dyn Output>);
103    fn fetch(&self, req: &FetchRequest) -> NodeStream;
104}
105
106/// An operator's output (`Output` in `operator.ts`).
107///
108/// Pushing is two-phase. `push` propagates a change; once every change of a
109/// source push has propagated, `reconcile` lets bounded operators (`Take`)
110/// refill and push the rows that refill them.
111pub trait Output {
112    fn push(&self, change: Change, pusher: &dyn InputBase);
113    /// Phase two. Sinks can ignore it; operators must forward it.
114    fn reconcile(&self, _pusher: &dyn InputBase) {}
115}
116
117/// An operator in a pipeline: an input to the next and an output of the
118/// previous.
119pub trait Operator: Input + Output {}
120
121impl<T: Input + Output> Operator for T {}
122
123/// Whether `a` and `b` are the same object, as JS's `===` on operators.
124pub fn is_same(a: &dyn InputBase, b: &dyn InputBase) -> bool {
125    std::ptr::addr_eq(a, b)
126}
127
128/// A weak reference that upgrades to nothing, for an input whose output is
129/// not set yet.
130pub fn no_output() -> Weak<dyn Output> {
131    Weak::<ClosureOutput>::new()
132}
133
134/// A weak filter output that upgrades to nothing.
135pub fn no_filter_output() -> Weak<dyn FilterOutput> {
136    Weak::<NoFilterOutput>::new()
137}
138
139/// Never constructed: the type behind [`no_filter_output`].
140pub struct NoFilterOutput;
141
142impl Output for NoFilterOutput {
143    fn push(&self, _: Change, _: &dyn InputBase) {}
144}
145
146impl FilterOutput for NoFilterOutput {
147    fn begin_filter(&self) {}
148    fn filter(&self, _: &Node) -> bool {
149        false
150    }
151    fn end_filter(&self) {}
152}
153
154/// Routes an input's pushes to closures, as JS operators do with object
155/// literals. The operator owns it: inputs hold their outputs weakly.
156pub struct ClosureOutput {
157    on_push: Box<dyn Fn(Change)>,
158    on_reconcile: Box<dyn Fn()>,
159}
160
161impl ClosureOutput {
162    pub fn new(push: impl Fn(Change) + 'static, reconcile: impl Fn() + 'static) -> Rc<Self> {
163        Rc::new(ClosureOutput {
164            on_push: Box::new(push),
165            on_reconcile: Box::new(reconcile),
166        })
167    }
168}
169
170impl Output for ClosureOutput {
171    fn push(&self, change: Change, _pusher: &dyn InputBase) {
172        (self.on_push)(change)
173    }
174
175    fn reconcile(&self, _pusher: &dyn InputBase) {
176        (self.on_reconcile)()
177    }
178}
179
180/// The `where` sub-graph's input (`FilterInput` in `filter-operators.ts`).
181pub trait FilterInput: InputBase {
182    fn set_filter_output(&self, output: Weak<dyn FilterOutput>);
183}
184
185/// The `where` sub-graph's output. Filter operators have no `fetch`; a fetch
186/// through the sub-graph asks `filter` whether each node passes.
187pub trait FilterOutput: Output {
188    fn begin_filter(&self);
189    fn filter(&self, node: &Node) -> bool;
190    fn end_filter(&self);
191}
192
193pub trait FilterOperator: FilterInput + FilterOutput {}
194
195impl<T: FilterInput + FilterOutput> FilterOperator for T {}
196
197/// A source of rows for pipelines (`Source` in `source.ts`).
198pub trait Source {
199    fn table_schema(&self) -> &Table;
200    /// Connects a pipeline. `sort` is `None` for an unordered connection.
201    fn connect(
202        &self,
203        sort: Option<Vec<OrderPart>>,
204        filters: Option<&Condition>,
205        split_edit_keys: Option<&HashSet<String>>,
206    ) -> Result<Rc<dyn SourceInput>, PipelineError>;
207    fn push(&self, change: SourceChange);
208}
209
210/// A source's connection to one pipeline.
211pub trait SourceInput: Input {
212    /// Whether the source applies all of the connection's filters, so no
213    /// `Filter` operators are needed above it.
214    fn fully_applied_filters(&self) -> bool;
215}