store_io_engine/options.rs
1//! How a region is provisioned (v0.5 E4 C10).
2
3use store_io_core::error::{Error, ErrorContext, NotWrittenCause};
4
5/// A region's size, and the most it may ever grow to.
6///
7/// ```
8/// use store_io_engine::RegionOptions;
9///
10/// // 64 MiB now, never more than 1 GiB: one extent of 1 GiB, so the
11/// // region grows to its cap without new space or a second extent.
12/// let opts = RegionOptions::default().size(64 << 20).max_size(1 << 30);
13/// assert!(opts.validate().is_ok());
14/// assert!(RegionOptions::default().size(2).max_size(1).validate().is_err());
15/// ```
16#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
17pub struct RegionOptions {
18 size: u64,
19 max_size: Option<u64>,
20}
21
22impl RegionOptions {
23 /// The data size to provision, in bytes (rounded up to the block; a
24 /// page or append region holds at least one block).
25 #[must_use]
26 pub const fn size(mut self, bytes: u64) -> Self {
27 self.size = bytes;
28 self
29 }
30
31 /// The most the region may ever grow to, in bytes (rounded up to the
32 /// block). Container format 2 only: the region is placed as one extent
33 /// of this capacity (its space held from the start, charged to its tag)
34 /// and grows within it, one run, with no new space; growth past it is
35 /// `NoSpace(RegionLimit)`. Without it a region grows by new extents
36 /// while the container has room.
37 ///
38 /// The space past the size is allocated, not written, where the system
39 /// can (Linux); on Windows and macOS it is written at provisioning (a
40 /// 64 GiB cap is a 64 GiB write, during which other provisioning and
41 /// space reports wait), and each growth within it writes its range
42 /// again (as everywhere).
43 #[must_use]
44 pub const fn max_size(mut self, bytes: u64) -> Self {
45 self.max_size = Some(bytes);
46 self
47 }
48
49 /// The data size asked for.
50 #[must_use]
51 pub const fn size_bytes(&self) -> u64 {
52 self.size
53 }
54
55 /// The cap asked for, if any.
56 #[must_use]
57 pub const fn max_size_bytes(&self) -> Option<u64> {
58 self.max_size
59 }
60
61 /// Checks the options alone (no store needed).
62 ///
63 /// # Errors
64 ///
65 /// `NotWritten(InvalidOptions)` for a cap below the size.
66 pub fn validate(&self) -> Result<(), Error> {
67 match self.max_size {
68 Some(cap) if cap < self.size => Err(Error::NotWritten {
69 cause: NotWrittenCause::InvalidOptions,
70 ctx: ErrorContext::default(),
71 }),
72 _ => Ok(()),
73 }
74 }
75}