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