Skip to main content

uqa_sql/plan/
memory.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Borrowed observation of the executable's live, directly owned storage.
8
9use super::{CommandPlan, UnifiedPlan};
10use crate::{result::explain::ExplainPlanningMemory, SQLError};
11use uqa_core::memory::{
12    AllocationObserver, AllocationUsage, ObserveAllocations, ProductionControl,
13};
14use uqa_core::ValueRetentionError;
15
16mod assignments;
17mod command;
18mod metadata;
19mod query;
20mod scalar;
21mod source;
22#[cfg(test)]
23mod tests;
24
25impl UnifiedPlan {
26    /// Observe initialized bytes and exposed allocation capacity before execution. Shared literal owners are counted once without decoding. Immutable analysis/catalog descriptors, opaque dependency storage and allocator bookkeeping remain outside the executable's storage. This neither evaluates expressions nor reserves the already-produced plan again.
27    pub fn planning_memory(
28        &self,
29        control: &ProductionControl<'_>,
30    ) -> Result<ExplainPlanningMemory, SQLError> {
31        let usage = AllocationUsage::measure(self, control)?;
32        Ok(ExplainPlanningMemory {
33            used_bytes: usage.used_bytes,
34            allocated_bytes: usage.allocated_bytes,
35        })
36    }
37}
38
39impl ObserveAllocations for CommandPlan {
40    fn observe_allocations<'a>(
41        &'a self,
42        observer: &mut AllocationObserver<'a, '_>,
43    ) -> Result<(), ValueRetentionError> {
44        match self {
45            Self::Insert(plan) => observer.child(plan),
46            Self::Update(plan) => observer.child(plan),
47            Self::Delete(plan) => observer.child(plan),
48            Self::Merge(plan) => observer.child(plan),
49            _ => Err(ValueRetentionError::Malformed {
50                kind: "executable plan",
51                reason: "utility command has a separate planning boundary".into(),
52            }),
53        }
54    }
55}
56
57impl ObserveAllocations for crate::catalog::roles::RoleReference {
58    fn observe_allocations<'a>(
59        &'a self,
60        observer: &mut AllocationObserver<'a, '_>,
61    ) -> Result<(), ValueRetentionError> {
62        match self {
63            Self::Named(name) => observer.child(name),
64            // The immutable catalog binding retains its own allocation owner.
65            Self::Bound(_) => Ok(()),
66        }
67    }
68}