1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
use std::time::Duration;
pub(crate) const DEFAULT_L1_SHARDS: usize = 32;
pub(crate) const MAX_APPEND_SHARDS: u32 = 256;
pub(crate) const MAX_WRITE_FLUSH_THRESHOLD_BYTES: usize = 4 * 1024 * 1024;
pub(crate) const MAX_READ_IO_WAIT_TIMEOUT: Duration = Duration::from_secs(5);
const DEFAULT_L1_CAPACITY_BYTES: usize = 256 * 1024 * 1024;
const DEFAULT_APPEND_SHARDS: u32 = 4;
const IO_URING_DEPTH_PER_WORKER: usize = 64;
/// Runtime implementation used by the independent read, write, and reclaim
/// I/O pools.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum IoEngine {
/// Worker-backed POSIX positioned I/O.
#[default]
Posix,
/// Linux io_uring, available only with the `io-uring` crate feature.
IoUring,
}
impl IoEngine {
pub(crate) const fn is_available(self) -> bool {
match self {
Self::Posix => true,
Self::IoUring => cfg!(all(
feature = "io-uring",
target_os = "linux",
any(
target_arch = "x86_64",
target_arch = "aarch64",
target_arch = "riscv64",
target_arch = "loongarch64",
target_arch = "powerpc64"
)
)),
}
}
}
/// Buffered/direct policy for runtime cache-record I/O.
///
/// Control files, recovery images, and any necessarily unaligned remainder use
/// buffered I/O in every mode.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum IoMode {
/// Always use buffered positioned I/O.
#[default]
Buffered,
/// Require Linux `O_DIRECT` support for aligned record I/O.
///
/// Aligned direct-I/O errors are returned instead of falling back. A
/// necessarily unaligned remainder still uses the buffered descriptor.
Direct,
}
impl IoMode {
pub(crate) const fn is_available(self) -> bool {
match self {
Self::Buffered => true,
Self::Direct => cfg!(target_os = "linux"),
}
}
}
/// Eviction policy for the process-local L1 tier.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum L1EvictionPolicy {
/// One-bit shard-local CLOCK with bounded victim scans.
#[default]
Clock,
/// Three static FIFO queues: small, main, and a metadata-only ghost queue.
S3Fifo,
}
/// Process-local cache topology and resource tuning validated during open.
///
/// These values do not form the static disk identity. They may change across
/// opens, although changing the append-shard count makes an existing clean
/// recovery image ineligible and therefore starts with an empty cache.
#[derive(Clone, Debug)]
pub struct RuntimeConfig {
pub(crate) io_engine: IoEngine,
pub(crate) io_mode: IoMode,
pub(crate) read_io_workers: usize,
pub(crate) read_io_wait_timeout: Duration,
pub(crate) write_io_workers: usize,
pub(crate) reclaim_workers: usize,
pub(crate) append_shards: u32,
pub(crate) l1_capacity_bytes: usize,
pub(crate) l1_eviction_policy: L1EvictionPolicy,
pub(crate) managed_memory_limit_bytes: usize,
pub(crate) l1_shards: usize,
pub(crate) write_flush_threshold_bytes: usize,
pub(crate) statistics: bool,
}
impl Default for RuntimeConfig {
fn default() -> Self {
Self {
io_engine: IoEngine::Posix,
io_mode: IoMode::Buffered,
read_io_workers: 4,
read_io_wait_timeout: Duration::ZERO,
write_io_workers: 4,
reclaim_workers: 1,
append_shards: DEFAULT_APPEND_SHARDS,
l1_capacity_bytes: DEFAULT_L1_CAPACITY_BYTES,
l1_eviction_policy: L1EvictionPolicy::Clock,
managed_memory_limit_bytes: 1024 * 1024 * 1024,
l1_shards: DEFAULT_L1_SHARDS,
write_flush_threshold_bytes: MAX_WRITE_FLUSH_THRESHOLD_BYTES,
statistics: false,
}
}
}
impl RuntimeConfig {
/// Selects the implementation used by the independent I/O pools.
///
/// POSIX worker-backed positioned I/O is the default. `IoUring` requires
/// the `io-uring` crate feature and a supported Linux target.
pub fn with_io_engine(mut self, engine: IoEngine) -> Self {
self.io_engine = engine;
self
}
/// Selects the buffered/direct policy for runtime record I/O.
///
/// Buffered I/O is the default. `Direct` requires Linux `O_DIRECT` support
/// and returns direct-I/O errors without retrying through buffered I/O.
pub fn with_io_mode(mut self, mode: IoMode) -> Self {
self.io_mode = mode;
self
}
/// Sets read execution concurrency.
///
/// With the POSIX engine this is both the number of worker threads and the
/// maximum number of admitted reads, in `1..=4096`. With `io_uring` it is
/// the number of independent fixed-depth rings.
pub fn with_read_io_workers(mut self, workers: usize) -> Self {
self.read_io_workers = workers;
self
}
/// Sets how long an L2 candidate may wait for read execution capacity.
///
/// Zero, the default, preserves immediate fail-open misses under read-pool
/// pressure. A non-zero timeout enables a bounded wait queue with at most
/// one waiter per configured read worker. Queue saturation, allocation
/// pressure, and timeout are returned as overload errors rather than cache
/// misses, allowing the caller to prefer local backpressure over origin I/O.
/// The timeout must not exceed five seconds.
pub fn with_read_io_wait_timeout(mut self, timeout: Duration) -> Self {
self.read_io_wait_timeout = timeout;
self
}
/// Sets write execution concurrency independently from reads.
///
/// With the POSIX engine this is both the number of worker threads and the
/// maximum number of in-flight writes, in `1..=4096`. With `io_uring` it is
/// the number of independent fixed-depth rings.
pub fn with_write_io_workers(mut self, workers: usize) -> Self {
self.write_io_workers = workers;
self
}
/// Sets the number of concurrent Region reclaim workers.
///
/// Each worker owns one Region-sized scan buffer and one reclaim I/O lane.
/// The count must be non-zero and no greater than the append-shard count;
/// additional workers cannot increase the per-shard clean reserve.
pub fn with_reclaim_workers(mut self, workers: usize) -> Self {
self.reclaim_workers = workers;
self
}
/// Sets the number of hash-routed append/staging paths created at open.
///
/// Each path owns one Active Region, two Region-sized write buffers, and
/// one ordered shard worker. The static geometry must provide one Region
/// per append shard plus at least one spare Region. The valid range is
/// `1..=256`.
///
/// Changing this value across opens safely cold-starts the disposable cache
/// instead of migrating recovered shard state; it does not change the
/// static disk identity.
pub fn with_append_shards(mut self, shards: u32) -> Self {
self.append_shards = shards;
self
}
/// Sets the retained-entry byte budget for L1. Zero disables L1.
///
/// Entry charges include the key, value, and fixed ownership charge. L1
/// slot, eviction-policy, free-list, and directory allocations are
/// accounted separately against the managed-memory limit.
pub fn with_l1_capacity_bytes(mut self, bytes: usize) -> Self {
self.l1_capacity_bytes = bytes;
self
}
/// Selects the bounded shard-local L1 eviction policy.
///
/// CLOCK is the default. S3-FIFO adds a metadata-only ghost queue and uses
/// a two-bit hit counter without moving entries on the hit path.
pub fn with_l1_eviction_policy(mut self, policy: L1EvictionPolicy) -> Self {
self.l1_eviction_policy = policy;
self
}
/// Sets the aggregate cache-managed memory budget.
///
/// The budget accounts for the index mapping extent, L1, append staging,
/// cache-owned thread topology, metadata, recovery scratch, and transient
/// record reads. It is not a bound on process RSS, allocator metadata,
/// Tokio, or the kernel page cache.
pub fn with_managed_memory_limit_bytes(mut self, bytes: usize) -> Self {
self.managed_memory_limit_bytes = bytes;
self
}
/// Sets the number of independently locked L1 shards, in `1..=65536`.
///
/// Power-of-two counts use the cheapest routing path. More shards reduce
/// contention but increase fixed metadata and runtime-control accounting.
pub fn with_l1_shards(mut self, shards: usize) -> Self {
self.l1_shards = shards;
self
}
/// Sets the per-append-shard buffered-byte threshold for requesting a flush.
///
/// This is not a maximum record or I/O size: a record may cross the
/// threshold, and partial buffers also flush after the bounded delay or
/// during pressure and lifecycle barriers. The value must be a non-zero
/// 4 KiB multiple no larger than 4 MiB.
pub fn with_write_flush_threshold_bytes(mut self, bytes: usize) -> Self {
self.write_flush_threshold_bytes = bytes;
self
}
/// Enables optional cumulative request, L1, index, and I/O counters.
///
/// Health and managed-resource gauges remain available when disabled.
pub fn with_statistics(mut self, enabled: bool) -> Self {
self.statistics = enabled;
self
}
/// Returns the configured I/O engine.
pub const fn io_engine(&self) -> IoEngine {
self.io_engine
}
/// Returns the configured runtime record-I/O mode.
pub const fn io_mode(&self) -> IoMode {
self.io_mode
}
/// Returns the configured read execution concurrency.
pub const fn read_io_workers(&self) -> usize {
self.read_io_workers
}
/// Returns the maximum wait for L2 read execution capacity.
pub const fn read_io_wait_timeout(&self) -> Duration {
self.read_io_wait_timeout
}
/// Returns the configured write execution concurrency.
pub const fn write_io_workers(&self) -> usize {
self.write_io_workers
}
/// Returns the number of concurrent Region reclaim workers.
pub const fn reclaim_workers(&self) -> usize {
self.reclaim_workers
}
/// Returns the number of hash-routed append shards.
pub const fn append_shards(&self) -> u32 {
self.append_shards
}
/// Returns the retained-entry byte budget for L1.
pub const fn l1_capacity_bytes(&self) -> usize {
self.l1_capacity_bytes
}
/// Returns the configured L1 eviction policy.
pub const fn l1_eviction_policy(&self) -> L1EvictionPolicy {
self.l1_eviction_policy
}
/// Returns the aggregate cache-managed memory budget.
pub const fn managed_memory_limit_bytes(&self) -> usize {
self.managed_memory_limit_bytes
}
/// Returns the number of independently locked L1 shards.
pub const fn l1_shards(&self) -> usize {
self.l1_shards
}
/// Returns the per-append-shard flush threshold in bytes.
pub const fn write_flush_threshold_bytes(&self) -> usize {
self.write_flush_threshold_bytes
}
/// Returns whether optional cumulative statistics are enabled.
pub const fn statistics_enabled(&self) -> bool {
self.statistics
}
pub(crate) const fn io_engine_count(&self, workers: usize) -> usize {
match self.io_engine {
IoEngine::Posix => 1,
IoEngine::IoUring => workers,
}
}
pub(crate) const fn io_depth_per_engine(&self, workers: usize) -> usize {
match self.io_engine {
IoEngine::Posix => workers,
IoEngine::IoUring => IO_URING_DEPTH_PER_WORKER,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn runtime_defaults_are_stable() {
let config = RuntimeConfig::default();
assert_eq!(config.io_engine(), IoEngine::Posix);
assert_eq!(config.io_mode(), IoMode::Buffered);
assert_eq!(config.read_io_workers(), 4);
assert_eq!(config.read_io_wait_timeout(), Duration::ZERO);
assert_eq!(config.write_io_workers(), 4);
assert_eq!(config.reclaim_workers(), 1);
assert_eq!(config.append_shards(), DEFAULT_APPEND_SHARDS);
assert_eq!(config.l1_capacity_bytes(), DEFAULT_L1_CAPACITY_BYTES);
assert_eq!(config.l1_eviction_policy(), L1EvictionPolicy::Clock);
assert_eq!(config.managed_memory_limit_bytes(), 1024 * 1024 * 1024);
assert_eq!(config.l1_shards(), DEFAULT_L1_SHARDS);
assert_eq!(
config.write_flush_threshold_bytes(),
MAX_WRITE_FLUSH_THRESHOLD_BYTES
);
assert!(!config.statistics_enabled());
}
#[test]
fn io_engine_capacity_matches_backend_shape() {
let posix = RuntimeConfig::default();
assert_eq!(posix.io_engine_count(7), 1);
assert_eq!(posix.io_depth_per_engine(7), 7);
let io_uring = posix.with_io_engine(IoEngine::IoUring);
assert_eq!(io_uring.io_engine_count(7), 7);
assert_eq!(io_uring.io_depth_per_engine(7), IO_URING_DEPTH_PER_WORKER);
}
}