qualia_core_db/net/qdnf/resolve/qsr/
handover.rs1use super::cover::CoverInterval;
9use super::outcome::QsrOutcome;
10use super::traversal::{lookup_into, QsrSnapshot};
11use crate::net::qdnf::errors::QdnfError;
12use crate::net::qdnf::types::{Generation, StrongDigest};
13
14pub const ACCEPTED_CAP: u8 = 8;
16
17#[repr(u8)]
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub enum WriterEpoch {
21 Active = 0,
22 Fenced = 1,
23 Draining = 2,
24 Transferred = 3,
25 Ambiguous = 4,
26}
27
28#[repr(C)]
30#[derive(Clone, Copy, Debug, PartialEq, Eq)]
31pub struct Handover {
32 pub old: u64,
33 pub new: u64,
34 pub state: WriterEpoch,
35 accepted: u8,
36 transferred: u8,
37}
38
39impl Handover {
40 pub const fn start(old: u64, new: u64) -> Self {
42 Self {
43 old,
44 new,
45 state: WriterEpoch::Active,
46 accepted: 0,
47 transferred: 0,
48 }
49 }
50
51 pub const fn ambiguous(old: u64, new: u64) -> Self {
53 Self {
54 old,
55 new,
56 state: WriterEpoch::Ambiguous,
57 accepted: 0,
58 transferred: 0,
59 }
60 }
61
62 #[inline]
63 pub const fn accepted_count(&self) -> u8 {
65 self.accepted
66 }
67
68 #[inline]
69 pub const fn transferred_count(&self) -> u8 {
71 self.transferred
72 }
73}
74
75pub fn fence_old(h: &mut Handover) {
77 if h.state == WriterEpoch::Active {
78 h.state = WriterEpoch::Fenced;
79 }
80}
81
82pub fn drain_accepted(h: &mut Handover) {
84 if h.state == WriterEpoch::Fenced {
85 h.state = WriterEpoch::Draining;
86 }
87}
88
89pub fn persist_boundary(h: &mut Handover) {
92 if h.state == WriterEpoch::Draining {
93 h.transferred = h.accepted;
94 h.state = WriterEpoch::Transferred;
95 }
96}
97
98pub fn activate_new(h: &mut Handover) -> Result<(), QdnfError> {
103 match h.state {
104 WriterEpoch::Transferred => {
105 h.state = WriterEpoch::Active;
106 Ok(())
107 }
108 WriterEpoch::Active => {
109 h.state = WriterEpoch::Ambiguous;
110 Err(QdnfError::Conflict)
111 }
112 WriterEpoch::Ambiguous => Err(QdnfError::Conflict),
113 WriterEpoch::Fenced | WriterEpoch::Draining => Err(QdnfError::Incomplete),
114 }
115}
116
117pub fn admit_write(h: &Handover) -> Result<(), QdnfError> {
119 match h.state {
120 WriterEpoch::Active => Ok(()),
121 WriterEpoch::Fenced | WriterEpoch::Draining | WriterEpoch::Transferred => {
122 Err(QdnfError::Unauthorized)
123 }
124 WriterEpoch::Ambiguous => Err(QdnfError::Conflict),
125 }
126}
127
128pub fn accept_mutation(h: &mut Handover) -> Result<u8, QdnfError> {
130 admit_write(h)?;
131 if h.accepted >= ACCEPTED_CAP {
132 return Err(QdnfError::Capacity);
133 }
134 h.accepted = h.accepted + 1;
135 Ok(h.accepted)
136}
137
138pub fn lookup_via_handover(
143 h: &Handover,
144 snapshot: &QsrSnapshot,
145 key: &StrongDigest,
146 covers: &[CoverInterval],
147 required_generation: Generation,
148 out: &mut [StrongDigest],
149) -> Result<QsrOutcome, QdnfError> {
150 match h.state {
151 WriterEpoch::Transferred => {}
152 WriterEpoch::Active if h.transferred > 0 => {}
153 WriterEpoch::Ambiguous => return Ok(QsrOutcome::Conflict),
154 WriterEpoch::Fenced | WriterEpoch::Draining | WriterEpoch::Active => {
155 return Ok(QsrOutcome::Incomplete);
156 }
157 }
158 lookup_into(snapshot, key, covers, required_generation, out)
159}
160
161#[cfg(test)]
162mod tests {
163 use super::*;
164
165 #[test]
166 fn fence_rejects_writes() {
167 let mut h = Handover::start(1, 2);
168 assert_eq!(accept_mutation(&mut h), Ok(1));
169 fence_old(&mut h);
170 assert_eq!(h.state, WriterEpoch::Fenced);
171 assert_eq!(admit_write(&h), Err(QdnfError::Unauthorized));
172 assert_eq!(accept_mutation(&mut h), Err(QdnfError::Unauthorized));
173 assert_eq!(h.accepted_count(), 1);
174 }
175
176 #[test]
177 fn drain_retains_accepted_and_transfer_copies_count() {
178 let mut h = Handover::start(3, 4);
179 accept_mutation(&mut h).unwrap();
180 accept_mutation(&mut h).unwrap();
181 fence_old(&mut h);
182 drain_accepted(&mut h);
183 assert_eq!(h.state, WriterEpoch::Draining);
184 assert_eq!(h.accepted_count(), 2);
185 persist_boundary(&mut h);
186 assert_eq!(h.state, WriterEpoch::Transferred);
187 assert_eq!(h.transferred_count(), 2);
188 assert_eq!(h.transferred_count(), h.accepted_count());
189 assert_eq!(admit_write(&h), Err(QdnfError::Unauthorized));
190 }
191
192 #[test]
193 fn activate_after_transfer() {
194 let mut h = Handover::start(5, 6);
195 fence_old(&mut h);
196 drain_accepted(&mut h);
197 persist_boundary(&mut h);
198 assert_eq!(activate_new(&mut h), Ok(()));
199 assert_eq!(h.state, WriterEpoch::Active);
200 assert_eq!(accept_mutation(&mut h), Ok(1));
201 }
202
203 #[test]
204 fn ambiguous_two_active_writers_is_conflict() {
205 let mut h = Handover::start(7, 8);
206 assert_eq!(activate_new(&mut h), Err(QdnfError::Conflict));
207 assert_eq!(h.state, WriterEpoch::Ambiguous);
208 assert_eq!(activate_new(&mut h), Err(QdnfError::Conflict));
209 assert_eq!(admit_write(&h), Err(QdnfError::Conflict));
210 }
211
212 #[test]
213 fn constructed_ambiguous_is_conflict() {
214 let mut h = Handover::ambiguous(1, 2);
215 assert_eq!(h.state, WriterEpoch::Ambiguous);
216 assert_eq!(activate_new(&mut h), Err(QdnfError::Conflict));
217 }
218
219 #[test]
220 fn activate_before_transfer_is_incomplete() {
221 let mut h = Handover::start(1, 2);
222 fence_old(&mut h);
223 assert_eq!(activate_new(&mut h), Err(QdnfError::Incomplete));
224 drain_accepted(&mut h);
225 assert_eq!(activate_new(&mut h), Err(QdnfError::Incomplete));
226 }
227
228 #[test]
229 fn accepted_cap_is_bounded() {
230 let mut h = Handover::start(1, 2);
231 let mut i = 0u8;
232 while i < ACCEPTED_CAP {
233 accept_mutation(&mut h).unwrap();
234 i = i + 1;
235 }
236 assert_eq!(accept_mutation(&mut h), Err(QdnfError::Capacity));
237 }
238
239 #[test]
240 fn lookup_before_transfer_is_incomplete_not_found() {
241 let mut snap = QsrSnapshot::empty(Generation(1));
242 snap.insert(StrongDigest::ZERO, StrongDigest::ZERO).unwrap();
243 let covers = [CoverInterval { start: 0, end: 15 }];
244 let mut out = [StrongDigest::ZERO; 1];
245 let mut h = Handover::start(1, 2);
246 assert_eq!(
247 lookup_via_handover(
248 &h,
249 &snap,
250 &StrongDigest::ZERO,
251 &covers,
252 Generation(1),
253 &mut out
254 ),
255 Ok(QsrOutcome::Incomplete)
256 );
257 fence_old(&mut h);
258 drain_accepted(&mut h);
259 persist_boundary(&mut h);
260 assert_eq!(
261 lookup_via_handover(
262 &h,
263 &snap,
264 &StrongDigest::ZERO,
265 &covers,
266 Generation(1),
267 &mut out
268 ),
269 Ok(QsrOutcome::Found { count: 1 })
270 );
271 }
272}