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    /// Whether the output has a phase two: false for a sink whose JS
116    /// counterpart has no `reconcile`, such as a view, which pushes timed
117    /// for the inspector skip (`MeasurePushOperator`).
118    fn has_reconcile(&self) -> bool {
119        true
120    }
121}
122
123/// An operator in a pipeline: an input to the next and an output of the
124/// previous.
125pub trait Operator: Input + Output {}
126
127impl<T: Input + Output> Operator for T {}
128
129/// Whether `a` and `b` are the same object, as JS's `===` on operators.
130pub fn is_same(a: &dyn InputBase, b: &dyn InputBase) -> bool {
131    std::ptr::addr_eq(a, b)
132}
133
134/// A weak reference that upgrades to nothing, for an input whose output is
135/// not set yet.
136pub fn no_output() -> Weak<dyn Output> {
137    Weak::<ClosureOutput>::new()
138}
139
140/// A weak filter output that upgrades to nothing.
141pub fn no_filter_output() -> Weak<dyn FilterOutput> {
142    Weak::<NoFilterOutput>::new()
143}
144
145/// Never constructed: the type behind [`no_filter_output`].
146pub struct NoFilterOutput;
147
148impl Output for NoFilterOutput {
149    fn push(&self, _: Change, _: &dyn InputBase) {}
150}
151
152impl FilterOutput for NoFilterOutput {
153    fn begin_filter(&self) {}
154    fn filter(&self, _: &Node) -> bool {
155        false
156    }
157    fn end_filter(&self) {}
158}
159
160/// Routes an input's pushes to closures, as JS operators do with object
161/// literals. The operator owns it: inputs hold their outputs weakly.
162pub struct ClosureOutput {
163    on_push: Box<dyn Fn(Change)>,
164    on_reconcile: Box<dyn Fn()>,
165}
166
167impl ClosureOutput {
168    pub fn new(push: impl Fn(Change) + 'static, reconcile: impl Fn() + 'static) -> Rc<Self> {
169        Rc::new(ClosureOutput {
170            on_push: Box::new(push),
171            on_reconcile: Box::new(reconcile),
172        })
173    }
174}
175
176impl Output for ClosureOutput {
177    fn push(&self, change: Change, _pusher: &dyn InputBase) {
178        (self.on_push)(change)
179    }
180
181    fn reconcile(&self, _pusher: &dyn InputBase) {
182        (self.on_reconcile)()
183    }
184}
185
186/// The `where` sub-graph's input (`FilterInput` in `filter-operators.ts`).
187pub trait FilterInput: InputBase {
188    fn set_filter_output(&self, output: Weak<dyn FilterOutput>);
189}
190
191/// The `where` sub-graph's output. Filter operators have no `fetch`; a fetch
192/// through the sub-graph asks `filter` whether each node passes.
193pub trait FilterOutput: Output {
194    fn begin_filter(&self);
195    fn filter(&self, node: &Node) -> bool;
196    fn end_filter(&self);
197}
198
199pub trait FilterOperator: FilterInput + FilterOutput {}
200
201impl<T: FilterInput + FilterOutput> FilterOperator for T {}
202
203/// A source of rows for pipelines (`Source` in `source.ts`).
204pub trait Source {
205    fn table_schema(&self) -> &Table;
206    /// Connects a pipeline. `sort` is `None` for an unordered connection.
207    fn connect(
208        &self,
209        sort: Option<Vec<OrderPart>>,
210        filters: Option<&Condition>,
211        split_edit_keys: Option<&HashSet<String>>,
212    ) -> Result<Rc<dyn SourceInput>, PipelineError>;
213    fn push(&self, change: SourceChange);
214}
215
216/// A source's connection to one pipeline.
217pub trait SourceInput: Input {
218    /// Whether the source applies all of the connection's filters, so no
219    /// `Filter` operators are needed above it.
220    fn fully_applied_filters(&self) -> bool;
221}