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;
5
6use store_io_core::error::Error;
7use store_io_platform::IoBuf;
8
9use crate::receipt::{DurableReceipt, WriteTicket};
10
11/// How a [`crate::Submitter`] is set up:
12/// `SubmitterConfig::default().with_depth(128)`.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14#[non_exhaustive]
15pub struct SubmitterConfig {
16    /// Operations submitted and not yet taken back from `reap` or `wait`, at
17    /// most (1 to [`crate::MAX_DEPTH`]; default 64). Also the depth of the
18    /// submitter's queue.
19    pub depth: u32,
20}
21
22impl Default for SubmitterConfig {
23    fn default() -> Self {
24        Self { depth: 64 }
25    }
26}
27
28impl SubmitterConfig {
29    /// The same, with `depth`.
30    #[must_use]
31    pub fn with_depth(mut self, depth: u32) -> Self {
32        self.depth = depth;
33        self
34    }
35}
36
37/// An operation the submitter refused: nothing was submitted, unless
38/// `error` is `DurabilityUnknown` (an append refused by the OS after its
39/// position was reserved, which poisons the store as a failed blocking
40/// append does). The buffer comes back; `None` only from a backend that
41/// broke its contract and kept it.
42#[derive(Debug)]
43pub struct Rejected {
44    /// Why.
45    pub error: Error,
46    /// The operation's buffer.
47    pub buf: Option<IoBuf>,
48}
49
50/// A write that completed in full.
51#[derive(Debug, PartialEq, Eq)]
52pub struct Written {
53    /// The write's ticket, for `sync_through` on its region. Minted only
54    /// now, when every byte has been transferred (D-080).
55    pub ticket: WriteTicket,
56    /// For a [`WriteMode::Durable`] write, the receipt for its own range;
57    /// `None` for a plain write (make the ticket durable with a barrier or
58    /// `sync_through`).
59    pub receipt: Option<DurableReceipt>,
60}
61
62/// How a submitter write is made durable (D-099).
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
64#[non_exhaustive]
65pub enum WriteMode {
66    /// The completion carries the ticket; make it durable with a barrier.
67    #[default]
68    Plain,
69    /// The completion is handed back only once the write is durable, with a
70    /// receipt (a prefix receipt for an append whose region was complete up
71    /// to it, else one for its own range): at once on a power-safe store
72    /// (the write itself was durable) unless its region forces data sync,
73    /// else after a covering flush.
74    Durable,
75}
76
77/// What a successful operation did.
78#[derive(Debug, PartialEq, Eq)]
79#[non_exhaustive]
80pub enum Done {
81    /// An append or page write.
82    Written(Written),
83    /// A barrier for one ticket: a receipt for that ticket's range.
84    Synced(DurableReceipt),
85    /// A barrier for the whole store: every write that completed in the
86    /// store before it was submitted is durable.
87    Flushed,
88    /// A read: the bytes read into the buffer, whose length is set to it
89    /// (fewer than asked only if the device returned fewer).
90    Read {
91        /// Bytes read.
92        len: usize,
93    },
94}
95
96/// One finished operation.
97#[derive(Debug)]
98pub struct Completion {
99    /// The tag given at submission.
100    pub tag: u64,
101    /// The operation's buffer, given back (for a read, holding the bytes);
102    /// `None` only from a backend that broke its contract and kept it.
103    pub buf: Option<IoBuf>,
104    /// The result. A write that failed or transferred short after it was
105    /// issued is `DurabilityUnknown`, and the store is poisoned (as for the
106    /// blocking calls). A read the device could not do is
107    /// `Corruption(MediaError)` for the read's whole range (narrow it with a
108    /// scan), or `Io` with the raw code for any other failure.
109    pub outcome: Result<Done, Error>,
110}
111
112/// Completions handed back by `reap` or `wait`, in the order they were
113/// collected. Any not taken from the iterator stay for the next call (and
114/// count against the submitter's depth).
115#[derive(Debug)]
116#[must_use = "completions not taken stay with the submitter and count against its depth"]
117pub struct Completions<'a> {
118    pub(crate) ready: &'a mut VecDeque<Completion>,
119}
120
121impl Iterator for Completions<'_> {
122    type Item = Completion;
123
124    fn next(&mut self) -> Option<Completion> {
125        self.ready.pop_front()
126    }
127
128    fn size_hint(&self) -> (usize, Option<usize>) {
129        (self.ready.len(), Some(self.ready.len()))
130    }
131}
132
133impl ExactSizeIterator for Completions<'_> {}