Skip to main content

runlimit_memory/
config.rs

1use thiserror::Error;
2
3const DEFAULT_SHARD_COUNT: usize = 1;
4const DEFAULT_MAX_EXPIRED_REMOVALS: usize = 8;
5const DEFAULT_MAX_BATCH_SIZE: usize = 32;
6
7/// Configuration for a hard-bounded [`MemoryStore`](crate::MemoryStore).
8#[derive(Clone, Debug, Eq, PartialEq)]
9pub struct MemoryStoreConfig {
10    max_keys: usize,
11    shard_count: usize,
12    max_expired_removals_per_check: usize,
13    max_batch_size: usize,
14}
15
16impl MemoryStoreConfig {
17    /// Creates a configuration with a global hard maximum of `max_keys` stored
18    /// counters.
19    ///
20    /// The store uses one shard by default so the entire configured capacity is
21    /// available regardless of key distribution. Increasing the shard count
22    /// trades some capacity utilization under uneven key distribution for
23    /// greater lock concurrency.
24    ///
25    /// # Errors
26    ///
27    /// Returns an error when `max_keys` is zero.
28    pub fn new(max_keys: usize) -> Result<Self, MemoryStoreConfigError> {
29        if max_keys == 0 {
30            return Err(MemoryStoreConfigError::ZeroMaxKeys);
31        }
32
33        Ok(Self {
34            max_keys,
35            shard_count: DEFAULT_SHARD_COUNT.min(max_keys),
36            max_expired_removals_per_check: DEFAULT_MAX_EXPIRED_REMOVALS,
37            max_batch_size: DEFAULT_MAX_BATCH_SIZE,
38        })
39    }
40
41    /// Sets the number of independently locked shards.
42    ///
43    /// The global key capacity is divided into fixed per-shard capacities. A
44    /// full shard denies a new key even when another shard has unused capacity.
45    ///
46    /// # Errors
47    ///
48    /// Returns an error when the shard count is zero or greater than the
49    /// configured global key capacity.
50    pub fn with_shard_count(mut self, shard_count: usize) -> Result<Self, MemoryStoreConfigError> {
51        if shard_count == 0 {
52            return Err(MemoryStoreConfigError::ZeroShardCount);
53        }
54        if shard_count > self.max_keys {
55            return Err(MemoryStoreConfigError::MoreShardsThanKeys {
56                shard_count,
57                max_keys: self.max_keys,
58            });
59        }
60        self.shard_count = shard_count;
61        Ok(self)
62    }
63
64    /// Sets the maximum expired entries removed from a shard per check that
65    /// targets it.
66    ///
67    /// An atomic batch receives this cleanup allowance for each check in the
68    /// batch, applied to that check's shard.
69    ///
70    /// # Errors
71    ///
72    /// Returns an error when `maximum` is zero.
73    pub fn with_max_expired_removals_per_check(
74        mut self,
75        maximum: usize,
76    ) -> Result<Self, MemoryStoreConfigError> {
77        if maximum == 0 {
78            return Err(MemoryStoreConfigError::ZeroExpiredRemovalLimit);
79        }
80        self.max_expired_removals_per_check = maximum;
81        Ok(self)
82    }
83
84    /// Sets the largest atomic batch accepted by the store.
85    ///
86    /// # Errors
87    ///
88    /// Returns an error when `maximum` is zero.
89    pub fn with_max_batch_size(mut self, maximum: usize) -> Result<Self, MemoryStoreConfigError> {
90        if maximum == 0 {
91            return Err(MemoryStoreConfigError::ZeroBatchSize);
92        }
93        self.max_batch_size = maximum;
94        Ok(self)
95    }
96
97    /// Returns the global hard maximum number of stored keys.
98    pub const fn max_keys(&self) -> usize {
99        self.max_keys
100    }
101
102    /// Returns the number of independently locked shards.
103    pub const fn shard_count(&self) -> usize {
104        self.shard_count
105    }
106
107    /// Returns the cleanup work limit per check targeting a shard.
108    pub const fn max_expired_removals_per_check(&self) -> usize {
109        self.max_expired_removals_per_check
110    }
111
112    /// Returns the largest accepted atomic batch.
113    pub const fn max_batch_size(&self) -> usize {
114        self.max_batch_size
115    }
116
117    pub(crate) fn shard_capacity(&self, shard_index: usize) -> usize {
118        let base = self.max_keys / self.shard_count;
119        let extra = usize::from(shard_index < self.max_keys % self.shard_count);
120        base + extra
121    }
122}
123
124/// Invalid in-memory store configuration.
125#[derive(Clone, Debug, Error, Eq, PartialEq)]
126pub enum MemoryStoreConfigError {
127    /// The global key capacity was zero.
128    #[error("max_keys must be greater than zero")]
129    ZeroMaxKeys,
130    /// The shard count was zero.
131    #[error("shard_count must be greater than zero")]
132    ZeroShardCount,
133    /// A shard count greater than the global capacity was requested.
134    #[error("shard_count ({shard_count}) cannot exceed max_keys ({max_keys})")]
135    MoreShardsThanKeys {
136        /// Requested shard count.
137        shard_count: usize,
138        /// Configured global key capacity.
139        max_keys: usize,
140    },
141    /// The bounded cleanup work limit was zero.
142    #[error("max_expired_removals_per_check must be greater than zero")]
143    ZeroExpiredRemovalLimit,
144    /// The accepted batch size was zero.
145    #[error("max_batch_size must be greater than zero")]
146    ZeroBatchSize,
147}
148
149#[cfg(test)]
150mod tests {
151    use super::{MemoryStoreConfig, MemoryStoreConfigError};
152
153    #[test]
154    fn defaults_to_one_shard_so_all_capacity_is_available() {
155        for max_keys in [1, 64, 65, 50_000] {
156            let config = MemoryStoreConfig::new(max_keys).unwrap();
157
158            assert_eq!(config.shard_count(), 1);
159            assert_eq!(config.shard_capacity(0), max_keys);
160        }
161    }
162
163    #[test]
164    fn distributes_capacity_without_exceeding_global_maximum() {
165        let config = MemoryStoreConfig::new(10)
166            .unwrap()
167            .with_shard_count(3)
168            .unwrap();
169
170        assert_eq!(config.shard_capacity(0), 4);
171        assert_eq!(config.shard_capacity(1), 3);
172        assert_eq!(config.shard_capacity(2), 3);
173        assert_eq!(
174            (0..config.shard_count())
175                .map(|index| config.shard_capacity(index))
176                .sum::<usize>(),
177            config.max_keys()
178        );
179    }
180
181    #[test]
182    fn rejects_zero_capacity() {
183        assert_eq!(
184            MemoryStoreConfig::new(0),
185            Err(MemoryStoreConfigError::ZeroMaxKeys)
186        );
187    }
188
189    #[test]
190    fn rejects_more_shards_than_keys() {
191        assert_eq!(
192            MemoryStoreConfig::new(2).unwrap().with_shard_count(3),
193            Err(MemoryStoreConfigError::MoreShardsThanKeys {
194                shard_count: 3,
195                max_keys: 2,
196            })
197        );
198    }
199}