Skip to main content

rustf/
pool.rs

1//! Object pooling system for Request structures
2//!
3//! ⚠️ **NOT RECOMMENDED FOR USE IN PRODUCTION**
4//!
5//! Benchmarks demonstrate this implementation is approximately **2x SLOWER** than direct
6//! allocation for Request objects due to:
7//! - Mutex lock overhead (4 separate lock acquisitions per get/return cycle)
8//! - Request::reset() overhead (clearing 6 collections)
9//! - Statistics tracking overhead
10//! - Modern Rust allocators (jemalloc/mimalloc) are already excellent for small objects
11//!
12//! **Benchmark Results:**
13//! - Pooled allocation: ~90-105ns
14//! - Direct allocation: ~40-57ns
15//! - Pool is 2x SLOWER than `Request::default()`
16//!
17//! This module is kept for reference and experimentation, but the RustF framework
18//! itself does not use it. For real-world applications, use `Request::default()` directly.
19//!
20//! See `rustf/benches/pool.rs` for detailed benchmark results.
21
22use crate::http::Request;
23use std::sync::{Arc, Mutex};
24
25/// Thread-safe object pool for Request structures
26///
27/// Maintains a pool of pre-allocated Request objects that can be reused
28/// across multiple HTTP requests. Uses LIFO (Last In, First Out) strategy
29/// to improve cache locality.
30#[derive(Clone)]
31pub struct RequestPool {
32    pool: Arc<Mutex<Vec<Request>>>,
33    max_size: usize,
34    created_count: Arc<Mutex<usize>>,
35    borrowed_count: Arc<Mutex<usize>>,
36    returned_count: Arc<Mutex<usize>>,
37}
38
39impl RequestPool {
40    /// Create a new request pool with specified maximum size
41    ///
42    /// # Arguments
43    /// * `max_size` - Maximum number of objects to keep in pool
44    ///
45    /// # Performance
46    /// - Larger pools reduce allocation frequency but use more memory
47    /// - Recommended: 2-4x your expected concurrent request count
48    pub fn new(max_size: usize) -> Self {
49        Self {
50            pool: Arc::new(Mutex::new(Vec::with_capacity(max_size))),
51            max_size,
52            created_count: Arc::new(Mutex::new(0)),
53            borrowed_count: Arc::new(Mutex::new(0)),
54            returned_count: Arc::new(Mutex::new(0)),
55        }
56    }
57
58    /// Get a Request from the pool or create a new one
59    ///
60    /// Returns a `PooledRequest` which automatically returns the
61    /// object to the pool when dropped (RAII pattern).
62    pub fn get(&self) -> PooledRequest {
63        let request = {
64            let mut pool = match self.pool.lock() {
65                Ok(p) => p,
66                Err(_) => {
67                    // Lock poisoned, create new request
68                    return PooledRequest {
69                        request: Some(Request::default()),
70                        pool: self.clone(),
71                    };
72                }
73            };
74            match pool.pop() {
75                Some(mut req) => {
76                    // Reset the request for reuse
77                    req.reset();
78                    req
79                }
80                None => {
81                    // Pool empty, create new request
82                    if let Ok(mut count) = self.created_count.lock() {
83                        *count += 1;
84                    }
85                    Request::default()
86                }
87            }
88        };
89
90        if let Ok(mut count) = self.borrowed_count.lock() {
91            *count += 1;
92        }
93
94        PooledRequest {
95            request: Some(request),
96            pool: self.clone(),
97        }
98    }
99
100    /// Return a Request to the pool
101    ///
102    /// Called automatically by PooledRequest::drop(), but can be
103    /// called manually for explicit control.
104    fn return_request(&self, mut request: Request) {
105        if let Ok(mut pool) = self.pool.lock() {
106            if pool.len() < self.max_size {
107                // Reset request state before returning to pool
108                request.reset();
109                pool.push(request);
110                if let Ok(mut count) = self.returned_count.lock() {
111                    *count += 1;
112                }
113            }
114        }
115        // If pool is full or lock failed, let the request be dropped
116    }
117
118    /// Get pool statistics for monitoring
119    pub fn stats(&self) -> PoolStats {
120        let pool_size = self.pool.lock().map(|p| p.len()).unwrap_or(0);
121        let created = self.created_count.lock().map(|c| *c).unwrap_or(0);
122        let borrowed = self.borrowed_count.lock().map(|b| *b).unwrap_or(0);
123        let returned = self.returned_count.lock().map(|r| *r).unwrap_or(0);
124
125        PoolStats {
126            pool_size,
127            max_size: self.max_size,
128            created_count: created,
129            borrowed_count: borrowed,
130            returned_count: returned,
131            hit_rate: if borrowed > 0 && borrowed >= created {
132                (borrowed - created) as f64 / borrowed as f64 * 100.0
133            } else {
134                0.0
135            },
136        }
137    }
138
139    /// Clear all objects from the pool
140    ///
141    /// Useful for memory cleanup or during testing
142    pub fn clear(&self) {
143        if let Ok(mut pool) = self.pool.lock() {
144            pool.clear();
145        }
146    }
147
148    /// Pre-populate the pool with objects
149    ///
150    /// Creates objects in advance to avoid allocation during request handling.
151    /// Recommended to call during application startup.
152    pub fn warm_up(&self, count: usize) {
153        let count = count.min(self.max_size);
154        let mut pool = match self.pool.lock() {
155            Ok(p) => p,
156            Err(_) => return, // Can't warm up with poisoned lock
157        };
158
159        for _ in 0..count {
160            if pool.len() < self.max_size {
161                pool.push(Request::default());
162                if let Ok(mut created) = self.created_count.lock() {
163                    *created += 1;
164                }
165            }
166        }
167    }
168}
169
170/// RAII wrapper for pooled Request objects
171///
172/// Automatically returns the Request to the pool when dropped.
173/// Implements Deref/DerefMut for transparent access to Request methods.
174pub struct PooledRequest {
175    request: Option<Request>,
176    pool: RequestPool,
177}
178
179impl PooledRequest {
180    /// Get mutable reference to the underlying Request
181    pub fn get_mut(&mut self) -> Option<&mut Request> {
182        self.request.as_mut()
183    }
184
185    /// Get immutable reference to the underlying Request
186    pub fn get(&self) -> Option<&Request> {
187        self.request.as_ref()
188    }
189
190    /// Take ownership of the Request, consuming the PooledRequest
191    ///
192    /// The Request will NOT be returned to the pool in this case.
193    /// Returns None if the request has already been taken.
194    pub fn into_inner(mut self) -> Option<Request> {
195        self.request.take()
196    }
197}
198
199impl std::ops::Deref for PooledRequest {
200    type Target = Request;
201
202    fn deref(&self) -> &Self::Target {
203        self.request
204            .as_ref()
205            .expect("PooledRequest: request already taken")
206    }
207}
208
209impl std::ops::DerefMut for PooledRequest {
210    fn deref_mut(&mut self) -> &mut Self::Target {
211        self.request
212            .as_mut()
213            .expect("PooledRequest: request already taken")
214    }
215}
216
217impl Drop for PooledRequest {
218    fn drop(&mut self) {
219        if let Some(request) = self.request.take() {
220            self.pool.return_request(request);
221        }
222    }
223}
224
225/// Pool statistics for monitoring and optimization
226#[derive(Debug, Clone)]
227pub struct PoolStats {
228    /// Current number of objects in the pool
229    pub pool_size: usize,
230    /// Maximum pool size
231    pub max_size: usize,
232    /// Total objects created (including initial pool)
233    pub created_count: usize,
234    /// Total objects borrowed from pool
235    pub borrowed_count: usize,
236    /// Total objects returned to pool
237    pub returned_count: usize,
238    /// Cache hit rate (percentage of borrows that didn't require allocation)
239    pub hit_rate: f64,
240}
241
242/// Global request pool instance
243///
244/// Provides a default pool that can be used across the application.
245/// Pool size automatically determined based on available memory and CPU cores.
246static REQUEST_POOL: std::sync::OnceLock<RequestPool> = std::sync::OnceLock::new();
247
248/// Get the global request pool instance
249///
250/// Lazily initializes the pool with optimized defaults:
251/// - Pool size: 4x CPU core count (good for CPU-bound workloads)
252/// - Minimum 16, maximum 512 objects
253pub fn global_request_pool() -> &'static RequestPool {
254    REQUEST_POOL.get_or_init(|| {
255        let core_count = num_cpus::get();
256        let pool_size = (core_count * 4).max(16).min(512);
257
258        let pool = RequestPool::new(pool_size);
259        pool.warm_up(pool_size / 2); // Pre-populate 50% of pool
260        pool
261    })
262}
263
264/// Initialize global request pool with custom size
265///
266/// Must be called before first use of global_request_pool().
267/// Useful for applications with specific memory/performance requirements.
268pub fn init_global_pool(
269    max_size: usize,
270    warm_up_count: usize,
271) -> std::result::Result<(), &'static str> {
272    let pool = RequestPool::new(max_size);
273    pool.warm_up(warm_up_count);
274
275    REQUEST_POOL
276        .set(pool)
277        .map_err(|_| "Global pool already initialized")
278}
279
280#[cfg(test)]
281mod tests {
282    use super::*;
283
284    #[test]
285    fn test_pool_basic_functionality() {
286        let pool = RequestPool::new(5);
287
288        // Get request from empty pool (should create new)
289        let mut req1 = pool.get();
290        req1.method = "GET".to_string();
291        req1.uri = "/test".to_string();
292
293        let stats = pool.stats();
294        assert_eq!(stats.created_count, 1);
295        assert_eq!(stats.borrowed_count, 1);
296        assert_eq!(stats.pool_size, 0);
297
298        // Return to pool
299        drop(req1);
300
301        let stats = pool.stats();
302        assert_eq!(stats.returned_count, 1);
303        assert_eq!(stats.pool_size, 1);
304
305        // Get again (should reuse)
306        let req2 = pool.get();
307        assert!(req2.method.is_empty()); // Should be reset
308        assert!(req2.uri.is_empty());
309
310        let stats = pool.stats();
311        assert_eq!(stats.created_count, 1); // No new creation
312        assert_eq!(stats.borrowed_count, 2);
313        assert_eq!(stats.pool_size, 0);
314        assert!(stats.hit_rate > 0.0);
315    }
316
317    #[test]
318    fn test_pool_max_size() {
319        let pool = RequestPool::new(2);
320
321        // Fill pool beyond capacity
322        let req1 = pool.get();
323        let req2 = pool.get();
324        let req3 = pool.get();
325
326        drop(req1);
327        drop(req2);
328        drop(req3);
329
330        let stats = pool.stats();
331        assert_eq!(stats.pool_size, 2); // Should not exceed max_size
332        assert_eq!(stats.returned_count, 2);
333    }
334
335    #[test]
336    fn test_request_reset() {
337        let pool = RequestPool::new(5);
338
339        {
340            let mut req = pool.get();
341            req.method = "POST".to_string();
342            req.uri = "/api/test".to_string();
343            req.headers
344                .insert("Content-Type".to_string(), "application/json".to_string());
345            req.query.insert("param".to_string(), "value".to_string());
346            // body_bytes is private, test via body_as_string after setting
347        } // Return to pool
348
349        // Get same request back
350        let req = pool.get();
351        assert!(req.method.is_empty());
352        assert!(req.uri.is_empty());
353        assert!(req.headers.is_empty());
354        assert!(req.query.is_empty());
355        assert!(req.body_as_string().is_empty());
356    }
357
358    #[test]
359    fn test_pool_warm_up() {
360        let pool = RequestPool::new(10);
361        pool.warm_up(5);
362
363        let stats = pool.stats();
364        assert_eq!(stats.pool_size, 5);
365        assert_eq!(stats.created_count, 5);
366        assert_eq!(stats.borrowed_count, 0);
367    }
368
369    #[test]
370    fn test_global_pool() {
371        let pool1 = global_request_pool();
372        let pool2 = global_request_pool();
373
374        // Should be same instance
375        assert!(std::ptr::eq(pool1, pool2));
376
377        let _req = pool1.get();
378        let stats = pool1.stats();
379        assert!(stats.max_size >= 16); // Should have reasonable size
380    }
381}