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