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///
9/// With the `serde` feature, this is an object containing `max_keys`,
10/// `shard_count`, `max_expired_removals_per_check`, and `max_batch_size`.
11/// Only `max_keys` is required when deserializing; omitted bounds use the same
12/// defaults as the constructors.
13#[derive(Clone, Debug, Eq, PartialEq)]
14pub struct MemoryStoreConfig {
15    max_keys: usize,
16    shard_count: usize,
17    max_expired_removals_per_check: usize,
18    max_batch_size: usize,
19}
20
21impl MemoryStoreConfig {
22    /// Creates a configuration with a global hard maximum of `max_keys` stored
23    /// counters.
24    ///
25    /// The store uses one shard by default so the entire configured capacity is
26    /// available regardless of key distribution. Increasing the shard count
27    /// trades some capacity utilization under uneven key distribution for
28    /// greater lock concurrency.
29    ///
30    /// # Errors
31    ///
32    /// Returns an error when `max_keys` is zero.
33    pub fn new(max_keys: usize) -> Result<Self, MemoryStoreConfigError> {
34        if max_keys == 0 {
35            return Err(MemoryStoreConfigError::ZeroMaxKeys);
36        }
37
38        Ok(Self {
39            max_keys,
40            shard_count: DEFAULT_SHARD_COUNT.min(max_keys),
41            max_expired_removals_per_check: DEFAULT_MAX_EXPIRED_REMOVALS,
42            max_batch_size: DEFAULT_MAX_BATCH_SIZE,
43        })
44    }
45
46    /// Sets the number of independently locked shards.
47    ///
48    /// The global key capacity is divided into fixed per-shard capacities. A
49    /// full shard denies a new key even when another shard has unused capacity.
50    /// An atomic batch that targets more distinct keys at a shard than its
51    /// fixed capacity is rejected as structurally unsatisfiable.
52    ///
53    /// # Errors
54    ///
55    /// Returns an error when the shard count is zero or greater than the
56    /// configured global key capacity.
57    pub fn with_shard_count(mut self, shard_count: usize) -> Result<Self, MemoryStoreConfigError> {
58        if shard_count == 0 {
59            return Err(MemoryStoreConfigError::ZeroShardCount);
60        }
61        if shard_count > self.max_keys {
62            return Err(MemoryStoreConfigError::MoreShardsThanKeys {
63                shard_count,
64                max_keys: self.max_keys,
65            });
66        }
67        self.shard_count = shard_count;
68        Ok(self)
69    }
70
71    /// Sets the maximum expired entries removed from a shard per check that
72    /// targets it.
73    ///
74    /// An atomic batch receives this cleanup allowance for each check in the
75    /// batch, applied to that check's shard.
76    ///
77    /// # Errors
78    ///
79    /// Returns an error when `maximum` is zero.
80    pub fn with_max_expired_removals_per_check(
81        mut self,
82        maximum: usize,
83    ) -> Result<Self, MemoryStoreConfigError> {
84        if maximum == 0 {
85            return Err(MemoryStoreConfigError::ZeroExpiredRemovalLimit);
86        }
87        self.max_expired_removals_per_check = maximum;
88        Ok(self)
89    }
90
91    /// Sets the largest atomic batch accepted by the store.
92    ///
93    /// # Errors
94    ///
95    /// Returns an error when `maximum` is zero.
96    pub fn with_max_batch_size(mut self, maximum: usize) -> Result<Self, MemoryStoreConfigError> {
97        if maximum == 0 {
98            return Err(MemoryStoreConfigError::ZeroBatchSize);
99        }
100        self.max_batch_size = maximum;
101        Ok(self)
102    }
103
104    /// Returns the global hard maximum number of stored keys.
105    pub const fn max_keys(&self) -> usize {
106        self.max_keys
107    }
108
109    /// Returns the number of independently locked shards.
110    pub const fn shard_count(&self) -> usize {
111        self.shard_count
112    }
113
114    /// Returns the cleanup work limit per check targeting a shard.
115    pub const fn max_expired_removals_per_check(&self) -> usize {
116        self.max_expired_removals_per_check
117    }
118
119    /// Returns the largest accepted atomic batch.
120    pub const fn max_batch_size(&self) -> usize {
121        self.max_batch_size
122    }
123
124    pub(crate) fn shard_capacity(&self, shard_index: usize) -> usize {
125        let base = self.max_keys / self.shard_count;
126        let extra = usize::from(shard_index < self.max_keys % self.shard_count);
127        base + extra
128    }
129}
130
131#[cfg(feature = "serde")]
132#[derive(serde::Serialize)]
133struct MemoryStoreConfigRef {
134    max_keys: usize,
135    shard_count: usize,
136    max_expired_removals_per_check: usize,
137    max_batch_size: usize,
138}
139
140#[cfg(feature = "serde")]
141#[derive(serde::Deserialize)]
142#[serde(deny_unknown_fields)]
143struct MemoryStoreConfigWire {
144    max_keys: usize,
145    #[serde(default = "default_shard_count")]
146    shard_count: usize,
147    #[serde(default = "default_max_expired_removals")]
148    max_expired_removals_per_check: usize,
149    #[serde(default = "default_max_batch_size")]
150    max_batch_size: usize,
151}
152
153#[cfg(feature = "serde")]
154const fn default_shard_count() -> usize {
155    DEFAULT_SHARD_COUNT
156}
157
158#[cfg(feature = "serde")]
159const fn default_max_expired_removals() -> usize {
160    DEFAULT_MAX_EXPIRED_REMOVALS
161}
162
163#[cfg(feature = "serde")]
164const fn default_max_batch_size() -> usize {
165    DEFAULT_MAX_BATCH_SIZE
166}
167
168#[cfg(feature = "serde")]
169impl serde::Serialize for MemoryStoreConfig {
170    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
171    where
172        S: serde::Serializer,
173    {
174        serde::Serialize::serialize(
175            &MemoryStoreConfigRef {
176                max_keys: self.max_keys(),
177                shard_count: self.shard_count(),
178                max_expired_removals_per_check: self.max_expired_removals_per_check(),
179                max_batch_size: self.max_batch_size(),
180            },
181            serializer,
182        )
183    }
184}
185
186#[cfg(feature = "serde")]
187impl<'de> serde::Deserialize<'de> for MemoryStoreConfig {
188    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
189    where
190        D: serde::Deserializer<'de>,
191    {
192        let wire = <MemoryStoreConfigWire as serde::Deserialize>::deserialize(deserializer)?;
193        Self::new(wire.max_keys)
194            .and_then(|config| config.with_shard_count(wire.shard_count))
195            .and_then(|config| {
196                config.with_max_expired_removals_per_check(wire.max_expired_removals_per_check)
197            })
198            .and_then(|config| config.with_max_batch_size(wire.max_batch_size))
199            .map_err(serde::de::Error::custom)
200    }
201}
202
203/// Invalid in-memory store configuration.
204#[derive(Clone, Debug, Error, Eq, PartialEq)]
205pub enum MemoryStoreConfigError {
206    /// The global key capacity was zero.
207    #[error("max_keys must be greater than zero")]
208    ZeroMaxKeys,
209    /// The shard count was zero.
210    #[error("shard_count must be greater than zero")]
211    ZeroShardCount,
212    /// A shard count greater than the global capacity was requested.
213    #[error("shard_count ({shard_count}) cannot exceed max_keys ({max_keys})")]
214    MoreShardsThanKeys {
215        /// Requested shard count.
216        shard_count: usize,
217        /// Configured global key capacity.
218        max_keys: usize,
219    },
220    /// The bounded cleanup work limit was zero.
221    #[error("max_expired_removals_per_check must be greater than zero")]
222    ZeroExpiredRemovalLimit,
223    /// The accepted batch size was zero.
224    #[error("max_batch_size must be greater than zero")]
225    ZeroBatchSize,
226}
227
228#[cfg(test)]
229mod tests {
230    use super::{MemoryStoreConfig, MemoryStoreConfigError};
231
232    #[test]
233    fn defaults_to_one_shard_so_all_capacity_is_available() {
234        for max_keys in [1, 64, 65, 50_000] {
235            let config = MemoryStoreConfig::new(max_keys).unwrap();
236
237            assert_eq!(config.shard_count(), 1);
238            assert_eq!(config.shard_capacity(0), max_keys);
239        }
240    }
241
242    #[test]
243    fn distributes_capacity_without_exceeding_global_maximum() {
244        let config = MemoryStoreConfig::new(10)
245            .unwrap()
246            .with_shard_count(3)
247            .unwrap();
248
249        assert_eq!(config.shard_capacity(0), 4);
250        assert_eq!(config.shard_capacity(1), 3);
251        assert_eq!(config.shard_capacity(2), 3);
252        assert_eq!(
253            (0..config.shard_count())
254                .map(|index| config.shard_capacity(index))
255                .sum::<usize>(),
256            config.max_keys()
257        );
258    }
259
260    #[test]
261    fn rejects_zero_capacity() {
262        assert_eq!(
263            MemoryStoreConfig::new(0),
264            Err(MemoryStoreConfigError::ZeroMaxKeys)
265        );
266    }
267
268    #[test]
269    fn rejects_more_shards_than_keys() {
270        assert_eq!(
271            MemoryStoreConfig::new(2).unwrap().with_shard_count(3),
272            Err(MemoryStoreConfigError::MoreShardsThanKeys {
273                shard_count: 3,
274                max_keys: 2,
275            })
276        );
277    }
278}