Skip to main content

uqa_sql/plan/
retained_arena.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Immutable scalar-query namespaces keep their constructor leases through shared execution scopes.
8
9use super::{QueryPlan, ScalarQueryArena};
10use crate::SQLError;
11use std::sync::Arc;
12use uqa_core::memory::{Produced, ProductionControl};
13
14#[derive(Debug, Clone, Default)]
15pub struct RetainedQueryArena(Storage);
16
17#[derive(Debug, Clone, Default)]
18enum Storage {
19    #[default]
20    Empty,
21    Ordinary(Arc<[QueryPlan]>),
22    Admitted(Arc<Produced<Vec<QueryPlan>>>),
23}
24
25impl RetainedQueryArena {
26    /// Admit a complete private arena before copying any query payload. Clones of the returned owner share that arena without new allocation.
27    pub fn capture(
28        queries: &[QueryPlan],
29        control: &ProductionControl<'_>,
30    ) -> Result<Self, SQLError> {
31        control.check()?;
32        if queries.is_empty() {
33            return Ok(Self::default());
34        }
35        ScalarQueryArena::copy_from(queries, control)?.into_shared(control)
36    }
37
38    fn from_produced(
39        queries: Produced<Vec<QueryPlan>>,
40        control: &ProductionControl<'_>,
41    ) -> Result<Self, SQLError> {
42        control.check()?;
43        if queries.is_empty() {
44            return Ok(Self::default());
45        }
46        Ok(Self(Storage::Admitted(queries.into_shared(control)?)))
47    }
48
49    pub fn reserved_bytes(&self) -> usize {
50        match &self.0 {
51            Storage::Admitted(queries) => queries.reserved_bytes(),
52            Storage::Empty | Storage::Ordinary(_) => 0,
53        }
54    }
55
56    /// Share an admitted arena with another reader, or admit a legacy caller's ordinary input before retaining its private copy.
57    pub fn retain_with_control(&self, control: &ProductionControl<'_>) -> Result<Self, SQLError> {
58        control.check()?;
59        match self.0 {
60            Storage::Ordinary(_) => Self::capture(self, control),
61            Storage::Empty | Storage::Admitted(_) => Ok(self.clone()),
62        }
63    }
64
65    pub fn ptr_eq(&self, other: &Self) -> bool {
66        match (&self.0, &other.0) {
67            (Storage::Empty, Storage::Empty) => true,
68            (Storage::Ordinary(left), Storage::Ordinary(right)) => Arc::ptr_eq(left, right),
69            (Storage::Admitted(left), Storage::Admitted(right)) => Arc::ptr_eq(left, right),
70            _ => false,
71        }
72    }
73}
74
75impl ScalarQueryArena {
76    /// Transfer the arena buffer and its existing payload ownership into shared storage without copying a query or changing its private slot identity.
77    pub fn into_shared(
78        self,
79        control: &ProductionControl<'_>,
80    ) -> Result<RetainedQueryArena, SQLError> {
81        RetainedQueryArena::from_produced(self.finish(control)?, control)
82    }
83}
84
85impl AsRef<[QueryPlan]> for RetainedQueryArena {
86    fn as_ref(&self) -> &[QueryPlan] {
87        match &self.0 {
88            Storage::Empty => &[],
89            Storage::Ordinary(queries) => queries,
90            Storage::Admitted(queries) => queries,
91        }
92    }
93}
94
95impl std::ops::Deref for RetainedQueryArena {
96    type Target = [QueryPlan];
97
98    fn deref(&self) -> &Self::Target {
99        self.as_ref()
100    }
101}
102
103impl<'a> IntoIterator for &'a RetainedQueryArena {
104    type Item = &'a QueryPlan;
105    type IntoIter = std::slice::Iter<'a, QueryPlan>;
106
107    fn into_iter(self) -> Self::IntoIter {
108        self.iter()
109    }
110}
111
112impl From<Vec<QueryPlan>> for RetainedQueryArena {
113    fn from(queries: Vec<QueryPlan>) -> Self {
114        if queries.is_empty() {
115            Self::default()
116        } else {
117            Self(Storage::Ordinary(queries.into()))
118        }
119    }
120}
121
122impl From<Arc<[QueryPlan]>> for RetainedQueryArena {
123    fn from(queries: Arc<[QueryPlan]>) -> Self {
124        Self(Storage::Ordinary(queries))
125    }
126}
127
128impl From<&[QueryPlan]> for RetainedQueryArena {
129    fn from(queries: &[QueryPlan]) -> Self {
130        if queries.is_empty() {
131            Self::default()
132        } else {
133            Self(Storage::Ordinary(queries.into()))
134        }
135    }
136}
137
138#[cfg(test)]
139mod tests;