Skip to main content

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}