Skip to main content

uqa_execution/statement/batch/
context.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Deferred execution inputs and session-owned cache, transaction and lock state.
8
9use crate::{
10    row_locks::retry_cache::RowLockRetryCache,
11    statement::{
12        context::{StatementEffects, StatementExecutionInputs, StatementRuntime},
13        transactions::StatementTransactions,
14    },
15};
16use std::sync::Arc;
17use uqa_sql::{
18    ast::TransactionStmt,
19    plan::{AggregateClassifier, ExecutablePlanOptimizer},
20    SQLError, SQLParam, Statement,
21};
22
23/// Cancel the statement that begins now once the session's `statement_timeout` passes, as `PostgreSQL`'s `start_xact_command` enables the timeout for each statement of a query and `finish_xact_command` disables it; the returned deadline disarms when the statement ends.
24pub fn statement_deadline<S: Clone + 'static>(
25    context: &BatchExecutionContext<'_, S>,
26) -> Option<uqa_core::CancellationDeadline> {
27    let timeout = context.statements.statement_timeout()?;
28    Some(
29        context
30            .runtime
31            .cancellation
32            .deadline(timeout, uqa_core::CancellationReason::StatementTimeout),
33    )
34}
35
36/// Owned cache contents after the session has validated its catalog epochs.
37pub struct CachedStatement {
38    pub statement: Arc<Statement>,
39    pub logical_plan: Option<uqa_sql::plan::SharedExecutablePlan>,
40    pub optimized_plan: Option<uqa_sql::plan::SharedExecutablePlan>,
41    pub parser: uqa_sql::parser::ParserMetadata,
42}
43
44impl CachedStatement {
45    /// Optimized entries were analyzed without parameters; any supplied inputs require native binding, including inputs the query does not reference.
46    pub(crate) fn optimized_plan_for(
47        &self,
48        params: &[SQLParam],
49    ) -> Option<&uqa_sql::plan::SharedExecutablePlan> {
50        if params.is_empty() {
51            self.optimized_plan.as_ref()
52        } else {
53            None
54        }
55    }
56}
57
58pub trait StatementCache {
59    /// Retire the preliminary executable once planning owns its input. Parsed syntax and matching analyzed inputs remain available for subsequent invocations.
60    fn retire_sql_logical_plan(
61        &self,
62        _sql: &str,
63        _control: &uqa_core::memory::ProductionControl<'_>,
64    ) -> Result<(), SQLError> {
65        Ok(())
66    }
67
68    /// Look up analysis after the statement's snapshot and writer refreshes, with current catalog and scope validation. Ordinary cache implementations may decline this capability.
69    fn cached_sql_analysis(
70        &self,
71        _sql: &str,
72    ) -> Option<uqa_sql::binding::statements::AnalyzedStatement> {
73        None
74    }
75    fn cache_sql_analysis(
76        &self,
77        _sql: &str,
78        _analysis: Option<uqa_sql::binding::statements::AnalyzedStatement>,
79        _control: &uqa_core::memory::ProductionControl<'_>,
80    ) -> Result<(), SQLError> {
81        Ok(())
82    }
83
84    fn cached_sql_statement(&self, sql: &str) -> Option<CachedStatement>;
85    fn cache_sql_statement(
86        &self,
87        sql: &str,
88        statement: Arc<Statement>,
89        logical_plan: Option<uqa_sql::plan::SharedExecutablePlan>,
90        parser: uqa_sql::parser::ParserMetadata,
91        control: &uqa_core::memory::ProductionControl<'_>,
92    ) -> Result<(), SQLError>;
93    fn cache_optimized_sql_plan(
94        &self,
95        sql: &str,
96        optimized_plan: uqa_sql::plan::SharedExecutablePlan,
97        control: &uqa_core::memory::ProductionControl<'_>,
98    ) -> Result<(), SQLError>;
99}
100
101/// Transaction state changes requested at the native scheduler's boundaries.
102pub trait BatchTransactions: StatementTransactions {
103    /// Refresh an idle session before reading its statement cache. An active transaction retains its view until its admitted statement selects a snapshot, including ownership of refresh failure.
104    fn refresh_idle_statement_view(&self) -> Result<(), SQLError>;
105    fn begin_simple_query_transaction(&self) -> Result<(), SQLError>;
106    fn promote_simple_query_transaction(&self) -> Result<(), SQLError>;
107    fn run_transaction_statement(&self, statement: TransactionStmt) -> Result<(), SQLError>;
108    /// Admit and run one operation in the existing transaction. The owner rejects failed or unresolved frames before invoking the callback, invokes it exactly once on admission, and owns error and unwind cleanup.
109    fn with_active_transaction(
110        &self,
111        operation: &mut dyn FnMut() -> Result<(), SQLError>,
112    ) -> Result<(), SQLError>;
113    fn prepare_explicit_statement_snapshot(&self, sets_snapshot: bool) -> Result<(), SQLError>;
114    fn prepare_explicit_transaction_writer(&self) -> Result<bool, SQLError>;
115    fn begin_implicit_statement_transaction(&self, read_only: bool) -> Result<(), SQLError>;
116}
117
118pub(in crate::statement) fn with_active_transaction<T>(
119    transactions: &dyn BatchTransactions,
120    operation: impl FnOnce() -> Result<T, SQLError>,
121) -> Result<T, SQLError> {
122    let mut operation = Some(operation);
123    let mut result = None;
124    transactions.with_active_transaction(&mut || {
125        let operation = operation.take().ok_or_else(|| {
126            SQLError::Internal("transaction owner invoked its operation more than once".into())
127        })?;
128        result = Some(operation()?);
129        Ok(())
130    })?;
131    result.ok_or_else(|| {
132        SQLError::Internal("transaction owner did not invoke its admitted operation".into())
133    })
134}
135
136/// Retain the session's row-lock frame until the current loop iteration exits.
137pub trait RowLockStatementGuard {}
138
139pub trait BatchRowLocks {
140    fn begin_row_lock_statement(&self) -> Box<dyn RowLockStatementGuard + '_>;
141    fn statement_row_lock_cache(&self) -> Result<Arc<RowLockRetryCache>, SQLError>;
142}
143
144pub struct BatchExecutionContext<'a, S: Clone + 'static> {
145    pub runtime: StatementRuntime<'a>,
146    pub persistent_backend: bool,
147    pub statements: &'a dyn StatementExecutionInputs<S>,
148    pub cache: &'a dyn StatementCache,
149    pub aggregates: &'a dyn AggregateClassifier,
150    pub effects: &'a dyn StatementEffects,
151    pub planning: &'a dyn ExecutablePlanOptimizer,
152    pub transactions: &'a dyn BatchTransactions,
153    pub row_locks: &'a dyn BatchRowLocks,
154}