Skip to main content

uqa_sql/expr/regex/
cache.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Session-owned compiled patterns. Matching never holds the cache lock or borrows another invocation's cancellation or scratch allowance.
8
9use std::{
10    cell::RefCell,
11    marker::PhantomData,
12    rc::Rc,
13    sync::{Arc, Mutex},
14};
15use uqa_core::memory::{BudgetedString, BudgetedVec, MemoryBudget, MemoryError, MemoryReservation};
16use uqa_pg_regex::{CompileFlags, RegexResources, RetainedRegex};
17
18const CAPACITY: usize = 32;
19
20pub(super) struct RetainedAllowance(pub(super) Option<MemoryReservation>);
21
22impl RegexResources for RetainedAllowance {
23    fn reserve(&mut self, _: usize) -> bool {
24        unreachable!("retained hooks only release compiled memory")
25    }
26    fn release(&mut self, bytes: usize) {
27        if let Some(lease) = self.0.as_mut() {
28            drop(lease.split(bytes));
29        }
30    }
31    fn cancel_requested(&mut self) -> bool {
32        false
33    }
34    fn stack_too_deep(&mut self, _: usize) -> bool {
35        false
36    }
37}
38
39pub(super) struct Entry {
40    pub(super) pattern: BudgetedString,
41    pub(super) flags: CompileFlags,
42    pub(super) collation: u32,
43    pub(super) generation: u64,
44    pub(super) regex: RetainedRegex<RetainedAllowance>,
45}
46
47pub(super) struct Admission {
48    pub(super) pattern: BudgetedString,
49    pub(super) generation: u64,
50    pub(super) memory: Option<MemoryReservation>,
51}
52
53impl Entry {
54    fn matches(&self, pattern: &str, flags: CompileFlags, collation: u32) -> bool {
55        &*self.pattern == pattern && self.flags == flags && self.collation == collation
56    }
57}
58
59#[derive(Default)]
60struct Entries {
61    values: Vec<Entry>,
62    memory: Option<MemoryReservation>,
63    generation: u64,
64}
65
66/// A logical session's bounded regular-expression cache. The supplied allowance owns pattern keys, cache slots and compiled contexts. Active calls temporarily remove their entry so independent workers never serialize matching on this lock. In-flight entries remain charged; at most 32 completed patterns are retained.
67pub struct RegexCache {
68    pub(super) budget: MemoryBudget,
69    entries: Mutex<Entries>,
70}
71
72impl RegexCache {
73    pub fn new(budget: MemoryBudget) -> Self {
74        Self {
75            budget,
76            entries: Mutex::new(Entries::default()),
77        }
78    }
79
80    /// Whether this cache's allocations belong to the supplied retention owner.
81    pub fn shares_allowance(&self, budget: &MemoryBudget) -> bool {
82        self.budget.shares_allowance(budget)
83    }
84
85    /// Release all idle patterns and their index allocation. Active invocations retain their owned state until they finish, then discard it if still cleared.
86    pub fn clear(&self) {
87        let mut entries = self
88            .entries
89            .lock()
90            .unwrap_or_else(|error| error.into_inner());
91        *entries = Entries {
92            generation: entries.generation.wrapping_add(1),
93            ..Entries::default()
94        };
95    }
96
97    pub(super) fn take(&self, pattern: &str, flags: CompileFlags, collation: u32) -> Option<Entry> {
98        let mut entries = self
99            .entries
100            .lock()
101            .unwrap_or_else(|error| error.into_inner());
102        let index = entries
103            .values
104            .iter()
105            .position(|entry| entry.matches(pattern, flags, collation))?;
106        Some(entries.values.remove(index))
107    }
108
109    pub(super) fn generation(&self) -> u64 {
110        self.entries
111            .lock()
112            .unwrap_or_else(|error| error.into_inner())
113            .generation
114    }
115
116    /// Retain only completed compiled state. Refused retention leaves the ordinary invocation usable with its original resource contract.
117    pub(super) fn admit(
118        &self,
119        pattern: &str,
120        bytes: usize,
121        original: Option<&MemoryBudget>,
122        generation: u64,
123    ) -> Option<Admission> {
124        if self.prepare().ok()? != generation {
125            return None;
126        }
127        let shared = original.is_some_and(|budget| self.budget.shares_allowance(budget));
128        let additional_state = if shared { 0 } else { bytes };
129        let mut key = BudgetedString::new(&self.budget);
130        loop {
131            match key.push_str(pattern) {
132                Ok(()) => break,
133                Err(ref error) if self.evict_for(error, additional_state) => {}
134                Err(_) => return None,
135            }
136        }
137        let memory = if shared {
138            None
139        } else {
140            loop {
141                match self.budget.reserve(bytes) {
142                    Ok(memory) => break Some(memory),
143                    Err(ref error) if self.evict_for(error, 0) => {}
144                    Err(_) => return None,
145                }
146            }
147        };
148        Some(Admission {
149            pattern: key,
150            generation,
151            memory,
152        })
153    }
154
155    pub(super) fn prepare(&self) -> Result<u64, MemoryError> {
156        let mut entries = self
157            .entries
158            .lock()
159            .unwrap_or_else(|error| error.into_inner());
160        if entries.values.capacity() == 0 {
161            let mut slots = BudgetedVec::<Entry>::new(&self.budget);
162            slots.reserve(CAPACITY)?;
163            let (values, memory) = slots.into_parts();
164            *entries = Entries {
165                values,
166                memory: Some(memory),
167                generation: entries.generation,
168            };
169        }
170        Ok(entries.generation)
171    }
172
173    fn evict_for(&self, error: &MemoryError, pending_bytes: usize) -> bool {
174        let MemoryError::Limit { required, limit } = error else {
175            return false;
176        };
177        let Some(missing) = required
178            .checked_sub(*limit)
179            .and_then(|bytes| bytes.checked_add(pending_bytes))
180        else {
181            return false;
182        };
183        let mut entries = self
184            .entries
185            .lock()
186            .unwrap_or_else(|error| error.into_inner());
187        // The refusal includes the actual key allocation and any limiting ancestor. Both the key and still-unadmitted compiled state must fit after reclaiming idle entries; active calls and unrelated retained owners cannot be evicted.
188        let reclaimable = entries.values.iter().try_fold(0usize, |bytes, entry| {
189            bytes
190                .checked_add(entry.pattern.capacity())?
191                .checked_add(entry.regex.reserved_bytes())
192        });
193        if entries.values.is_empty() || reclaimable.is_none_or(|bytes| bytes < missing) {
194            return false;
195        }
196        entries.values.remove(0);
197        true
198    }
199
200    pub(super) fn keep(&self, entry: Entry) {
201        let mut entries = self
202            .entries
203            .lock()
204            .unwrap_or_else(|error| error.into_inner());
205        if entry.generation != entries.generation
206            || entries.memory.is_none()
207            || entries
208                .values
209                .iter()
210                .any(|old| old.matches(&entry.pattern, entry.flags, entry.collation))
211        {
212            return;
213        }
214        if entries.values.len() == CAPACITY {
215            entries.values.remove(0);
216        }
217        // prepare admitted a full-capacity buffer before compilation; returning an invocation never allocates, including during unwinding or cancellation.
218        entries.values.push(entry);
219    }
220}
221
222thread_local! {
223    static CURRENT: RefCell<Option<Arc<RegexCache>>> = const { RefCell::new(None) };
224}
225
226/// Capture the current session cache for a worker. Outside a session, no cache survives the call and the ordinary resource contract is unchanged.
227pub fn current_regex_cache() -> Option<Arc<RegexCache>> {
228    CURRENT.with_borrow(Clone::clone)
229}
230
231/// Enter a session's cache on this thread, restoring its caller on every exit.
232pub struct RegexCacheScope {
233    previous: Option<Arc<RegexCache>>,
234    thread: PhantomData<Rc<()>>,
235}
236
237impl RegexCacheScope {
238    pub fn enter(cache: Option<Arc<RegexCache>>) -> Self {
239        Self {
240            previous: CURRENT.replace(cache),
241            thread: PhantomData,
242        }
243    }
244}
245
246impl Drop for RegexCacheScope {
247    fn drop(&mut self) {
248        CURRENT.set(self.previous.take());
249    }
250}
251
252#[cfg(test)]
253pub(super) mod tests;