store-io-engine 0.6.0

The store-io engine: volumes, regions, barriers with flush sharing, receipts, provisioning and A/B slot objects over any store-io platform.
Documentation
//! An export's call, bound to its thread (R5.4, R5.6): the reference sinks
//! made by the caller before the call find it when they begin, join its
//! record for their device group, and report to it, so the export knows
//! whether every part of it finished, whatever a caller's wrapper around a
//! sink returned.

use std::cell::{Cell, RefCell};
use std::marker::PhantomData;
use std::rc::Rc;
use std::sync::Arc;

use store_io_core::error::Error;
use store_io_platform::Clock;

use crate::pace::Pace;
use crate::qos::Qos;

/// A part's failure, where the export was when it happened.
#[derive(Clone)]
pub(crate) struct Failure {
    pub(crate) error: Error,
    /// The export's region index then: the region being exported
    /// (`inside`), or the next one to start (between regions, at `begin`
    /// or, past the last, at `finish`).
    pub(crate) region: u32,
    pub(crate) inside: bool,
    /// Inside a region: the offset in its stream the failure is at (a
    /// failed write's start, a refused call's bytes accepted so far).
    pub(crate) offset: u64,
}

/// One call's state.
pub(crate) struct CallState {
    /// The source store's device group and the call's record on it (none
    /// for an import: its source is a part that joins like any other).
    source: Option<Arc<Qos>>,
    source_pace: Option<Pace>,
    /// The call's records on other groups, made when a part first joins.
    others: RefCell<Vec<(Arc<Qos>, Pace)>>,
    /// A part joined the source's record (the stream then leaves it a
    /// piece: `Pace::second`).
    shares_source: Cell<bool>,
    /// Reference sinks bound to the call, and those that finished.
    sinks: Cell<u32>,
    finished: Cell<u32>,
    /// Each bound reference sink's writes done: the region index and the
    /// offset in its stream they reach (R5.6: the report advances only
    /// over writes a sink completed).
    written: RefCell<Vec<(u32, u64)>>,
    /// Each bound reference sink's regions ended, from the first, without
    /// a gap: a region counts as exported only once every one ended it.
    ended: RefCell<Vec<u32>>,
    /// The first failure a part recorded (sticky).
    failure: RefCell<Option<Failure>>,
    /// Where the export is: its region index, whether inside it, and the
    /// bytes it had exported when each region began.
    region: Cell<u32>,
    inside: Cell<bool>,
    bases: RefCell<Vec<u64>>,
}

impl CallState {
    pub(crate) fn new(source: Arc<Qos>, source_pace: Option<Pace>) -> Rc<Self> {
        Self::with_source(Some(source), source_pace)
    }

    /// A call with no source store (an import): every part's record is
    /// made when it first joins.
    pub(crate) fn detached() -> Rc<Self> {
        Self::with_source(None, None)
    }

    fn with_source(source: Option<Arc<Qos>>, source_pace: Option<Pace>) -> Rc<Self> {
        Rc::new(Self {
            source,
            source_pace,
            others: RefCell::new(Vec::new()),
            shares_source: Cell::new(false),
            sinks: Cell::new(0),
            finished: Cell::new(0),
            written: RefCell::new(Vec::new()),
            ended: RefCell::new(Vec::new()),
            failure: RefCell::new(None),
            region: Cell::new(0),
            inside: Cell::new(false),
            bases: RefCell::new(Vec::new()),
        })
    }

    /// The call's record on `qos`'s group: the source's when it is the
    /// source's group (the part then shares it), else one made for that
    /// group the first time a part joins it.
    pub(crate) fn pace_for(&self, qos: &Arc<Qos>, clock: &Clock) -> Option<Pace> {
        if self
            .source
            .as_ref()
            .is_some_and(|s| Qos::same_group(s, qos))
        {
            self.shares_source.set(true);
            return self.source_pace.clone();
        }
        let mut others = self.others.borrow_mut();
        if let Some((_, p)) = others.iter().find(|(q, _)| Qos::same_group(q, qos)) {
            return Some(p.clone());
        }
        let p = Pace::new(qos, Arc::clone(clock));
        others.push((Arc::clone(qos), p.clone()));
        Some(p)
    }

    /// Whether a part joined the source's record.
    pub(crate) fn shares_source(&self) -> bool {
        self.shares_source.get()
    }

    /// A reference sink bound itself to the call: its id for
    /// [`Self::wrote`].
    pub(crate) fn sink_bound(&self) -> usize {
        self.sinks.set(self.sinks.get().saturating_add(1));
        self.ended.borrow_mut().push(0);
        let mut w = self.written.borrow_mut();
        w.push((u32::MAX, 0));
        w.len() - 1
    }

    /// Sink `id` ended the export's current region (its `end_region`
    /// returned `Ok`): counted when it ended every region before it.
    pub(crate) fn region_ended(&self, id: usize) {
        let region = self.region.get();
        if let Some(n) = self.ended.borrow_mut().get_mut(id) {
            if *n == region {
                *n = region.saturating_add(1);
            }
        }
    }

    /// The regions, from the first, every bound reference sink ended;
    /// `None` with no reference sink bound.
    pub(crate) fn regions_ended(&self) -> Option<u32> {
        self.ended.borrow().iter().copied().min()
    }

    /// Sink `id`'s writes done in the export's current region reach
    /// `offset` of its stream.
    pub(crate) fn wrote(&self, id: usize, offset: u64) {
        let region = self.region.get();
        if let Some(w) = self.written.borrow_mut().get_mut(id) {
            *w = (region, offset);
        }
    }

    /// The offset in region `index`'s stream every bound reference sink's
    /// writes done reach (one that wrote nothing there: 0); `None` with no
    /// reference sink bound.
    pub(crate) fn written_up_to(&self, index: u32) -> Option<u64> {
        let w = self.written.borrow();
        w.iter()
            .map(|&(r, at)| if r == index { at } else { 0 })
            .min()
    }

    /// A bound reference sink finished.
    pub(crate) fn sink_finished(&self) {
        self.finished.set(self.finished.get().saturating_add(1));
    }

    /// Whether every bound reference sink finished.
    pub(crate) fn all_finished(&self) -> bool {
        self.finished.get() >= self.sinks.get()
    }

    /// The export begins region `index`, having exported `bytes`.
    pub(crate) fn enter(&self, index: u32, bytes: u64) {
        self.region.set(index);
        self.inside.set(true);
        let mut b = self.bases.borrow_mut();
        b.truncate(index as usize);
        b.push(bytes);
    }

    /// The export ended a region; `next` is the next one's index.
    pub(crate) fn leave(&self, next: u32) {
        self.region.set(next);
        self.inside.set(false);
    }

    /// The region the export is inside, if it is inside one.
    pub(crate) fn inside_region(&self) -> Option<u32> {
        self.inside.get().then(|| self.region.get())
    }

    /// The bytes the export had exported when region `index` began.
    pub(crate) fn base(&self, index: u32) -> Option<u64> {
        self.bases.borrow().get(index as usize).copied()
    }

    /// A part failed at `offset` of the export's current region (the first
    /// failure is kept: later refusals are its consequences).
    pub(crate) fn part_failed(&self, error: Error, offset: u64) {
        let mut f = self.failure.borrow_mut();
        if f.is_none() {
            let inside = self.inside.get();
            *f = Some(Failure {
                error,
                region: self.region.get(),
                inside,
                offset: if inside { offset } else { 0 },
            });
        }
    }

    /// The first failure a part recorded.
    pub(crate) fn failure(&self) -> Option<Failure> {
        self.failure.borrow().clone()
    }
}

thread_local! {
    /// The calls in progress on this thread, innermost last.
    static CALLS: RefCell<Vec<Rc<CallState>>> = const { RefCell::new(Vec::new()) };
}

/// A call's binding to this thread, until it drops.
pub(crate) struct Bound {
    _thread: PhantomData<*const ()>,
}

/// Binds `call` to this thread (innermost) until the guard drops.
pub(crate) fn bind(call: &Rc<CallState>) -> Bound {
    let _b = CALLS.try_with(|c| c.borrow_mut().push(Rc::clone(call)));
    Bound {
        _thread: PhantomData,
    }
}

impl Drop for Bound {
    fn drop(&mut self) {
        let _b = CALLS.try_with(|c| c.borrow_mut().pop());
    }
}

/// The innermost call bound to this thread.
pub(crate) fn current() -> Option<Rc<CallState>> {
    CALLS
        .try_with(|c| c.borrow().last().cloned())
        .ok()
        .flatten()
}