Skip to main content

store_io_engine/
completion.rs

1//! What the engine-layer [`crate::Submitter`] hands back (D-098): its
2//! configuration, refusals and completions.
3
4use std::collections::VecDeque;
5use store_io_core::IoClass;
6
7use store_io_core::error::Error;
8use store_io_platform::IoBuf;
9
10use crate::receipt::{DurableReceipt, WriteTicket};
11
12/// How a [`crate::Submitter`] is set up:
13/// `SubmitterConfig::default().with_depth(128)`.
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15#[non_exhaustive]
16pub struct SubmitterConfig {
17    /// Operations submitted and not yet taken back from `reap` or `wait`, at
18    /// most (1 to [`crate::MAX_DEPTH`]; default 64). Also the depth of the
19    /// submitter's queue.
20    pub depth: u32,
21    /// The class of this submitter's I/O (PLANNING R5.4).
22    ///
23    /// - `Commit` (the default): never paced; its barriers, and on a
24    ///   power-safe store its writes, mark the device's commits active.
25    /// - `Background`: its reads and writes go out in pieces of at most
26    ///   `StoreOptions::background_io`, admitted by its device's pacing: while
27    ///   the device's commits are active, one piece of the submitter in
28    ///   flight (unless its group has room), else up to
29    ///   `background_unpaced`. An operation refused before anything is
30    ///   reserved is `NotWritten(Paced)` with its buffer (reap and retry);
31    ///   its later pieces wait in the submitter, oldest first, and go out at
32    ///   its next `reap` or `wait`, or at its drop. Its buffers
33    ///   ([`crate::Submitter::take_buf`]) never hold more than half of a pool
34    ///   class; its barriers and writes never mark commits active. An append
35    ///   whose pieces wait holds back its region's completed prefix, so a
36    ///   commit syncing that region waits for the submitter's thread to reap
37    ///   or wait: keep commits and background appends in separate regions.
38    /// - `Read`: its reads are of the read class, its writes `Commit`.
39    pub class: IoClass,
40}
41
42impl Default for SubmitterConfig {
43    fn default() -> Self {
44        Self {
45            depth: 64,
46            class: IoClass::Commit,
47        }
48    }
49}
50
51impl SubmitterConfig {
52    /// The same, with `depth`.
53    #[must_use]
54    pub fn with_depth(mut self, depth: u32) -> Self {
55        self.depth = depth;
56        self
57    }
58
59    /// The same, of `class`.
60    #[must_use]
61    pub fn with_class(mut self, class: IoClass) -> Self {
62        self.class = class;
63        self
64    }
65}
66
67/// An operation the submitter refused: nothing was submitted, unless
68/// `error` is `DurabilityUnknown` (an append refused by the OS after its
69/// position was reserved, which poisons the store as a failed blocking
70/// append does). The buffer comes back; `None` only from a backend that
71/// broke its contract and kept it.
72#[derive(Debug)]
73pub struct Rejected {
74    /// Why.
75    pub error: Error,
76    /// The operation's buffer.
77    pub buf: Option<IoBuf>,
78}
79
80/// A write that completed in full.
81#[derive(Debug, PartialEq, Eq)]
82pub struct Written {
83    /// The write's ticket, for `sync_through` on its region. Minted only
84    /// now, when every byte has been transferred (D-080).
85    pub ticket: WriteTicket,
86    /// For a [`WriteMode::Durable`] write, the receipt for its own range;
87    /// `None` for a plain write (make the ticket durable with a barrier or
88    /// `sync_through`).
89    pub receipt: Option<DurableReceipt>,
90}
91
92/// How a submitter write is made durable (D-099).
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
94#[non_exhaustive]
95pub enum WriteMode {
96    /// The completion carries the ticket; make it durable with a barrier.
97    #[default]
98    Plain,
99    /// The completion is handed back only once the write is durable, with a
100    /// receipt (a prefix receipt for an append whose region was complete up
101    /// to it, else one for its own range): at once on a power-safe store
102    /// (the write itself was durable) unless its region forces data sync,
103    /// else after a covering flush.
104    Durable,
105}
106
107/// What a successful operation did.
108#[derive(Debug, PartialEq, Eq)]
109#[non_exhaustive]
110pub enum Done {
111    /// An append or page write.
112    Written(Written),
113    /// A barrier for one ticket: a receipt for that ticket's range.
114    Synced(DurableReceipt),
115    /// A barrier for the whole store: every write that completed in the
116    /// store before it was submitted is durable.
117    Flushed,
118    /// A read: the bytes read into the buffer, whose length is set to it
119    /// (fewer than asked only if the device returned fewer).
120    Read {
121        /// Bytes read.
122        len: usize,
123    },
124}
125
126/// One finished operation.
127#[derive(Debug)]
128pub struct Completion {
129    /// The tag given at submission.
130    pub tag: u64,
131    /// The operation's buffer, given back (for a read, holding the bytes);
132    /// `None` only from a backend that broke its contract and kept it.
133    pub buf: Option<IoBuf>,
134    /// The result. A write that failed or transferred short after it was
135    /// issued is `DurabilityUnknown`, and the store is poisoned (as for the
136    /// blocking calls). A read the device could not do is
137    /// `Corruption(MediaError)` for the read's whole range (narrow it with a
138    /// scan), or `Io` with the raw code for any other failure.
139    pub outcome: Result<Done, Error>,
140}
141
142/// Completions handed back by `reap` or `wait`, in the order they were
143/// collected. Any not taken from the iterator stay for the next call (and
144/// count against the submitter's depth).
145#[derive(Debug)]
146#[must_use = "completions not taken stay with the submitter and count against its depth"]
147pub struct Completions<'a> {
148    pub(crate) ready: &'a mut VecDeque<Completion>,
149}
150
151impl Iterator for Completions<'_> {
152    type Item = Completion;
153
154    fn next(&mut self) -> Option<Completion> {
155        self.ready.pop_front()
156    }
157
158    fn size_hint(&self) -> (usize, Option<usize>) {
159        (self.ready.len(), Some(self.ready.len()))
160    }
161}
162
163impl ExactSizeIterator for Completions<'_> {}