velesdb_core/velesql/
cache.rs

1//! Query cache for `VelesQL` parsed queries.
2//!
3//! Provides an LRU cache for parsed AST to avoid re-parsing identical queries.
4//! Typical cache hit rates exceed 90% on repetitive workloads.
5
6use parking_lot::RwLock;
7use rustc_hash::FxHashMap;
8use std::collections::VecDeque;
9use std::hash::{Hash, Hasher};
10
11use super::ast::Query;
12use super::error::ParseError;
13use super::Parser;
14
15/// Statistics for the query cache.
16#[derive(Debug, Clone, Copy, Default)]
17pub struct CacheStats {
18    /// Number of cache hits.
19    pub hits: u64,
20    /// Number of cache misses.
21    pub misses: u64,
22    /// Number of evictions.
23    pub evictions: u64,
24}
25
26impl CacheStats {
27    /// Returns the cache hit rate as a percentage (0.0 - 100.0).
28    #[must_use]
29    pub fn hit_rate(&self) -> f64 {
30        let total = self.hits + self.misses;
31        if total == 0 {
32            0.0
33        } else {
34            #[allow(clippy::cast_precision_loss)]
35            let rate = (self.hits as f64 / total as f64) * 100.0;
36            rate
37        }
38    }
39}
40
41/// LRU cache for parsed `VelesQL` queries.
42///
43/// Thread-safe implementation using `parking_lot::RwLock`.
44///
45/// # Example
46///
47/// ```ignore
48/// use velesdb_core::velesql::QueryCache;
49///
50/// let cache = QueryCache::new(1000);
51/// let query = cache.parse("SELECT * FROM documents LIMIT 10")?;
52/// // Second call returns cached AST
53/// let query2 = cache.parse("SELECT * FROM documents LIMIT 10")?;
54/// assert!(cache.stats().hits >= 1);
55/// ```
56pub struct QueryCache {
57    /// Cache storage: hash -> Query
58    cache: RwLock<FxHashMap<u64, Query>>,
59    /// LRU order: front = oldest, back = newest
60    order: RwLock<VecDeque<u64>>,
61    /// Maximum cache size
62    max_size: usize,
63    /// Cache statistics
64    stats: RwLock<CacheStats>,
65}
66
67impl QueryCache {
68    /// Creates a new query cache with the specified maximum size.
69    ///
70    /// # Arguments
71    ///
72    /// * `max_size` - Maximum number of queries to cache (minimum 1)
73    #[must_use]
74    pub fn new(max_size: usize) -> Self {
75        Self {
76            cache: RwLock::new(FxHashMap::default()),
77            order: RwLock::new(VecDeque::with_capacity(max_size)),
78            max_size: max_size.max(1),
79            stats: RwLock::new(CacheStats::default()),
80        }
81    }
82
83    /// Parses a query, returning cached AST if available.
84    ///
85    /// # Errors
86    ///
87    /// Returns `ParseError` if the query is invalid.
88    pub fn parse(&self, query: &str) -> Result<Query, ParseError> {
89        let hash = Self::hash_query(query);
90
91        // Try cache read first
92        {
93            let cache = self.cache.read();
94            if let Some(cached) = cache.get(&hash) {
95                let mut stats = self.stats.write();
96                stats.hits += 1;
97                return Ok(cached.clone());
98            }
99        }
100
101        // Cache miss - parse the query
102        let parsed = Parser::parse(query)?;
103
104        // Insert into cache
105        {
106            let mut cache = self.cache.write();
107            let mut order = self.order.write();
108            let mut stats = self.stats.write();
109
110            stats.misses += 1;
111
112            // Evict oldest if at capacity
113            while cache.len() >= self.max_size {
114                if let Some(oldest) = order.pop_front() {
115                    cache.remove(&oldest);
116                    stats.evictions += 1;
117                }
118            }
119
120            cache.insert(hash, parsed.clone());
121            order.push_back(hash);
122        }
123
124        Ok(parsed)
125    }
126
127    /// Returns current cache statistics.
128    #[must_use]
129    pub fn stats(&self) -> CacheStats {
130        *self.stats.read()
131    }
132
133    /// Returns the current number of cached queries.
134    #[must_use]
135    pub fn len(&self) -> usize {
136        self.cache.read().len()
137    }
138
139    /// Returns true if the cache is empty.
140    #[must_use]
141    pub fn is_empty(&self) -> bool {
142        self.cache.read().is_empty()
143    }
144
145    /// Clears all cached queries and resets statistics.
146    pub fn clear(&self) {
147        let mut cache = self.cache.write();
148        let mut order = self.order.write();
149        let mut stats = self.stats.write();
150
151        cache.clear();
152        order.clear();
153        *stats = CacheStats::default();
154    }
155
156    /// Computes a hash for the query string.
157    fn hash_query(query: &str) -> u64 {
158        let mut hasher = rustc_hash::FxHasher::default();
159        query.hash(&mut hasher);
160        hasher.finish()
161    }
162}
163
164impl Default for QueryCache {
165    fn default() -> Self {
166        Self::new(1000)
167    }
168}
velesdb_core/velesql/cache.rs

velesdb_core/velesql/
cache.rs
