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, UnifiedPlan},
20    SQLError, 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: Arc<UnifiedPlan>,
40    pub optimized_plan: Option<Arc<UnifiedPlan>>,
41    pub parser: uqa_sql::parser::ParserMetadata,
42}
43
44pub trait StatementCache {
45    /// Look up analysis after the statement's snapshot and writer refreshes, with current catalog and scope validation. Ordinary cache implementations may decline this capability.
46    fn cached_sql_analysis(
47        &self,
48        _sql: &str,
49    ) -> Option<Arc<uqa_sql::binding::statements::AnalyzedStatement>> {
50        None
51    }
52    fn cache_sql_analysis(
53        &self,
54        _sql: &str,
55        _analysis: Option<Arc<uqa_sql::binding::statements::AnalyzedStatement>>,
56    ) {
57    }
58
59    fn cached_sql_statement(&self, sql: &str) -> Option<CachedStatement>;
60    fn cache_sql_statement(
61        &self,
62        sql: String,
63        statement: Arc<Statement>,
64        logical_plan: Arc<UnifiedPlan>,
65        parser: uqa_sql::parser::ParserMetadata,
66    );
67    fn cache_optimized_sql_plan(&self, sql: &str, optimized_plan: Arc<UnifiedPlan>);
68}
69
70/// Transaction state changes requested at the native scheduler's boundaries.
71pub trait BatchTransactions: StatementTransactions {
72    fn begin_simple_query_transaction(&self) -> Result<(), SQLError>;
73    fn promote_simple_query_transaction(&self) -> Result<(), SQLError>;
74    fn run_transaction_statement(&self, statement: TransactionStmt) -> Result<(), SQLError>;
75    fn ensure_transaction_usable(&self) -> Result<(), SQLError>;
76    fn prepare_explicit_statement_snapshot(&self, sets_snapshot: bool) -> Result<(), SQLError>;
77    fn prepare_explicit_transaction_writer(&self) -> Result<bool, SQLError>;
78    fn begin_implicit_statement_transaction(&self, read_only: bool) -> Result<(), SQLError>;
79}
80
81/// Retain the session's row-lock frame until the current loop iteration exits.
82pub trait RowLockStatementGuard {}
83
84pub trait BatchRowLocks {
85    fn begin_row_lock_statement(&self) -> Box<dyn RowLockStatementGuard + '_>;
86    fn statement_row_lock_cache(&self) -> Result<Arc<RowLockRetryCache>, SQLError>;
87}
88
89pub struct BatchExecutionContext<'a, S: Clone + 'static> {
90    pub runtime: StatementRuntime<'a>,
91    pub persistent_backend: bool,
92    pub statements: &'a dyn StatementExecutionInputs<S>,
93    pub cache: &'a dyn StatementCache,
94    pub aggregates: &'a dyn AggregateClassifier,
95    pub effects: &'a dyn StatementEffects,
96    pub planning: &'a dyn ExecutablePlanOptimizer,
97    pub transactions: &'a dyn BatchTransactions,
98    pub row_locks: &'a dyn BatchRowLocks,
99}