Skip to main content

store_io_engine/
slot_handle.rs

1//! The [`Slot`] handle: a small object committed atomically (one block
2//! write plus one barrier per commit; the slot pair protocol is in
3//! `slots.rs`).
4
5use std::sync::{Arc, PoisonError};
6
7use store_io_core::error::{CorruptionKind, Error, ErrorContext, NotWrittenCause, Op};
8use store_io_format::meta::{REGION_META_LEN, RegionMeta, RegionState as Lifecycle};
9use store_io_format::slot::HEADER_LEN;
10use store_io_platform::Platform;
11
12use crate::io::ctx;
13use crate::receipt::DurableReceipt;
14use crate::slots::{PairAt, PairRead, plan_next};
15use crate::store::{LiveRegion, Store, durable_slot};
16
17/// A small object (a manifest, a superblock) committed atomically: after any
18/// crash it reads back as exactly the old or exactly the new version.
19///
20/// One commit is one block write plus one barrier. Commits to one slot are
21/// serialised (at most one slot write in flight).
22pub struct Slot<P: Platform> {
23    store: Store<P>,
24    state: Arc<LiveRegion>,
25}
26
27impl<P: Platform> Slot<P> {
28    pub(crate) fn from_parts(store: Store<P>, state: Arc<LiveRegion>) -> Self {
29        Self { store, state }
30    }
31}
32
33impl<P: Platform> Clone for Slot<P> {
34    fn clone(&self) -> Self {
35        Self {
36            store: self.store.clone(),
37            state: Arc::clone(&self.state),
38        }
39    }
40}
41
42impl<P: Platform> Slot<P>
43where
44    P::Queue: Send,
45{
46    pub(crate) fn state(&self) -> &Arc<LiveRegion> {
47        &self.state
48    }
49
50    /// Largest payload a commit accepts.
51    #[must_use]
52    pub fn capacity(&self) -> usize {
53        let l = &self.store.inner.layout;
54        if l.format == store_io_format::slot::FORMAT_2 {
55            // After the format-2 header's 64-byte fixed part.
56            store_io_format::meta2::max_object(l.log2_block)
57        } else {
58            l.block() as usize - HEADER_LEN - REGION_META_LEN
59        }
60    }
61
62    fn at(&self) -> PairAt {
63        let l = &self.store.inner.layout;
64        let [a, b] = self.state.header_at;
65        PairAt {
66            volume: *self.store.inner.volume.as_bytes(),
67            object: l.region_object(self.state.id.get()),
68            a,
69            b,
70            log2: l.log2_block,
71            format: l.format,
72            numbered: false,
73        }
74    }
75
76    /// The current committed object, or `None` if never committed.
77    ///
78    /// Generation 1 of the slot pair is the provisioning header; commits start
79    /// at generation 2.
80    #[must_use]
81    pub fn read(&self) -> Option<Vec<u8>> {
82        let h = self
83            .state
84            .header
85            .lock()
86            .unwrap_or_else(PoisonError::into_inner);
87        let (_, info) = h.report.winner_info()?;
88        if info.generation <= 1 {
89            return None;
90        }
91        let l = &self.store.inner.layout;
92        if l.format == store_io_format::slot::FORMAT_2 {
93            // The object follows the header's fixed part, `object_len` long.
94            // A slot region lists no extents, so the file length bounds
95            // nothing here (and the metadata lock is not taken under the
96            // header's: release takes them the other way round).
97            let payload = h.payload.as_deref()?;
98            let view =
99                store_io_format::meta2::decode_region_header(payload, l.log2_block, u64::MAX)
100                    .ok()?;
101            return Some(view.object().to_vec());
102        }
103        h.payload
104            .as_ref()
105            .and_then(|p| p.get(REGION_META_LEN..))
106            .map(<[u8]>::to_vec)
107    }
108
109    /// Commits a new version of the object.
110    ///
111    /// The receipt's generation counts commits (the slot pair's
112    /// generation: 2 for the first). In format 2 a slot region also has a
113    /// region generation, in its header, which a commit leaves as it is
114    /// (only a recycle moves a region generation on, and slots are never
115    /// recycled).
116    ///
117    /// # Errors
118    ///
119    /// `NotWritten(TooLarge)` beyond [`Self::capacity`], `Io` if the store's
120    /// queue could not be prepared (nothing was written), `Poisoned`, or
121    /// `DurabilityUnknown` (the domain is now poisoned).
122    pub fn commit(&self, data: &[u8]) -> Result<DurableReceipt, Error> {
123        let s = &self.store;
124        s.ready_for(&self.state)?;
125        let _timed = s
126            .inner
127            .observer
128            .span(store_io_core::observe::Stage::SlotCommit);
129        let c = ctx(&self.state);
130        if data.len() > self.capacity() {
131            return Err(Error::NotWritten {
132                cause: NotWrittenCause::TooLarge,
133                ctx: c,
134            });
135        }
136        let mut header = self
137            .state
138            .header
139            .lock()
140            .unwrap_or_else(PoisonError::into_inner);
141        let payload = if s.inner.layout.format == store_io_format::slot::FORMAT_2 {
142            format2_payload(&header, s.inner.layout.log2_block, data, c)?
143        } else {
144            format1_payload(&header, data, c)?
145        };
146        let next = plan_next(&header, &payload, s.inner.owner_generation)?;
147        let generation = next.generation;
148        let at = self.at();
149        let mut lane = s.lane(&self.state, Op::Write)?;
150        // A forced slot flushes on a power-safe store too (D-102).
151        let flushed = s.inner.policy.flush || self.state.forced();
152        let policy = crate::store::Policy {
153            flush: flushed,
154            ..s.inner.policy
155        };
156        let written = durable_slot::<P>(
157            &mut lane,
158            &s.inner.file,
159            &s.inner.pool,
160            &at,
161            &header,
162            &next,
163            &policy,
164            &s.inner.domain,
165        )
166        .inspect_err(|_| s.wake_frontiers())?;
167        *header = written;
168        // A slot has no tickets: its receipt covers the commit alone.
169        let mut receipt = s.receipt(&self.state, 0, data.len() as u64, 0, false, flushed);
170        if let Some(g) = store_io_core::id::Generation::from_raw(generation) {
171            receipt.generation = g;
172        }
173        Ok(receipt)
174    }
175}
176
177impl<P: Platform> core::fmt::Debug for Slot<P> {
178    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
179        f.debug_tuple("Slot").field(&*self.state).finish()
180    }
181}
182
183fn metadata(c: ErrorContext) -> Error {
184    Error::Corruption {
185        kind: CorruptionKind::Metadata,
186        ctx: c,
187    }
188}
189
190/// A format-1 slot payload: the region record as it is, then the object.
191fn format1_payload(header: &PairRead, data: &[u8], c: ErrorContext) -> Result<Vec<u8>, Error> {
192    let meta_bytes = header
193        .payload
194        .as_ref()
195        .and_then(|p| p.get(..REGION_META_LEN))
196        .ok_or_else(|| metadata(c))?;
197    let rm = RegionMeta::decode(meta_bytes).map_err(|_| metadata(c))?;
198    if rm.state != Lifecycle::Ready {
199        return Err(Error::NotWritten {
200            cause: NotWrittenCause::NotReady,
201            ctx: c,
202        });
203    }
204    let mut payload = Vec::with_capacity(REGION_META_LEN + data.len());
205    payload.extend_from_slice(meta_bytes);
206    payload.extend_from_slice(data);
207    Ok(payload)
208}
209
210/// A format-2 slot payload (spec ยง8): the header's fixed part as it is
211/// (region generation, fill, flags kept), `object_len` the new object's
212/// length, then the object.
213fn format2_payload(
214    header: &PairRead,
215    log2_block: u8,
216    data: &[u8],
217    c: ErrorContext,
218) -> Result<Vec<u8>, Error> {
219    let bytes = header.payload.as_deref().ok_or_else(|| metadata(c))?;
220    let view = store_io_format::meta2::decode_region_header(bytes, log2_block, u64::MAX)
221        .map_err(|_| metadata(c))?;
222    if view.header.state != Lifecycle::Ready {
223        return Err(Error::NotWritten {
224            cause: NotWrittenCause::NotReady,
225            ctx: c,
226        });
227    }
228    let mut h = view.header;
229    h.object_len = u32::try_from(data.len()).map_err(|_| metadata(c))?;
230    let mut out = vec![0u8; store_io_format::meta2::REGION_HEADER2_LEN + data.len()];
231    let n = store_io_format::meta2::encode_region_header(&mut out, &h, &[], data)
232        .map_err(|_| metadata(c))?;
233    out.truncate(n);
234    Ok(out)
235}