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<'_> {}