Skip to main content

uqa_core/memory/
production.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Ordinary and admitted producers share constructors while output and temporary leases stay separate.
8
9use super::{Budgeted, MemoryBudget, MemoryReservation};
10use crate::{CancellationToken, Value, ValueRetentionError};
11
12mod map;
13mod owned;
14mod small_vec;
15mod string;
16mod vec;
17pub use map::ProductionMap;
18pub use owned::OwnedProductionControl;
19pub use small_vec::ProductionSmallVec;
20pub use string::ProductionString;
21pub use vec::ProductionVec;
22
23/// Allocation and cancellation inputs borrowed for one production call. An ordinary call has no allowance or cancellation scope; a controlled call preserves both the original retained owner and the invoking reader.
24#[derive(Debug, Clone, Copy)]
25pub struct ProductionControl<'a> {
26    budget: Option<&'a MemoryBudget>,
27    original: Option<&'a CancellationToken>,
28    invoking: Option<&'a CancellationToken>,
29}
30
31impl<'a> ProductionControl<'a> {
32    /// Bridge the existing copy API's allowance; its caller-owned cancellation callback remains active in the copier.
33    pub(crate) fn with_budget(budget: &'a MemoryBudget) -> Self {
34        Self {
35            budget: Some(budget),
36            original: None,
37            invoking: None,
38        }
39    }
40
41    pub const fn uncontrolled() -> Self {
42        Self {
43            budget: None,
44            original: None,
45            invoking: None,
46        }
47    }
48
49    pub fn new(
50        budget: &'a MemoryBudget,
51        original: &'a CancellationToken,
52        invoking: &'a CancellationToken,
53    ) -> Self {
54        Self {
55            budget: Some(budget),
56            original: Some(original),
57            invoking: Some(invoking),
58        }
59    }
60
61    pub fn budget(&self) -> Option<&'a MemoryBudget> {
62        self.budget
63    }
64
65    pub fn check_cancellation(&self) -> Result<(), crate::QueryCancelled> {
66        if let Some(original) = self.original {
67            original.check()?;
68        }
69        if let Some(invoking) = self.invoking {
70            invoking.check()?;
71        }
72        Ok(())
73    }
74
75    pub fn check(&self) -> Result<(), ValueRetentionError> {
76        self.check_cancellation().map_err(Into::into)
77    }
78
79    pub fn empty_reservation(&self) -> Option<MemoryReservation> {
80        self.budget.map(MemoryBudget::empty_reservation)
81    }
82
83    /// Admit an explicitly known allocation layout before its constructor runs.
84    pub fn reserve(&self, bytes: usize) -> Result<Option<MemoryReservation>, ValueRetentionError> {
85        self.check()?;
86        self.budget
87            .map(|budget| budget.reserve(bytes).map_err(Into::into))
88            .transpose()
89    }
90
91    /// Transfer two leases for allocations already owned by the same composite result. This does not produce, copy or replace a value.
92    pub fn combine(
93        &self,
94        left: Option<MemoryReservation>,
95        right: Option<MemoryReservation>,
96    ) -> Option<MemoryReservation> {
97        self.assert_owner(left.as_ref());
98        self.assert_owner(right.as_ref());
99        match (left, right) {
100            (Some(mut left), Some(right)) => {
101                left.absorb(right);
102                Some(left)
103            }
104            (None, None) => None,
105            _ => unreachable!("production ownership modes were checked"),
106        }
107    }
108
109    /// Associate a value with leases acquired by its constructors. Every owned allocation must already belong to the supplied reservation. The explicit pair prevents a representation-changing closure from silently introducing new payloads; callers must construct and admit those payloads at their owner.
110    pub fn finish<T>(
111        &self,
112        value: T,
113        memory: Option<MemoryReservation>,
114    ) -> Result<Produced<T>, ValueRetentionError> {
115        let output = Produced { value, memory };
116        self.assert_owner(output.memory.as_ref());
117        self.check()?;
118        Ok(output)
119    }
120
121    /// Accept a completed value from an external producer whose construction is outside this resource scope. This admission boundary retains its exposed owned capacities without copying; built-in constructors must instead reserve before allocating. The value precedes its accumulating lease on every error path.
122    pub fn retain_external_value(
123        &self,
124        value: Value,
125    ) -> Result<Produced<Value>, ValueRetentionError> {
126        let mut output = Produced {
127            value,
128            memory: self.empty_reservation(),
129        };
130        self.check()?;
131        if let Some(budget) = self.budget {
132            let memory = output
133                .memory
134                .as_mut()
135                .expect("controlled external value owner");
136            output.value.visit_retained_payload_with_check(
137                budget,
138                || self.check_cancellation(),
139                |bytes| memory.grow(bytes),
140            )?;
141        }
142        self.check()?;
143        Ok(output)
144    }
145
146    pub fn copy_value(&self, value: &Value) -> Result<Produced<Value>, ValueRetentionError> {
147        self.check()?;
148        let result = match self.budget {
149            Some(budget) => Produced::from(value.clone_budgeted_with_check(budget, || {
150                if let Some(original) = self.original {
151                    original.check()?;
152                }
153                if let Some(invoking) = self.invoking {
154                    invoking.check()?;
155                }
156                Ok(())
157            })?),
158            None => Produced {
159                value: value.clone(),
160                memory: None,
161            },
162        };
163        self.check()?;
164        Ok(result)
165    }
166
167    pub fn copy_text(&self, text: &str) -> Result<Produced<String>, ValueRetentionError> {
168        self.check()?;
169        let mut output = ProductionString::new(*self);
170        output.reserve(text.len())?;
171        output.push_str(text)?;
172        output.finish()
173    }
174
175    pub fn format(
176        &self,
177        arguments: std::fmt::Arguments<'_>,
178    ) -> Result<Produced<String>, ValueRetentionError> {
179        use std::fmt::Write;
180        self.check()?;
181        let mut output = ProductionString::new(*self);
182        let formatted = output.write_fmt(arguments);
183        let result = output.finish()?;
184        assert!(
185            formatted.is_ok(),
186            "formatter failed without a production error"
187        );
188        Ok(result)
189    }
190
191    fn assert_owner(&self, memory: Option<&MemoryReservation>) {
192        match (self.budget, memory) {
193            (Some(budget), Some(memory)) => assert!(
194                budget.shares_allowance(memory.budget()),
195                "different production allowance"
196            ),
197            (None, None) => {}
198            _ => panic!("controlled and uncontrolled production ownership must not be mixed"),
199        }
200    }
201}
202
203/// A produced value with its existing controlled lease, or an explicit ordinary result. There is no mutable dereference or generic map operation that could replace it with newly allocated, unadmitted payloads.
204#[derive(Debug)]
205pub struct Produced<T> {
206    value: T,
207    memory: Option<MemoryReservation>,
208}
209
210impl<T> Produced<T> {
211    pub fn reserved_bytes(&self) -> usize {
212        self.memory.as_ref().map_or(0, MemoryReservation::bytes)
213    }
214
215    /// Share an immutable result and its existing lease. The shared payload is admitted before allocation; reference-count bookkeeping is outside the payload allowance.
216    pub fn into_shared(
217        self,
218        control: &ProductionControl<'_>,
219    ) -> Result<std::sync::Arc<Self>, ValueRetentionError> {
220        control.assert_owner(self.memory.as_ref());
221        let header = control.reserve(size_of::<Self>())?;
222        let (value, memory) = self.into_parts();
223        Ok(std::sync::Arc::new(
224            control.finish(value, control.combine(memory, header))?,
225        ))
226    }
227
228    /// Transfer the explicit value/lease pair to its next allocation owner. The caller must retain the lease until those allocations are freed or handed off under a documented legacy API boundary.
229    pub fn into_parts(self) -> (T, Option<MemoryReservation>) {
230        (self.value, self.memory)
231    }
232
233    /// Extract an ordinary result. A controlled result is returned unchanged instead of silently releasing its lease.
234    pub fn into_uncontrolled(self) -> Result<T, Self> {
235        if self.memory.is_some() {
236            return Err(self);
237        }
238        Ok(self.value)
239    }
240
241    /// Preserve a controlled result in the existing budgeted carrier. An ordinary result is returned unchanged instead of being retroactively charged.
242    pub fn into_budgeted(self) -> Result<Budgeted<T>, Self> {
243        let Some(memory) = self.memory else {
244            return Err(self);
245        };
246        Ok(Budgeted::new(self.value, memory))
247    }
248}
249
250impl<T: Copy> Produced<Vec<T>> {
251    /// Mutate fixed-length scratch slots without changing capacity or introducing owned payloads. The Copy bound excludes allocation-owning values and the slice cannot grow the admitted container.
252    pub fn as_mut_slice(&mut self) -> &mut [T] {
253        self.value.as_mut_slice()
254    }
255}
256
257impl<T> From<Budgeted<T>> for Produced<T> {
258    fn from(value: Budgeted<T>) -> Self {
259        let (value, memory) = value.into_parts();
260        Self {
261            value,
262            memory: Some(memory),
263        }
264    }
265}
266
267impl<T> std::ops::Deref for Produced<T> {
268    type Target = T;
269    fn deref(&self) -> &T {
270        &self.value
271    }
272}
273
274impl<T: PartialEq> PartialEq for Produced<T> {
275    fn eq(&self, other: &Self) -> bool {
276        self.value == other.value
277    }
278}
279
280impl<T: Eq> Eq for Produced<T> {}
281impl<T: Ord> PartialOrd for Produced<T> {
282    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
283        Some(self.cmp(other))
284    }
285}
286impl<T: Ord> Ord for Produced<T> {
287    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
288        self.value.cmp(&other.value)
289    }
290}
291impl std::borrow::Borrow<str> for Produced<String> {
292    fn borrow(&self) -> &str {
293        &self.value
294    }
295}
296impl std::borrow::Borrow<String> for Produced<String> {
297    fn borrow(&self) -> &String {
298        &self.value
299    }
300}
301
302#[cfg(test)]
303mod tests;