Skip to main content

uqa_engine/transactions/
completion.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Request completion from the transaction owner's actual publication and rollback boundaries.
8
9use super::{Engine, TransactionStatus};
10
11/// Transaction facts for one admitted host operation. These facts never authorize replay: a message can contain explicit commits, and nontransactional sequence effects survive rollback.
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub enum ExecutionCompletion {
14    /// No transaction completed during a failed operation.
15    None,
16    /// The operation completed its implicit work, or a commit was confirmed before a later failure.
17    Committed,
18    /// The transaction owner confirmed rollback without an intervening commit.
19    RolledBack,
20    /// An unresolved physical or logical completion remains in the session.
21    Pending,
22    /// An explicit or nested transaction remains open, possibly failed.
23    InTransaction,
24    /// The operation crossed both commit and rollback boundaries, or cleanup could not establish one outcome.
25    Unknown,
26}
27
28/// The original native return value or error together with its operation-scoped transaction facts.
29#[derive(Debug)]
30pub struct ExecutionOutcome<T, E> {
31    pub result: Result<T, E>,
32    pub completion: ExecutionCompletion,
33}
34
35/// Constant-size, nontransactional facts. Snapshot/rollback must never rewind completed publication. Saturation deliberately loses precision instead of wrapping into a false absence of events.
36#[derive(Clone, Copy, Default)]
37pub(crate) struct CompletionCounters {
38    committed: u64,
39    rolled_back: u64,
40    unknown: u64,
41}
42
43impl CompletionCounters {
44    fn completion_since(self, before: Self, success: bool) -> ExecutionCompletion {
45        if [self.committed, self.rolled_back, self.unknown].contains(&u64::MAX)
46            || self.unknown != before.unknown
47        {
48            return ExecutionCompletion::Unknown;
49        }
50        match (
51            self.committed != before.committed,
52            self.rolled_back != before.rolled_back,
53        ) {
54            (true, true) => ExecutionCompletion::Unknown,
55            (true, false) => ExecutionCompletion::Committed,
56            (false, true) => ExecutionCompletion::RolledBack,
57            (false, false) if success => ExecutionCompletion::Committed,
58            (false, false) => ExecutionCompletion::None,
59        }
60    }
61}
62
63impl Engine {
64    /// Run one host operation under the session statement gate and report its native completion facts. The operation retains its own admission, execution and recovery owner; this adapter neither starts a transaction nor retries work. Nested native calls contribute to the same interval, while earlier calls and sibling sessions do not. A successful operation without a retained transaction has finished its implicit work, including a read-only evaluation that required no physical transaction.
65    pub fn execute_with_completion<T, E>(
66        &self,
67        operation: impl FnOnce(&Self) -> Result<T, E>,
68    ) -> ExecutionOutcome<T, E> {
69        let _statement = self.lock_statement_gate();
70        let before = *self.session.completion_counters.lock();
71        let result = operation(self);
72        let stack = self.session.transactions.lock();
73        let completion = match stack.last().map(|frame| frame.status) {
74            Some(TransactionStatus::CommitPending(_) | TransactionStatus::RollbackPending(_)) => {
75                ExecutionCompletion::Pending
76            }
77            Some(_) => ExecutionCompletion::InTransaction,
78            None => self
79                .session
80                .completion_counters
81                .lock()
82                .completion_since(before, result.is_ok()),
83        };
84        ExecutionOutcome { result, completion }
85    }
86
87    pub(super) fn record_transaction_completion(&self, completion: ExecutionCompletion) {
88        let mut counters = self.session.completion_counters.lock();
89        let counter = match completion {
90            ExecutionCompletion::Committed => &mut counters.committed,
91            ExecutionCompletion::RolledBack => &mut counters.rolled_back,
92            ExecutionCompletion::Unknown => &mut counters.unknown,
93            _ => unreachable!("only a completed outer transaction publishes an outcome"),
94        };
95        *counter = counter.saturating_add(1);
96    }
97}
98
99#[cfg(test)]
100mod tests;