Skip to main content

vthread_stack/
pool.rs

1//! Bounded carrier-local stack cache.
2
3#[cfg(feature = "runtime-evidence")]
4use std::collections::BTreeMap;
5use std::io;
6
7use corosensei::stack::DefaultStack;
8#[cfg(feature = "runtime-evidence")]
9use corosensei::stack::Stack;
10
11/// Operational counters for a stack pool.
12#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
13pub struct StackPoolSnapshot {
14    /// Stacks currently retained for reuse.
15    pub cached: usize,
16    /// Fresh stack mappings created.
17    pub allocated: u64,
18    /// Cached stacks handed out again.
19    pub reused: u64,
20    /// Completed stacks accepted into the cache.
21    pub retained: u64,
22    /// Completed stacks dropped because the cache was full.
23    pub discarded: u64,
24}
25
26/// A bounded cache of guard-page-backed stacks.
27pub struct StackPool {
28    stack_size: usize,
29    max_cached: usize,
30    stacks: Vec<DefaultStack>,
31    #[cfg(feature = "runtime-evidence")]
32    identities: BTreeMap<usize, u64>,
33    #[cfg(feature = "runtime-evidence")]
34    mappings: BTreeMap<u64, usize>,
35    #[cfg(feature = "runtime-evidence")]
36    next_identity: u64,
37    snapshot: StackPoolSnapshot,
38}
39
40impl StackPool {
41    /// Creates an empty pool.
42    pub fn new(stack_size: usize, max_cached: usize) -> Self {
43        Self {
44            stack_size,
45            max_cached,
46            stacks: Vec::new(),
47            #[cfg(feature = "runtime-evidence")]
48            identities: BTreeMap::new(),
49            #[cfg(feature = "runtime-evidence")]
50            mappings: BTreeMap::new(),
51            #[cfg(feature = "runtime-evidence")]
52            next_identity: 1,
53            snapshot: StackPoolSnapshot::default(),
54        }
55    }
56
57    /// Acquires a cached stack or allocates a new one.
58    pub fn acquire(&mut self) -> io::Result<DefaultStack> {
59        #[cfg(feature = "runtime-evidence")]
60        {
61            self.acquire_identified().map(|(_, stack)| stack)
62        }
63        #[cfg(not(feature = "runtime-evidence"))]
64        {
65            if let Some(stack) = self.stacks.pop() {
66                self.snapshot.cached = self.stacks.len();
67                self.snapshot.reused += 1;
68                return Ok(stack);
69            }
70            self.snapshot.allocated += 1;
71            DefaultStack::new(self.stack_size)
72        }
73    }
74
75    /// Acquires a stack together with its stable pool-local mapping identity.
76    #[cfg(feature = "runtime-evidence")]
77    pub fn acquire_identified(&mut self) -> io::Result<(u64, DefaultStack)> {
78        if let Some(stack) = self.stacks.pop() {
79            self.snapshot.cached = self.stacks.len();
80            self.snapshot.reused += 1;
81            let identity = self
82                .identity(&stack)
83                .ok_or_else(|| io::Error::other("cached stack mapping has no pool identity"))?;
84            return Ok((identity, stack));
85        }
86
87        let stack = DefaultStack::new(self.stack_size)?;
88        let identity = self.next_identity;
89        self.next_identity = identity
90            .checked_add(1)
91            .ok_or_else(|| io::Error::other("stack mapping identity exhausted"))?;
92        let base = stack.base().get();
93        self.identities.insert(base, identity);
94        self.mappings.insert(identity, base);
95        self.snapshot.allocated += 1;
96        Ok((identity, stack))
97    }
98
99    /// Returns a completed stack to the bounded cache.
100    pub fn release(&mut self, stack: DefaultStack) {
101        #[cfg(feature = "runtime-evidence")]
102        {
103            let Some(identity) = self.identity(&stack) else {
104                self.snapshot.discarded += 1;
105                return;
106            };
107            self.release_identified(identity, stack);
108        }
109        #[cfg(not(feature = "runtime-evidence"))]
110        {
111            if self.stacks.len() < self.max_cached {
112                self.stacks.push(stack);
113                self.snapshot.retained += 1;
114                self.snapshot.cached = self.stacks.len();
115            } else {
116                self.snapshot.discarded += 1;
117            }
118        }
119    }
120
121    /// Returns an identified mapping and reports whether the bounded cache retained it.
122    #[cfg(feature = "runtime-evidence")]
123    pub fn release_identified(&mut self, identity: u64, stack: DefaultStack) -> bool {
124        let actual = self.identity(&stack);
125        if actual != Some(identity) {
126            self.snapshot.discarded += 1;
127            if let Some(actual) = actual {
128                self.retire(actual);
129            }
130            return false;
131        }
132        if self.stacks.len() < self.max_cached {
133            self.stacks.push(stack);
134            self.snapshot.retained += 1;
135            self.snapshot.cached = self.stacks.len();
136            true
137        } else {
138            self.snapshot.discarded += 1;
139            self.retire(identity);
140            false
141        }
142    }
143
144    /// Retires metadata after its active mapping was discarded outside the cache.
145    #[cfg(feature = "runtime-evidence")]
146    pub fn retire(&mut self, identity: u64) -> bool {
147        let Some(base) = self.mappings.remove(&identity) else {
148            return false;
149        };
150        self.identities.remove(&base);
151        true
152    }
153
154    /// Returns the current counters.
155    pub fn snapshot(&self) -> StackPoolSnapshot {
156        self.snapshot
157    }
158
159    #[cfg(feature = "runtime-evidence")]
160    fn identity(&self, stack: &DefaultStack) -> Option<u64> {
161        self.identities.get(&stack.base().get()).copied()
162    }
163}
164
165#[cfg(test)]
166#[path = "pool_test.rs"]
167mod pool_test;