Skip to main content

uqa_execution/query/statement/
directional.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Persistent directional query traversal over a session-owned worker task.
8use crate::query::consumer::{QueryConsumerControl, QueryRowConsumer};
9use crate::query::diagnostics::{InvocationRequest, QueryDiagnostics, RequestScope};
10use crate::{
11    BackwardScanSupport, Batch, ExecError, ExecResult, PhysicalOperator, PhysicalRow,
12    PhysicalScanDirection, RowSchema,
13};
14use std::{cell::Cell, rc::Rc};
15use uqa_core::{
16    memory::{MemoryReservation, ProductionControl},
17    Value,
18};
19use uqa_sql::SQLError;
20
21enum DirectionalPlanRequest {
22    Step(PhysicalScanDirection, Option<InvocationRequest>),
23    Rewind(Option<InvocationRequest>),
24    Close,
25}
26
27enum DirectionalPlanResponse {
28    Row(PhysicalRow),
29    Eof,
30    Rewound,
31    Error(SQLError),
32}
33
34struct DirectionalPlanWorker {
35    requests: std::sync::mpsc::Sender<DirectionalPlanRequest>,
36    responses: std::sync::mpsc::Receiver<DirectionalPlanResponse>,
37    join: Option<std::thread::JoinHandle<()>>,
38}
39
40impl Drop for DirectionalPlanWorker {
41    fn drop(&mut self) {
42        let _ = self.requests.send(DirectionalPlanRequest::Close);
43        if let Some(join) = self.join.take() {
44            let _ = join.join();
45        }
46    }
47}
48
49struct DirectionalPlanRowConsumer {
50    diagnostics: RequestScope,
51    requests: std::sync::mpsc::Receiver<DirectionalPlanRequest>,
52    responses: std::sync::mpsc::Sender<DirectionalPlanResponse>,
53    direction: Cell<PhysicalScanDirection>,
54    closed: Cell<bool>,
55    schema: RowSchema,
56}
57
58impl DirectionalPlanRowConsumer {
59    fn wait_for_request(&self) -> Result<QueryConsumerControl, SQLError> {
60        match self.requests.recv() {
61            Ok(DirectionalPlanRequest::Step(direction, diagnostics)) => {
62                self.diagnostics.replace(diagnostics);
63                self.direction.set(direction);
64                Ok(QueryConsumerControl::Continue)
65            }
66            Ok(DirectionalPlanRequest::Rewind(diagnostics)) => {
67                self.diagnostics.replace(diagnostics);
68                Ok(QueryConsumerControl::Rewind)
69            }
70            Ok(DirectionalPlanRequest::Close) | Err(_) => {
71                self.closed.set(true);
72                Ok(QueryConsumerControl::Stop)
73            }
74        }
75    }
76
77    fn respond_and_wait(
78        &self,
79        response: DirectionalPlanResponse,
80    ) -> Result<QueryConsumerControl, SQLError> {
81        if self.responses.send(response).is_err() {
82            self.closed.set(true);
83            return Ok(QueryConsumerControl::Stop);
84        }
85        self.wait_for_request()
86    }
87}
88
89impl QueryRowConsumer for DirectionalPlanRowConsumer {
90    fn begin(&self, columns: &[String], _schema: &RowSchema) -> Result<(), SQLError> {
91        if columns.len() != self.schema.len() {
92            return Err(SQLError::TypeMismatch(format!(
93                "directional set-operation branch width {} does not match declared width {}",
94                columns.len(),
95                self.schema.len()
96            )));
97        }
98        Ok(())
99    }
100
101    fn consume(&self, row: crate::OwnedPhysicalRow) -> Result<QueryConsumerControl, SQLError> {
102        let view = row.view();
103        let values = (0..self.schema.len())
104            .map(|position| view.value_at(position).cloned().unwrap_or(Value::Null))
105            .collect();
106        self.respond_and_wait(DirectionalPlanResponse::Row(PhysicalRow::from_values(
107            values,
108        )))
109    }
110
111    fn uses_directional_scan(&self) -> bool {
112        true
113    }
114
115    fn scan_direction(&self) -> PhysicalScanDirection {
116        self.direction.get()
117    }
118
119    fn direction_exhausted(&self) -> Result<QueryConsumerControl, SQLError> {
120        self.respond_and_wait(DirectionalPlanResponse::Eof)
121    }
122
123    fn rewound(&self) -> Result<QueryConsumerControl, SQLError> {
124        self.respond_and_wait(DirectionalPlanResponse::Rewound)
125    }
126}
127
128/// Run one query in the session state prepared by the caller. The session owns its statement gate and snapshot lifetime.
129pub trait DirectionalQueryTask: Send {
130    fn execute(self: Box<Self>, consumer: Rc<dyn QueryRowConsumer>) -> Result<(), SQLError>;
131}
132
133pub struct DirectionalQueryPlanOperator {
134    diagnostics: Option<QueryDiagnostics>,
135    schema: RowSchema,
136    support: BackwardScanSupport,
137    input: Option<Box<dyn DirectionalQueryTask>>,
138    worker: Option<DirectionalPlanWorker>,
139    _memory: Option<MemoryReservation>,
140}
141
142impl DirectionalQueryPlanOperator {
143    pub fn new_with_control(
144        input: Box<dyn DirectionalQueryTask>,
145        support: BackwardScanSupport,
146        schema: RowSchema,
147        control: &ProductionControl<'_>,
148    ) -> Result<Box<Self>, SQLError> {
149        let memory = control.reserve(size_of::<Self>())?;
150        Ok(Box::new(Self {
151            diagnostics: None,
152            schema,
153            support,
154            input: Some(input),
155            worker: None,
156            _memory: memory,
157        }))
158    }
159
160    #[must_use]
161    pub fn with_diagnostics(mut self: Box<Self>, diagnostics: QueryDiagnostics) -> Box<Self> {
162        self.diagnostics = Some(diagnostics);
163        self
164    }
165
166    fn start_worker(&mut self, direction: PhysicalScanDirection) -> ExecResult<()> {
167        let input = self
168            .input
169            .take()
170            .ok_or_else(|| ExecError::Other("directional query branch is closed".into()))?;
171        let (request_tx, request_rx) = std::sync::mpsc::channel();
172        let (response_tx, response_rx) = std::sync::mpsc::channel();
173        let schema = self.schema.clone();
174        let diagnostics = self.diagnostics.as_ref().map(QueryDiagnostics::request);
175        let thread_context = crate::statement::thread_context::StatementThreadContext::current();
176        let join = std::thread::spawn({
177            move || {
178                let _statement_thread = thread_context.enter();
179                let consumer = Rc::new(DirectionalPlanRowConsumer {
180                    diagnostics: QueryDiagnostics::request_scope(diagnostics),
181                    requests: request_rx,
182                    responses: response_tx.clone(),
183                    direction: Cell::new(direction),
184                    closed: Cell::new(false),
185                    schema,
186                });
187                let result = input.execute(consumer.clone());
188                if let Err(error) = result {
189                    if !consumer.closed.get() {
190                        let _ = response_tx.send(DirectionalPlanResponse::Error(error));
191                    }
192                } else if !consumer.closed.get() {
193                    let _ = response_tx.send(DirectionalPlanResponse::Error(SQLError::Internal(
194                        "directional query branch stopped without a close request".into(),
195                    )));
196                }
197            }
198        });
199        self.worker = Some(DirectionalPlanWorker {
200            requests: request_tx,
201            responses: response_rx,
202            join: Some(join),
203        });
204        Ok(())
205    }
206
207    fn worker(&self) -> ExecResult<&DirectionalPlanWorker> {
208        self.worker
209            .as_ref()
210            .ok_or_else(|| ExecError::Other("directional query branch is closed".into()))
211    }
212
213    fn request(&self, request: DirectionalPlanRequest) -> ExecResult<DirectionalPlanResponse> {
214        let worker = self.worker()?;
215        worker.requests.send(request).map_err(|_| {
216            ExecError::Other("directional query branch stopped before a request".into())
217        })?;
218        worker.responses.recv().map_err(|_| {
219            ExecError::Other("directional query branch stopped without a response".into())
220        })
221    }
222
223    fn step(&mut self, direction: PhysicalScanDirection) -> ExecResult<DirectionalPlanResponse> {
224        if self.worker.is_none() {
225            self.start_worker(direction)?;
226            return self.worker()?.responses.recv().map_err(|_| {
227                ExecError::Other("directional query branch stopped without a response".into())
228            });
229        }
230        self.request(DirectionalPlanRequest::Step(
231            direction,
232            self.diagnostics.as_ref().map(QueryDiagnostics::request),
233        ))
234    }
235}
236
237impl PhysicalOperator for DirectionalQueryPlanOperator {
238    fn row_schema(&self) -> &RowSchema {
239        &self.schema
240    }
241
242    fn backward_scan_support(&self) -> BackwardScanSupport {
243        self.support
244    }
245
246    fn open(&mut self) -> ExecResult<()> {
247        if self.input.is_some() || self.worker.is_some() {
248            Ok(())
249        } else {
250            Err(ExecError::Other(
251                "directional query branch is closed".into(),
252            ))
253        }
254    }
255
256    fn next(&mut self) -> ExecResult<Option<Batch>> {
257        self.next_direction(PhysicalScanDirection::Forward)
258    }
259
260    fn next_direction(&mut self, direction: PhysicalScanDirection) -> ExecResult<Option<Batch>> {
261        match self.step(direction)? {
262            DirectionalPlanResponse::Row(row) => Ok(Some(Batch::from_physical_rows(
263                self.schema.clone(),
264                vec![row],
265            ))),
266            DirectionalPlanResponse::Eof => Ok(None),
267            DirectionalPlanResponse::Error(error) => Err(ExecError::SQL(error)),
268            DirectionalPlanResponse::Rewound => Err(ExecError::Other(
269                "directional query branch returned an invalid row response".into(),
270            )),
271        }
272    }
273
274    fn rewind(&mut self) -> ExecResult<()> {
275        if self.input.is_some() {
276            return Ok(());
277        }
278        match self.request(DirectionalPlanRequest::Rewind(
279            self.diagnostics.as_ref().map(QueryDiagnostics::request),
280        ))? {
281            DirectionalPlanResponse::Rewound => Ok(()),
282            DirectionalPlanResponse::Error(error) => Err(ExecError::SQL(error)),
283            DirectionalPlanResponse::Row(_) | DirectionalPlanResponse::Eof => {
284                Err(ExecError::Other(
285                    "directional query branch returned an invalid rewind response".into(),
286                ))
287            }
288        }
289    }
290
291    fn close(&mut self) -> ExecResult<()> {
292        self.worker = None;
293        self.input = None;
294        Ok(())
295    }
296}
297
298#[cfg(test)]
299mod tests;