pigeonhole-db 1.1.0

data/vendor/pigeonhole/src/retry.rs

@@ -0,0 +1,358 @@
+//! Retrying optimistic transactions (#694, ICR 0060), and the transaction counters behind
+//! [`EngineMetrics`](crate::EngineMetrics)' transaction fields (ICR 0061).
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+use crate::{CommitInfo, Durability, Error, ErrorCode, Pigeonhole, Result, Transaction};
+
+/// How [`Pigeonhole::transact`] retries a transaction (ICR 0060).
+///
+/// An attempt that fails with [`ErrorCode::Conflict`] (something it read changed before it
+/// committed) or [`ErrorCode::SnapshotExpired`] (a recovery replaced the engine it began on)
+/// is retried after a pause; with [`retry_busy`](Self::retry_busy), so is one that fails
+/// with [`ErrorCode::Busy`]. Pauses grow exponentially from
+/// [`backoff`](Self::backoff)'s base to its cap, each drawn uniformly below its bound ("full
+/// jitter"), so competing transactions spread out instead of colliding again. Retrying stops
+/// at [`max_attempts`](Self::max_attempts) or past [`deadline`](Self::deadline), whichever
+/// comes first, returning the last error.
+///
+/// The defaults: no attempt cap, a 30 s deadline (the default write-stall timeout), pauses
+/// from 5 µs up to 100 ms, `Busy` not retried, the writer's default durability. The 5 µs base
+/// is measured (#708): a pause of a few microseconds already spreads competing
+/// transactions out, and a larger base mostly lengthens the tail of those that keep losing.
+/// [`Pigeonhole::transact`] yields the core for a pause below 100 µs instead of sleeping,
+/// since a sleep that short overshoots by the OS timer slack (#932); longer pauses sleep.
+///
+/// A plain value: numbers, durations and flags, no closure or trait object.
+/// [`Pigeonhole::transact`] is a Rust-only convenience (a closure and a generic error) over
+/// it; everything it decides is reachable without it, so an async caller with its own timer
+/// (or a future C ABI) drives the same loop with [`Pigeonhole::transaction`] and
+/// [`next_pause`](Self::next_pause) (or [`retries_code`](Self::retries_code) and
+/// [`delay`](Self::delay)).
+///
+/// ```
+/// use std::time::Duration;
+/// use pigeonhole::RetryPolicy;
+///
+/// let policy = RetryPolicy::default()
+///     .max_attempts(10)
+///     .deadline(Duration::from_secs(2))
+///     .backoff(Duration::from_micros(50), Duration::from_millis(20));
+/// assert!(policy.delay(1) <= Duration::from_micros(50));
+/// assert!(policy.delay(30) <= Duration::from_millis(20));
+/// ```
+#[derive(Debug, Clone)]
+pub struct RetryPolicy {
+    max_attempts: Option<u32>,
+    deadline: Option<Duration>,
+    base: Duration,
+    cap: Duration,
+    retry_busy: bool,
+    durability: Option<Durability>,
+}
+
+impl Default for RetryPolicy {
+    fn default() -> Self {
+        Self {
+            max_attempts: None,
+            deadline: Some(Duration::from_secs(30)),
+            base: Duration::from_micros(5),
+            cap: Duration::from_millis(100),
+            retry_busy: false,
+            durability: None,
+        }
+    }
+}
+
+impl RetryPolicy {
+    /// At most `n` attempts in all (at least 1).
+    pub fn max_attempts(mut self, n: u32) -> Self {
+        self.max_attempts = Some(n.max(1));
+        self
+    }
+
+    /// No attempt cap (the default): only the deadline stops retrying.
+    pub fn unlimited_attempts(mut self) -> Self {
+        self.max_attempts = None;
+        self
+    }
+
+    /// No new attempt starts once `d` has passed since the first began (default 30 s). An
+    /// attempt already running finishes, so the whole call can take longer: a commit
+    /// waiting for room returns `Busy` only after `Options::write_stall_timeout` (also 30 s
+    /// by default).
+    pub fn deadline(mut self, d: Duration) -> Self {
+        self.deadline = Some(d);
+        self
+    }
+
+    /// No deadline: only the attempt cap stops retrying. With neither, a transaction that
+    /// keeps conflicting is retried for ever.
+    pub fn no_deadline(mut self) -> Self {
+        self.deadline = None;
+        self
+    }
+
+    /// The pause before the second attempt is drawn below `base`, and the bound doubles per
+    /// attempt up to `cap` (defaults 5 µs and 100 ms).
+    pub fn backoff(mut self, base: Duration, cap: Duration) -> Self {
+        self.base = base;
+        self.cap = cap.max(base);
+        self
+    }
+
+    /// Also retry an attempt that fails with [`ErrorCode::Busy`] (default off): the
+    /// database could not make room within `Options::write_stall_timeout`.
+    pub fn retry_busy(mut self, yes: bool) -> Self {
+        self.retry_busy = yes;
+        self
+    }
+
+    /// Commit each attempt with `durability` (default: the writer's default durability).
+    pub fn durability(mut self, durability: Durability) -> Self {
+        self.durability = Some(durability);
+        self
+    }
+
+    /// Whether an attempt that failed with `error` is retried.
+    pub fn retries(&self, error: &Error) -> bool {
+        self.retries_code(error.code())
+    }
+
+    /// [`retries`](Self::retries) by error code alone: `Conflict` and `SnapshotExpired`
+    /// always, `Busy` with [`retry_busy`](Self::retry_busy).
+    pub fn retries_code(&self, code: ErrorCode) -> bool {
+        match code {
+            ErrorCode::Conflict | ErrorCode::SnapshotExpired => true,
+            ErrorCode::Busy => self.retry_busy,
+            _ => false,
+        }
+    }
+
+    /// The whole retry decision after attempt `attempt` (counting from 1) failed with
+    /// `code`, `elapsed` after the first attempt began: `None` to give up (the code is not
+    /// retried, the attempt cap is reached, or the deadline passed), else the pause before
+    /// the next attempt, cut short at the deadline. With it and
+    /// [`Pigeonhole::transaction`] a caller drives exactly [`Pigeonhole::transact`]'s loop
+    /// without its closure: an async caller with its own timer, or a C ABI.
+    pub fn next_pause(&self, code: ErrorCode, attempt: u32, elapsed: Duration) -> Option<Duration> {
+        let more = self.max_attempts.is_none_or(|n| attempt < n)
+            && self.deadline.is_none_or(|d| elapsed < d);
+        if !more || !self.retries_code(code) {
+            return None;
+        }
+        let pause = self.delay(attempt + 1);
+        Some(match self.deadline {
+            Some(d) => pause.min(d.saturating_sub(elapsed)),
+            None => pause,
+        })
+    }
+
+    /// The pause before attempt `attempt` (counting from 1; none before the first): drawn
+    /// uniformly below `min(base × 2^(attempt−2), cap)`.
+    pub fn delay(&self, attempt: u32) -> Duration {
+        if attempt <= 1 {
+            return Duration::ZERO;
+        }
+        let shift = (attempt - 2).min(32);
+        let bound = self
+            .base
+            .checked_mul(1u32 << shift.min(31))
+            .unwrap_or(self.cap)
+            .min(self.cap);
+        let nanos = bound.as_nanos() as u64;
+        if nanos == 0 {
+            return Duration::ZERO;
+        }
+        Duration::from_nanos(jitter() % nanos)
+    }
+}
+
+/// A cheap per-thread random number for the jitter: no dependency, no lock.
+fn jitter() -> u64 {
+    use std::cell::Cell;
+    thread_local! {
+        static STATE: Cell<u64> = Cell::new({
+            let t = std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map_or(0, |d| d.as_nanos() as u64);
+            let here = &t as *const u64 as u64;
+            (t ^ here.rotate_left(32)) | 1
+        });
+    }
+    STATE.with(|s| {
+        // xorshift64*
+        let mut x = s.get();
+        x ^= x >> 12;
+        x ^= x << 25;
+        x ^= x >> 27;
+        s.set(x);
+        x.wrapping_mul(0x2545_F491_4F6C_DD1D)
+    })
+}
+
+impl Pigeonhole {
+    /// Runs `body` in a transaction and commits it, retrying as `policy` says (ICR 0060):
+    /// the usual way to use [`Transaction`]. Each attempt starts a fresh transaction, so
+    /// `body` reads current data; it may run several times, so it should do nothing outside
+    /// the transaction that must not be repeated. Returns what `body` returned and the
+    /// commit.
+    ///
+    /// `body` returns any error type that a [`pigeonhole::Error`](Error) converts into, so
+    /// it can give up with the application's own error (nothing is committed then). If any
+    /// of the transaction's reads failed with an error the policy retries (a recovery
+    /// expiring its snapshot), the attempt is retried whatever `body` returned, even if it
+    /// swallowed that error and gave up for another reason: the snapshot is gone either way.
+    /// [`Transaction::get`] and [`Transaction::get_row`] reads count; a failed
+    /// [`get_async`](Transaction::get_async) does not. A commit that fails with a retried
+    /// error (a `Conflict`, or `SnapshotExpired` when a recovery refused it) is retried;
+    /// anything else is returned as is.
+    ///
+    /// ```
+    /// use pigeonhole::{Family, Options, Pigeonhole, RetryPolicy};
+    ///
+    /// # fn main() -> pigeonhole::Result<()> {
+    /// # let dir = pigeonhole::doc_support::temp_dir();
+    /// let db = Pigeonhole::open(dir.join("app.phdb"), Options::default().shards(2))?;
+    /// let bank = db.table("bank")?.family("acct", Family::default()).create_if_missing()?;
+    /// bank.mutate(b"alice").put("acct", b"balance", b"10").commit()?;
+    /// bank.mutate(b"bob").put("acct", b"balance", b"0").commit()?;
+    ///
+    /// // Move 5 from alice to bob, retrying on conflicts with other transfers.
+    /// let balance = |txn: &mut pigeonhole::Transaction, who: &[u8]| -> pigeonhole::Result<u64> {
+    ///     let cell = txn.get(&bank, who, "acct", b"balance")?;
+    ///     Ok(cell.map_or(0, |c| std::str::from_utf8(c.value()).unwrap().parse().unwrap()))
+    /// };
+    /// let (moved, _commit) = db.transact(&RetryPolicy::default(), |txn| {
+    ///     let (a, b) = (balance(txn, b"alice")?, balance(txn, b"bob")?);
+    ///     let amount = a.min(5);
+    ///     txn.put(&bank, b"alice", "acct", b"balance", (a - amount).to_string().as_bytes())
+    ///         .put(&bank, b"bob", "acct", b"balance", (b + amount).to_string().as_bytes());
+    ///     Ok::<_, pigeonhole::Error>(amount)
+    /// })?;
+    /// assert_eq!(moved, 5);
+    /// # db.close()?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn transact<T, E>(
+        &self,
+        policy: &RetryPolicy,
+        mut body: impl FnMut(&mut Transaction) -> std::result::Result<T, E>,
+    ) -> std::result::Result<(T, CommitInfo), E>
+    where
+        E: From<Error>,
+    {
+        let started = Instant::now();
+        let mut attempt = 1u32;
+        loop {
+            // `retryable`: a pigeonhole error the policy may retry; `given_up`: the
+            // application's own error, returned as is.
+            let mut given_up = None;
+            let retryable = match self.transaction() {
+                Err(e) => Some(e),
+                Ok(mut txn) => match body(&mut txn) {
+                    Err(app) => match txn.failed_read() {
+                        Some(e) if policy.retries(&e) => Some(e),
+                        _ => {
+                            given_up = Some(app);
+                            None
+                        }
+                    },
+                    Ok(value) => {
+                        let commit = match policy.durability {
+                            Some(d) => txn.commit_with(d),
+                            None => txn.commit(),
+                        };
+                        match commit {
+                            Ok(info) => return Ok((value, info)),
+                            Err(e) => Some(e),
+                        }
+                    }
+                },
+            };
+            if let Some(app) = given_up {
+                return Err(app);
+            }
+            let error = retryable.expect("an error when nothing was given up");
+            let Some(pause) = policy.next_pause(error.code(), attempt, started.elapsed()) else {
+                return Err(E::from(error));
+            };
+            attempt += 1;
+            self.db.txn_counts.retries.fetch_add(1, Ordering::Relaxed);
+            wait(pause);
+        }
+    }
+}
+
+/// Pauses below this are yield-spun rather than slept (ICR 0060's 2026-10-26 amendment):
+/// Linux stretches every `nanosleep` by the thread's timer slack (50 µs by default), which
+/// more than doubled the short pauses a contended transfer takes (#932). A library
+/// shouldn't change its caller's timer slack, so it doesn't sleep below it.
+const SPIN_BELOW: Duration = Duration::from_micros(100);
+
+/// [`Pigeonhole::transact`]'s pause: yield the core until `pause` has passed if it's short,
+/// else sleep.
+fn wait(pause: Duration) {
+    if pause.is_zero() {
+        return;
+    }
+    if pause >= SPIN_BELOW {
+        std::thread::sleep(pause);
+        return;
+    }
+    let until = Instant::now() + pause;
+    while Instant::now() < until {
+        std::thread::yield_now();
+    }
+}
+
+/// Transaction outcomes since open (ICR 0061), across automatic recoveries.
+#[derive(Debug, Default)]
+pub(crate) struct TxnCounts {
+    pub(crate) commits: AtomicU64,
+    pub(crate) conflicts: AtomicU64,
+    pub(crate) retries: AtomicU64,
+}
+
+impl TxnCounts {
+    /// Counts one transaction commit's outcome.
+    pub(crate) fn count(&self, result: &Result<CommitInfo>) {
+        match result {
+            Ok(_) => self.commits.fetch_add(1, Ordering::Relaxed),
+            Err(e) if e.code() == ErrorCode::Conflict => {
+                self.conflicts.fetch_add(1, Ordering::Relaxed)
+            }
+            Err(_) => return,
+        };
+    }
+
+    /// Fills the transaction fields of `m`.
+    pub(crate) fn fill(&self, m: &mut crate::EngineMetrics) {
+        m.transactions = self.commits.load(Ordering::Relaxed);
+        m.transaction_conflicts = self.conflicts.load(Ordering::Relaxed);
+        m.transaction_retries = self.retries.load(Ordering::Relaxed);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn wait_lasts_at_least_the_pause_spun_or_slept() {
+        for pause in [
+            Duration::from_micros(20),
+            SPIN_BELOW,
+            Duration::from_micros(300),
+        ] {
+            let started = Instant::now();
+            wait(pause);
+            assert!(started.elapsed() >= pause, "{pause:?}");
+        }
+        let started = Instant::now();
+        wait(Duration::ZERO);
+        assert!(started.elapsed() < Duration::from_millis(50));
+    }
+}

data/vendor/pigeonhole/src/set.rs

@@ -0,0 +1,103 @@
+//! A set family's cell value, read in place ([`SetRef`], D298).
+
+use pigeonhole_format::roaring;
+
+/// A set of `u32`s, borrowed from a cell of a set family
+/// ([`Aggregation::Set`](crate::Aggregation::Set)) without decoding it: membership is a
+/// search, the size comes from its containers' counts, and intersections and unions of two
+/// cells go container by container. The bytes are a standard 32-bit roaring bitmap
+/// ([`as_bytes`](Self::as_bytes)), which CRoaring and roaring-rs read as they are.
+///
+/// ```
+/// use pigeonhole::{Aggregation, Family, Options, Pigeonhole};
+///
+/// # fn main() -> pigeonhole::Result<()> {
+/// # let dir = pigeonhole::doc_support::temp_dir();
+/// let db = Pigeonhole::open(dir.join("app.phdb"), Options::default().shards(1))?;
+/// let t = db
+///     .table("graph")?
+///     .family("out", Family::aggregate(Aggregation::Set))
+///     .create_if_missing()?;
+/// t.mutate(b"a").set_add("out", b"", 1).set_add("out", b"", 7).commit()?;
+/// t.mutate(b"b").set_add("out", b"", 7).set_add("out", b"", 9).commit()?;
+/// t.mutate(b"a").set_remove("out", b"", 1).commit()?;
+/// let (a, b) = (t.get(b"a", "out", b"")?.unwrap(), t.get(b"b", "out", b"")?.unwrap());
+/// let (a, b) = (a.as_set().unwrap(), b.as_set().unwrap());
+/// assert_eq!(a.iter().collect::<Vec<_>>(), [7]);
+/// assert_eq!(a.intersection_len(&b), 1);
+/// assert_eq!(a.union_len(&b), 2);
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct SetRef<'a>(roaring::SetRef<'a>);
+
+impl<'a> SetRef<'a> {
+    /// The set in `bytes`, a canonical roaring bitmap without run containers (as a set
+    /// family stores one); `None` if they are not one.
+    pub fn from_bytes(bytes: &'a [u8]) -> Option<Self> {
+        roaring::SetRef::parse(bytes).ok().map(Self)
+    }
+
+    /// The set's bytes: a standard roaring bitmap.
+    pub fn as_bytes(&self) -> &'a [u8] {
+        self.0.as_bytes()
+    }
+
+    /// The number of elements.
+    pub fn len(&self) -> u64 {
+        self.0.len()
+    }
+
+    /// Whether the set is empty.
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+
+    /// Whether `x` is in the set.
+    pub fn contains(&self, x: u32) -> bool {
+        self.0.contains(x)
+    }
+
+    /// The elements, ascending.
+    pub fn iter(&self) -> SetIter<'a> {
+        SetIter(self.0.iter())
+    }
+
+    /// The elements of both sets, ascending.
+    pub fn intersection<'b>(&self, other: &SetRef<'b>) -> SetIntersection<'a, 'b> {
+        SetIntersection(self.0.intersection(&other.0))
+    }
+
+    /// The size of the intersection of the two sets, without building it.
+    pub fn intersection_len(&self, other: &SetRef<'_>) -> u64 {
+        self.0.intersection_len(&other.0)
+    }
+
+    /// The size of the union of the two sets, without building it.
+    pub fn union_len(&self, other: &SetRef<'_>) -> u64 {
+        self.0.union_len(&other.0)
+    }
+}
+
+/// A set's elements, ascending ([`SetRef::iter`]).
+pub struct SetIter<'a>(roaring::Iter<'a>);
+
+impl Iterator for SetIter<'_> {
+    type Item = u32;
+
+    fn next(&mut self) -> Option<u32> {
+        self.0.next()
+    }
+}
+
+/// The elements of two sets, ascending ([`SetRef::intersection`]).
+pub struct SetIntersection<'a, 'b>(roaring::Intersection<'a, 'b>);
+
+impl Iterator for SetIntersection<'_, '_> {
+    type Item = u32;
+
+    fn next(&mut self) -> Option<u32> {
+        self.0.next()
+    }
+}