Skip to main content

vthread_stack/
pool.rs

1//! Bounded carrier-local stack cache.
2
3use std::io;
4
5use corosensei::stack::DefaultStack;
6
7/// Operational counters for a stack pool.
8#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
9pub struct StackPoolSnapshot {
10    /// Stacks currently retained for reuse.
11    pub cached: usize,
12    /// Fresh stack mappings created.
13    pub allocated: u64,
14    /// Cached stacks handed out again.
15    pub reused: u64,
16    /// Completed stacks accepted into the cache.
17    pub retained: u64,
18    /// Completed stacks dropped because the cache was full.
19    pub discarded: u64,
20}
21
22/// A bounded cache of guard-page-backed stacks.
23pub struct StackPool {
24    stack_size: usize,
25    max_cached: usize,
26    stacks: Vec<DefaultStack>,
27    snapshot: StackPoolSnapshot,
28}
29
30impl StackPool {
31    /// Creates an empty pool.
32    pub fn new(stack_size: usize, max_cached: usize) -> Self {
33        Self {
34            stack_size,
35            max_cached,
36            stacks: Vec::new(),
37            snapshot: StackPoolSnapshot::default(),
38        }
39    }
40
41    /// Acquires a cached stack or allocates a new one.
42    pub fn acquire(&mut self) -> io::Result<DefaultStack> {
43        if let Some(stack) = self.stacks.pop() {
44            self.snapshot.cached = self.stacks.len();
45            self.snapshot.reused += 1;
46            return Ok(stack);
47        }
48
49        let stack = DefaultStack::new(self.stack_size)?;
50        self.snapshot.allocated += 1;
51        Ok(stack)
52    }
53
54    /// Returns a completed stack to the bounded cache.
55    pub fn release(&mut self, stack: DefaultStack) {
56        if self.stacks.len() < self.max_cached {
57            self.stacks.push(stack);
58            self.snapshot.retained += 1;
59            self.snapshot.cached = self.stacks.len();
60        } else {
61            self.snapshot.discarded += 1;
62        }
63    }
64
65    /// Returns the current counters.
66    pub fn snapshot(&self) -> StackPoolSnapshot {
67        self.snapshot
68    }
69}
70
71#[cfg(test)]
72#[path = "pool_test.rs"]
73mod pool_test;