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
//! Step points of the dependent-write race (R5.13), for the engine's own
//! tests only.
//!
//! A dependent write ([`crate::AppendRegion::append_after`] and the rest)
//! reports each step of its order, and a recycle or release reports its
//! drain, to a callback a test installs. The callback may park the calling
//! thread until the test releases it, so a test can start a recycle at any
//! step and see where the two meet.
//!
//! Without the engine's `sim-hooks` feature the module is private, its
//! step reports compile to nothing and there is no way to install a hook.
//! The feature is unstable and for tests only: the engine enables it for
//! its own integration tests through a dev-dependency on itself, never for
//! a release build.

/// A point a dependent write or a retirement reports.
#[doc(hidden)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Step {
    /// A dependent write, its dependencies checked, before it takes its
    /// lane (a `Submitter`'s takes none: before its passes).
    BeforeLane,
    /// Holding its lane, before its passes.
    BeforePasses,
    /// Holding its passes, before its reservation (a page write, which
    /// reserves nothing: before its issue).
    BeforeReserve,
    /// Reserved (a page write: about to issue), its passes still held; they
    /// are dropped next.
    Reserved,
    /// A recycle or release has retired the region's gate and is about to
    /// wait for the passes in flight (it holds no lock yet).
    RecycleDraining,
    /// That wait returned: no pass is left, none will be admitted.
    RecycleDrained,
    /// A set barrier, a handed-off store still unanswered, about to sleep on
    /// its answers. It holds their lock: a poison waker's wake, which takes
    /// it, can only come once the call sleeps.
    AnswersWait,
    /// A set barrier with stores handed off checking their answers while
    /// it yields (once per check, before it reads them; the last check may
    /// find them all posted).
    AnswersYield,
    /// A flush thread has posted a set barrier's answer and is about to
    /// signal it.
    AnswerPosted,
    /// The blocking pump at the top of its loop, before its poison check
    /// and its next write piece (once per piece, and once more before it
    /// finds its source done).
    PumpPiece,
    /// Provisioning's fill, before its poison check and its next piece.
    FillPiece,
    /// A copy's reader, its feed full and its scan's reads drained, about
    /// to block on its send.
    FeedBlocking,
    /// A read stream, its gate checked, about to take a buffer and submit a
    /// read (once per try: also when no buffer is free or pacing refuses).
    StreamSubmit,
    /// A read stream has seen a read's completion and is about to check its
    /// gate before delivering anything of it.
    StreamCompleted,
    /// A read stream's bisection has completed its reads and is about to
    /// check the gate before queueing its items.
    StreamBisected,
    /// A refused background piece's admission, its call's collectors run
    /// one completion at a time until a piece would be admitted, about to
    /// try it again.
    CollectRetry,
    /// A recycle has rewritten its region's header (the gate retired) and
    /// is about to swap the region list's entry for the new generation (it
    /// holds no lock).
    RecycleRewritten,
    /// A copy's or an export's plan has read every region's header, each
    /// lock taken alone, and is about to take the metadata lock.
    PlanHeaders,
}

#[cfg(feature = "sim-hooks")]
static HOOK: std::sync::RwLock<Option<fn(Step)>> = std::sync::RwLock::new(None);

/// Installs `hook` (or removes it, with `None`) for every later step in the
/// process.
#[cfg(feature = "sim-hooks")]
#[doc(hidden)]
pub fn install(hook: Option<fn(Step)>) {
    *HOOK
        .write()
        .unwrap_or_else(std::sync::PoisonError::into_inner) = hook;
}

#[cfg(feature = "sim-hooks")]
std::thread_local! {
    static UNSEEN: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// Runs `f` as another process would: the opens, resumes and closes it
/// makes on this thread are not recorded in the process's registry of
/// opens (`frontier.rs`), as an open by another process never is.
#[cfg(feature = "sim-hooks")]
#[doc(hidden)]
pub fn unseen<R>(f: impl FnOnce() -> R) -> R {
    struct Restore(bool);
    impl Drop for Restore {
        fn drop(&mut self) {
            UNSEEN.with(|u| u.set(self.0));
        }
    }
    let _restore = Restore(UNSEEN.with(|u| u.replace(true)));
    f()
}

#[cfg(feature = "sim-hooks")]
std::thread_local! {
    static NO_FLUSH_THREADS: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// Runs `f` as if the OS refused every thread: a store's flush thread
/// started on this thread meanwhile fails to start (its flushes then run on
/// the thread asking for them).
#[cfg(feature = "sim-hooks")]
#[doc(hidden)]
pub fn without_flush_threads<R>(f: impl FnOnce() -> R) -> R {
    struct Restore(bool);
    impl Drop for Restore {
        fn drop(&mut self) {
            NO_FLUSH_THREADS.with(|u| u.set(self.0));
        }
    }
    let _restore = Restore(NO_FLUSH_THREADS.with(|u| u.replace(true)));
    f()
}

/// Whether a flush thread may start on this thread (always, without the
/// feature).
#[inline]
pub(crate) fn flush_threads() -> bool {
    #[cfg(feature = "sim-hooks")]
    {
        !NO_FLUSH_THREADS.with(std::cell::Cell::get)
    }
    #[cfg(not(feature = "sim-hooks"))]
    {
        true
    }
}

/// Whether this thread's opens are recorded (always, without the
/// feature).
#[inline]
pub(crate) fn seen() -> bool {
    #[cfg(feature = "sim-hooks")]
    {
        !UNSEEN.with(std::cell::Cell::get)
    }
    #[cfg(not(feature = "sim-hooks"))]
    {
        true
    }
}

/// Reports `s` to the installed hook, if any. The pointer is copied out
/// first, so the hook runs with no lock held.
#[inline]
pub(crate) fn step(s: Step) {
    #[cfg(feature = "sim-hooks")]
    {
        let hook = *HOOK
            .read()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if let Some(hook) = hook {
            hook(s);
        }
    }
    #[cfg(not(feature = "sim-hooks"))]
    let _unused = s;
}

/// One hook for the engine's own unit tests, which share a process: each
/// test queues an action for its own thread at a step ([`lib_tests::at`]),
/// so tests running in parallel never replace each other's hook.
#[cfg(all(test, not(loom), feature = "sim-hooks"))]
pub(crate) mod lib_tests {
    use std::sync::{Mutex, PoisonError};
    use std::thread::ThreadId;

    use super::Step;

    type Action = Box<dyn FnOnce() + Send>;

    static PENDING: Mutex<Vec<(Step, ThreadId, Action)>> = Mutex::new(Vec::new());

    /// Runs `act` on this thread at its next `step` (once).
    pub(crate) fn at(step: Step, act: Action) {
        PENDING
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .push((step, std::thread::current().id(), act));
        super::install(Some(dispatch));
    }

    /// Drops this thread's actions not yet run.
    pub(crate) fn clear() {
        let me = std::thread::current().id();
        PENDING
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .retain(|(_, t, _)| *t != me);
    }

    fn dispatch(step: Step) {
        let me = std::thread::current().id();
        let act = {
            let mut p = PENDING.lock().unwrap_or_else(PoisonError::into_inner);
            p.iter()
                .position(|(s, t, _)| *s == step && *t == me)
                .map(|i| p.remove(i).2)
        };
        if let Some(act) = act {
            act();
        }
    }
}