Skip to main content

sisa_caching_memory/
settings.rs

1//! Settings for the memory store.
2
3use std::time::Duration;
4
5use serde::{Deserialize, Serialize};
6use sisa_caching_core::{
7    cache::CacheError,
8    settings::{CacheSettings, NoUnknownFields, check_duration},
9};
10
11/// The most maps a store's entries can be split over.
12const MAX_SHARDS: usize = 1_024;
13
14/// The memory store's own settings, apart from the shared ones. A hybrid store's local layer
15/// takes these too, under `local`.
16#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
17#[serde(default, deny_unknown_fields)]
18#[non_exhaustive]
19pub struct MemorySettings {
20    /// How often the store drops its expired entries: 60 seconds by default. `None` turns that
21    /// off, for an application that calls `purge` itself; `validate` rejects `0`.
22    pub purge_interval_secs: Option<u64>,
23
24    /// The most entries the store holds. Past it, an insert starts a trim that drops expired
25    /// entries, then the least recently used, down to about nine tenths of the limit. Inside a
26    /// tokio runtime the trim runs on the blocking pool and inserts go on meanwhile, so the store
27    /// can go over the limit while it runs; if they left it over, the trim runs again. `None`, the
28    /// default, sets no limit; `validate` rejects `0`.
29    pub max_entries: Option<usize>,
30
31    /// How many maps the entries are split over, each with its own lock: 16 by default. More maps
32    /// let threads using different keys run side by side, and a `remove_prefix`, purge or trim
33    /// holds up one map at a time instead of the whole store; each call then hashes its key once
34    /// more. `None` means one map, a little faster for a store used from one thread; `validate`
35    /// rejects `0` and more than 1,024.
36    pub shards: Option<usize>,
37}
38
39// A purge every minute, no limit, and 16 maps.
40impl Default for MemorySettings {
41    fn default() -> Self {
42        Self {
43            purge_interval_secs: Some(60),
44            max_entries: None,
45            shards: Some(16),
46        }
47    }
48}
49
50impl MemorySettings {
51    /// Fails when a setting is 0, `purge_interval_secs` is over 365 days or `shards` is over
52    /// 1,024.
53    pub fn validate(&self) -> Result<(), CacheError> {
54        check_duration(
55            "purge_interval_secs",
56            self.purge_interval(),
57            "use None to turn purging off",
58        )?;
59
60        for (field, count, none) in [
61            ("max_entries", self.max_entries, "for no limit"),
62            ("shards", self.shards, "for one map"),
63        ] {
64            if count == Some(0) {
65                return Err(CacheError::invalid_settings(
66                    field,
67                    format!("is 0; use None {none}"),
68                ));
69            }
70        }
71
72        if let Some(shards) = self.shards.filter(|shards| *shards > MAX_SHARDS) {
73            return Err(CacheError::invalid_settings(
74                "shards",
75                format!("is {shards}; the most is {MAX_SHARDS}"),
76            ));
77        }
78
79        Ok(())
80    }
81
82    /// `purge_interval_secs` as a `Duration`, or `None` when the store doesn't purge by itself.
83    pub fn purge_interval(&self) -> Option<Duration> {
84        self.purge_interval_secs.map(Duration::from_secs)
85    }
86
87    /// How many maps `shards` asks for: 1 for `None`.
88    pub fn shards(&self) -> usize {
89        self.shards.unwrap_or(1)
90    }
91}
92
93/// Settings for an [`InMemoryCacheStore`](crate::store::InMemoryCacheStore): the shared ones and
94/// the memory store's own. In a config file both sit side by side, and an unknown field fails, so
95/// a misspelled setting can't silently keep its default:
96///
97/// ```
98/// # use sisa_caching_memory::settings::InMemoryCacheSettings;
99/// let settings: InMemoryCacheSettings =
100///     serde_json::from_str(r#"{ "default_ttl_secs": 300, "max_entries": 10000 }"#).unwrap();
101///
102/// assert_eq!(settings.common.default_ttl_secs, Some(300));
103/// assert_eq!(settings.memory.max_entries, Some(10_000));
104/// let misspelled = r#"{ "default_ttl_sec": 300 }"#;
105/// assert!(serde_json::from_str::<InMemoryCacheSettings>(misspelled).is_err());
106/// ```
107#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
108#[serde(default)]
109#[non_exhaustive]
110pub struct InMemoryCacheSettings {
111    /// The settings every store has: the default TTL, refresh-ahead and the `get_or_set` lock wait.
112    #[serde(flatten)]
113    pub common: CacheSettings,
114
115    /// The memory store's own settings: its purge, its limit and its maps.
116    #[serde(flatten)]
117    pub memory: MemorySettings,
118
119    // Last, so it sees only the fields no other one took, and fails on them.
120    #[serde(flatten, skip_serializing)]
121    pub(crate) unknown_fields: NoUnknownFields,
122}
123
124// Every setting at its default, as `MemorySettings` and `CacheSettings` give them.
125impl Default for InMemoryCacheSettings {
126    fn default() -> Self {
127        Self {
128            common: CacheSettings::default(),
129            memory: MemorySettings::default(),
130            unknown_fields: NoUnknownFields,
131        }
132    }
133}
134
135impl InMemoryCacheSettings {
136    /// Fails when a setting is out of range, as [`MemorySettings::validate`] and
137    /// [`CacheSettings::validate`] say.
138    pub fn validate(&self) -> Result<(), CacheError> {
139        self.common.validate()?;
140        self.memory.validate()
141    }
142}
143
144#[cfg(test)]
145mod tests {
146    use sisa_caching_core::settings::MAX_TTL_SECS;
147
148    use super::*;
149
150    #[test]
151    fn out_of_range_settings_are_rejected() {
152        let too_long = Some(MAX_TTL_SECS + 1);
153        let memory = |memory| InMemoryCacheSettings {
154            memory,
155            ..InMemoryCacheSettings::default()
156        };
157
158        for (field, settings) in [
159            (
160                "default_ttl_secs",
161                InMemoryCacheSettings {
162                    common: {
163                        let mut settings = CacheSettings::default();
164                        settings.default_ttl_secs = too_long;
165                        settings
166                    },
167                    ..InMemoryCacheSettings::default()
168                },
169            ),
170            (
171                "purge_interval_secs",
172                memory(MemorySettings {
173                    purge_interval_secs: too_long,
174                    ..MemorySettings::default()
175                }),
176            ),
177            (
178                "purge_interval_secs",
179                memory(MemorySettings {
180                    purge_interval_secs: Some(0),
181                    ..MemorySettings::default()
182                }),
183            ),
184            (
185                "max_entries",
186                memory(MemorySettings {
187                    max_entries: Some(0),
188                    ..MemorySettings::default()
189                }),
190            ),
191            (
192                "shards",
193                memory(MemorySettings {
194                    shards: Some(0),
195                    ..MemorySettings::default()
196                }),
197            ),
198            (
199                "shards",
200                memory(MemorySettings {
201                    shards: Some(MAX_SHARDS + 1),
202                    ..MemorySettings::default()
203                }),
204            ),
205        ] {
206            assert!(
207                matches!(settings.validate(), Err(CacheError::InvalidSettings { field: rejected, .. }) if rejected == field),
208                "{settings:?}"
209            );
210        }
211
212        let year = Some(MAX_TTL_SECS);
213        let settings = InMemoryCacheSettings {
214            common: {
215                let mut settings = CacheSettings::default();
216                settings.default_ttl_secs = year;
217                settings
218            },
219            memory: MemorySettings {
220                purge_interval_secs: year,
221                shards: Some(MAX_SHARDS),
222                ..MemorySettings::default()
223            },
224            ..InMemoryCacheSettings::default()
225        };
226
227        assert!(
228            settings.validate().is_ok(),
229            "exactly 365 days and 1,024 maps are allowed"
230        );
231    }
232
233    #[test]
234    fn by_default_purging_runs_every_minute_nothing_is_capped_and_there_are_16_maps() {
235        let settings = InMemoryCacheSettings::default();
236
237        assert_eq!(settings.common, CacheSettings::default());
238        assert_eq!(
239            settings.memory.purge_interval(),
240            Some(Duration::from_secs(60))
241        );
242        assert_eq!(settings.memory.max_entries, None);
243        assert_eq!(settings.memory.shards(), 16);
244    }
245
246    #[test]
247    fn none_turns_a_limit_off() {
248        let settings = MemorySettings {
249            purge_interval_secs: None,
250            max_entries: None,
251            shards: None,
252        };
253
254        assert!(settings.validate().is_ok());
255        assert_eq!(settings.purge_interval(), None);
256        assert_eq!(settings.max_entries, None);
257        assert_eq!(settings.shards(), 1);
258    }
259}