pigeonhole-db 1.1.0

data/src/error.rs

@@ -0,0 +1,151 @@
+//! Errors: `Pigeonhole::Error < StandardError`, and one subclass per [`ErrorCode`] named as
+//! the code, each instance carrying `code` (the name) and `code_num` (ICR 0111).
+
+use magnus::{Error, ExceptionClass, RModule, Ruby, Value, prelude::*};
+use pigeonhole::ErrorCode;
+
+/// Declares the codes: the module registration and the code → class-name mapping.
+macro_rules! codes {
+    ($($code:ident),* $(,)?) => {
+        /// The class name for `code`, or `None` for a code this build doesn't know.
+        fn name(code: ErrorCode) -> Option<&'static str> {
+            match code {
+                $(ErrorCode::$code => Some(stringify!($code)),)*
+                _ => None,
+            }
+        }
+
+        /// Defines `Pigeonhole::Error`, every code's subclass, `SpentError` and
+        /// `ReturnedValueError` under `m`,
+        /// and `Pigeonhole::Native::ERROR_CODES` (each code's name and number) under `native`,
+        /// which a test checks against `ErrorCode` itself (ai1249's P5 on #1399).
+        pub(crate) fn register(ruby: &Ruby, m: RModule, native: RModule) -> Result<(), Error> {
+            let base = m.define_error("Error", ruby.exception_standard_error())?;
+            $(m.define_error(stringify!($code), base)?;)*
+            m.define_error("SpentError", base)?;
+            m.define_error("ReturnedValueError", base)?;
+            let codes = ruby.hash_new();
+            $(codes.aset(stringify!($code), ErrorCode::$code as u32)?;)*
+            codes.freeze();
+            native.const_set("ERROR_CODES", codes)?;
+            Ok(())
+        }
+    };
+}
+
+codes!(
+    Io,
+    Corruption,
+    WriterLocked,
+    ShmVersionMismatch,
+    ShmUnavailable,
+    UnsupportedFormat,
+    NetworkFilesystem,
+    TableNotFound,
+    TableExists,
+    FamilyNotFound,
+    FamilyExists,
+    UnknownMergeOperator,
+    MergeFailed,
+    Conflict,
+    ReadOnly,
+    KeyTooLarge,
+    ValueTooLarge,
+    NoSpace,
+    InvalidArgument,
+    Unsupported,
+    Closed,
+    NoReaderSlot,
+    RecordTooLarge,
+    Busy,
+    SnapshotExpired,
+    WouldDeadlock,
+    BatchTooLarge,
+    OutcomeUnknown,
+    NoWriter,
+    UnsupportedFeature,
+    FeedExpired,
+);
+
+/// `code`'s exception with `message`, its `@code` and `@code_num` set.
+pub(crate) fn with_code(ruby: &Ruby, code: ErrorCode, message: &str) -> Error {
+    let make = || -> Result<Error, Error> {
+        let m: RModule = ruby.class_object().const_get("Pigeonhole")?;
+        let class: ExceptionClass = m.const_get(name(code).unwrap_or("Error"))?;
+        // `Pigeonhole::Error#initialize(message, code, code_num)` (lib/pigeonhole.rb).
+        let e = class.new_instance((message, format!("{code:?}"), code as u32))?;
+        Ok(Error::from(e))
+    };
+    make().unwrap_or_else(|e| e)
+}
+
+/// A library error as its Ruby exception.
+pub(crate) fn to_rb(ruby: &Ruby, e: &pigeonhole::Error) -> Error {
+    with_code(ruby, e.code(), e.message())
+}
+
+/// `Result` with library errors converted.
+pub(crate) trait OrRb<T> {
+    /// The library error, if any, as its Ruby exception.
+    fn or_rb(self, ruby: &Ruby) -> Result<T, Error>;
+}
+
+impl<T> OrRb<T> for pigeonhole::Result<T> {
+    fn or_rb(self, ruby: &Ruby) -> Result<T, Error> {
+        self.map_err(|e| to_rb(ruby, &e))
+    }
+}
+
+/// Runs the engine call `f` with the GVL released ([`crate::gvl::without_gvl`]), its
+/// library error raised as the Ruby exception.
+pub(crate) fn engine<F, R>(ruby: &Ruby, f: F) -> Result<R, Error>
+where
+    F: FnOnce() -> pigeonhole::Result<R> + Send,
+    R: Send,
+{
+    crate::gvl::without_gvl(ruby, f)?.or_rb(ruby)
+}
+
+/// `Pigeonhole::SpentError` (an `Error` with no code): a write handle used after it was
+/// committed, discarded or rolled back (simp724's R4 on #697; named, ai1249's P4 on #1399).
+pub(crate) fn spent(ruby: &Ruby, message: &str) -> Error {
+    uncoded(ruby, "SpentError", message)
+}
+
+/// A read that failed after commit `seqno` applied, as `Pigeonhole::ReturnedValueError`
+/// (its `seqno`, and the read's error as its `code`, `code_num` and `cause`): a caller can
+/// tell it from a failed commit, which a retry is safe after (perf2's S1 on #1473).
+pub(crate) fn returned_value(ruby: &Ruby, seqno: u64, e: &pigeonhole::Error) -> Error {
+    let cause = to_rb(ruby, e);
+    let make = || -> Result<Error, Error> {
+        let m: RModule = ruby.class_object().const_get("Pigeonhole")?;
+        let class: ExceptionClass = m.const_get("ReturnedValueError")?;
+        let code = e.code();
+        let message = format!(
+            "the commit (seqno {seqno}) succeeded, but reading the value after it failed: {}",
+            e.message()
+        );
+        // `ReturnedValueError#initialize(message, code, code_num, seqno)` (lib/pigeonhole.rb).
+        let exc = class.new_instance((message, format!("{code:?}"), code as u32, seqno))?;
+        // Raised through `Kernel.raise` so the read's exception is its `cause`.
+        let raised = match cause.value() {
+            Some(c) => ruby
+                .module_kernel()
+                .funcall::<_, _, Value>("raise", (exc, magnus::kwargs!("cause" => c)))
+                .err(),
+            None => None,
+        };
+        Ok(raised.unwrap_or_else(|| Error::from(exc)))
+    };
+    make().unwrap_or_else(|e| e)
+}
+
+/// `Pigeonhole::<class>` with `message` and no code: the binding's own errors.
+pub(crate) fn uncoded(ruby: &Ruby, class: &str, message: &str) -> Error {
+    let make = || -> Result<Error, Error> {
+        let m: RModule = ruby.class_object().const_get("Pigeonhole")?;
+        let class: ExceptionClass = m.const_get(class)?;
+        Ok(Error::from(class.new_instance((message,))?))
+    };
+    make().unwrap_or_else(|e| e)
+}

data/src/feed.rs

@@ -0,0 +1,316 @@
+//! The change feed (D310, #1322): `Table#feed`, and `Feed`'s waits.
+//!
+//! A commit comes back as `[seqno, timestamp, [[table, family, kind, row, qualifier,
+//! timestamp, value], ...]]`, which `lib/pigeonhole/api.rb` turns into frozen `Commit` and
+//! `Change` objects.
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Mutex, MutexGuard};
+use std::time::{Duration, Instant};
+
+use magnus::{Error, RArray, RString, Ruby, TryConvert, prelude::*};
+use pigeonhole::{ChangeKind, ErrorCode};
+
+use crate::classes::{Feed, Snapshot, Table};
+use crate::convert::{Bytes, Secs, arg_error, binary, frozen, lock};
+use crate::error::{engine, with_code};
+use crate::fork::ForkSafe;
+use crate::gvl::without_gvl;
+use crate::read::{snapshot_arg, typed};
+use crate::table::{Handle, either};
+
+/// The longest a wait runs with the GVL released before it checks for an interrupt
+/// (`Thread#raise`, `Thread#kill`, Ctrl-C), so a consumer blocked in `next` stays
+/// interruptible although one engine call isn't.
+const SLICE: Duration = Duration::from_millis(100);
+
+/// A feed's state: the subscription (`None` once closed) behind a mutex, and how many
+/// threads are waiting to take it.
+///
+/// A consumer in `next` holds the mutex for each slice and takes it again right after, and
+/// `std`'s mutex isn't fair, so without `wanted` it kept winning: `token` and `close` from
+/// another thread waited many slices (perf2 measured 1.46 s), with the GVL released and no
+/// way to interrupt them (perf2's S1 on #1411). Every lock goes through
+/// [`acquire`](Self::acquire), which counts the thread in `wanted` while it waits, and
+/// `next` gives way between slices while `wanted` isn't 0, so any other caller, a second
+/// consumer included, waits at most about one slice.
+pub(crate) struct FeedState {
+    feed: Mutex<Option<pigeonhole::Feed>>,
+    wanted: AtomicUsize,
+}
+
+impl FeedState {
+    fn new(feed: pigeonhole::Feed) -> Self {
+        Self {
+            feed: Mutex::new(Some(feed)),
+            wanted: AtomicUsize::new(0),
+        }
+    }
+
+    /// The subscription, counted in `wanted` until the lock is ours.
+    fn acquire(&self) -> MutexGuard<'_, Option<pigeonhole::Feed>> {
+        self.wanted.fetch_add(1, Ordering::SeqCst);
+        let guard = lock(&self.feed);
+        self.wanted.fetch_sub(1, Ordering::SeqCst);
+        guard
+    }
+
+    /// Waits, with the GVL released, until no other thread wants the lock or `limit` (at
+    /// most a slice) has passed: a consumer between slices lets the others in first.
+    fn give_way(&self, ruby: &Ruby, limit: Duration) -> Result<(), Error> {
+        if self.wanted.load(Ordering::SeqCst) == 0 {
+            return Ok(());
+        }
+        without_gvl(ruby, || {
+            let start = Instant::now();
+            while self.wanted.load(Ordering::SeqCst) > 0 && start.elapsed() < limit {
+                std::thread::sleep(Duration::from_millis(1));
+            }
+        })
+    }
+}
+
+impl Table {
+    /// `feed(tables, prefix, visible, from_snapshot, from_oldest, resume)`: subscribes to
+    /// this table's committed changes (and `tables`'). A reader process's table feeds from
+    /// the running writer's history (D310 PR 4, #1361).
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn feed(
+        ruby: &Ruby,
+        rb_self: &Self,
+        tables: Option<RArray>,
+        prefix: Option<Bytes>,
+        visible: bool,
+        from_snapshot: Option<&Snapshot>,
+        from_oldest: bool,
+        resume: Option<Bytes>,
+    ) -> Result<Feed, Error> {
+        let starts = usize::from(from_snapshot.is_some())
+            + usize::from(from_oldest)
+            + usize::from(resume.is_some());
+        if starts > 1 {
+            return Err(arg_error(
+                ruby,
+                "one of from_snapshot:, from_oldest: and resume:, not several",
+            ));
+        }
+        let mut others = Vec::new();
+        for v in tables.into_iter().flatten() {
+            others.push(<&Table>::try_convert(v)?.handle(ruby)?.clone());
+        }
+        let snap = snapshot_arg(ruby, from_snapshot)?;
+        let h = rb_self.handle(ruby)?.clone();
+        let feed = engine(ruby, move || {
+            let mut b = either!(&h, |t| t.feed());
+            for other in &others {
+                b = match other {
+                    Handle::Writer(t) => b.table(t),
+                    Handle::Reader(t) => b.read_table(t),
+                };
+            }
+            if let Some(p) = &prefix {
+                b = b.prefix(&p.0);
+            }
+            if visible {
+                b = b.visible();
+            }
+            if let Some(s) = &snap {
+                b = b.from_snapshot(s);
+            }
+            if from_oldest {
+                b = b.from_oldest();
+            }
+            if let Some(r) = resume {
+                b = b.resume(&pigeonhole::FeedToken::from_bytes(r.0));
+            }
+            b.open()
+        })?;
+        Ok(Feed(ForkSafe::new(FeedState::new(feed))))
+    }
+}
+
+/// A change's kind as a Symbol's name.
+fn kind_name(kind: ChangeKind) -> &'static str {
+    match kind {
+        ChangeKind::Put => "put",
+        ChangeKind::Merge => "merge",
+        ChangeKind::DeleteCell => "delete_cell",
+        ChangeKind::DeleteColumn => "delete_column",
+        ChangeKind::DeleteFamily => "delete_family",
+        // A kind this build doesn't name.
+        _ => "unknown",
+    }
+}
+
+/// A commit as `[seqno, timestamp, changes]`. Every String and Array inside a change is
+/// frozen, as its `Data` is (ai1249's P1 on #1411): mutating one would change the change's
+/// `==` and `hash`.
+fn commit(ruby: &Ruby, c: &pigeonhole::Commit) -> Result<RArray, Error> {
+    let name = |s: &str| {
+        let s = ruby.str_new(s);
+        s.freeze();
+        s
+    };
+    let changes = ruby.ary_new_capa(c.changes().len());
+    for ch in c.changes() {
+        let a = ruby.ary_new_capa(7);
+        a.push(name(ch.table()))?;
+        a.push(name(ch.family()))?;
+        a.push(ruby.to_symbol(kind_name(ch.kind())))?;
+        a.push(frozen(ruby, ch.row()))?;
+        a.push(frozen(ruby, ch.qualifier()))?;
+        a.push(ch.timestamp())?;
+        let value = ch
+            .value()
+            .map_or_else(|| ruby.qnil().as_value(), |v| typed(ruby, v));
+        value.freeze();
+        a.push(value)?;
+        changes.push(a)?;
+    }
+    let out = ruby.ary_new_capa(3);
+    out.push(c.seqno())?;
+    out.push(c.timestamp())?;
+    out.push(changes)?;
+    Ok(out)
+}
+
+impl Feed {
+    /// One wait of at most `slice` (`None`: no wait), with the GVL released. `Closed` for a
+    /// closed feed.
+    fn poll(
+        ruby: &Ruby,
+        rb_self: &Self,
+        slice: Option<Duration>,
+    ) -> Result<Option<pigeonhole::Commit>, Error> {
+        let state = rb_self.0.get(ruby)?;
+        // The mutex is taken only inside the call, so a thread waiting on it (behind a
+        // consumer's slice) never holds the GVL.
+        let polled = engine(ruby, || {
+            let mut guard = state.acquire();
+            let Some(f) = guard.as_mut() else {
+                return Ok(None);
+            };
+            let next = match slice {
+                Some(d) => f.next(d)?,
+                None => f.try_next()?,
+            };
+            Ok(Some(next.cloned()))
+        })?;
+        polled.ok_or_else(|| with_code(ruby, ErrorCode::Closed, "the feed is closed"))
+    }
+
+    /// `native_next(timeout)`: the next commit, waiting up to `timeout` seconds (`nil`
+    /// waits until one comes), in slices with an interrupt check between them; `nil` if
+    /// none came in time.
+    pub(crate) fn next(
+        ruby: &Ruby,
+        rb_self: &Self,
+        timeout: Option<Secs>,
+    ) -> Result<Option<RArray>, Error> {
+        let deadline = timeout.and_then(|t| Instant::now().checked_add(t.0));
+        let state = rb_self.0.get(ruby)?;
+        loop {
+            // Another thread waiting for the feed (`token`, `close`, a second consumer) goes
+            // first; then this one checks for interrupts before its next slice.
+            // Never past a short `timeout:`'s deadline (ai1249's nit on #1411).
+            let left = || {
+                deadline.map_or(SLICE, |d| {
+                    d.saturating_duration_since(Instant::now()).min(SLICE)
+                })
+            };
+            state.give_way(ruby, left())?;
+            ruby.thread_check_ints()?;
+            let slice = left();
+            if let Some(c) = Self::poll(ruby, rb_self, Some(slice))? {
+                return commit(ruby, &c).map(Some);
+            }
+            if deadline.is_some_and(|d| Instant::now() >= d) {
+                return Ok(None);
+            }
+        }
+    }
+
+    /// `native_try_next`: the next commit if one is ready, else `nil`. Never waits.
+    pub(crate) fn try_next(ruby: &Ruby, rb_self: &Self) -> Result<Option<RArray>, Error> {
+        Self::poll(ruby, rb_self, None)?
+            .map(|c| commit(ruby, &c))
+            .transpose()
+    }
+
+    /// Where the feed is, as bytes: `Table#feed(resume:)` continues after the last commit
+    /// delivered, in this open of the database or a later one.
+    pub(crate) fn token(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
+        let state = rb_self.0.get(ruby)?;
+        // A thread waiting in `next` holds the lock for up to a slice, then gives way.
+        let token = without_gvl(ruby, || {
+            state.acquire().as_ref().map(pigeonhole::Feed::token)
+        })?
+        .ok_or_else(|| with_code(ruby, ErrorCode::Closed, "the feed is closed"))?;
+        Ok(binary(ruby, token.as_bytes()))
+    }
+
+    /// Once the feed expired: the oldest commit seqno its history still holds, when known.
+    pub(crate) fn oldest_retained(ruby: &Ruby, rb_self: &Self) -> Result<Option<u64>, Error> {
+        let state = rb_self.0.get(ruby)?;
+        without_gvl(ruby, || {
+            state
+                .acquire()
+                .as_ref()
+                .and_then(pigeonhole::Feed::oldest_retained)
+        })
+    }
+
+    /// Ends the subscription now. Calls afterwards raise `Closed`; closing twice does
+    /// nothing.
+    pub(crate) fn close(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        let state = rb_self.0.get(ruby)?;
+        without_gvl(ruby, || drop(state.acquire().take()))
+    }
+
+    /// Whether `close` was called.
+    pub(crate) fn is_closed(ruby: &Ruby, rb_self: &Self) -> Result<bool, Error> {
+        let state = rb_self.0.get(ruby)?;
+        without_gvl(ruby, || state.acquire().is_none())
+    }
+}
+
+/// The feed options of `Pigeonhole.open`: `change_feed` (the history's size in bytes),
+/// `change_feed_off`, `feed_age` and `feed_tables`.
+pub(crate) fn options(
+    ruby: &Ruby,
+    mut o: pigeonhole::Options,
+    change_feed: Option<u64>,
+    change_feed_off: bool,
+    feed_age: Option<Secs>,
+    feed_tables: Option<RArray>,
+) -> Result<pigeonhole::Options, Error> {
+    if change_feed_off {
+        if change_feed.is_some() || feed_age.is_some() {
+            return Err(arg_error(
+                ruby,
+                "change_feed_off: can't take change_feed: or feed_age:",
+            ));
+        }
+        o = o.change_feed_off();
+    }
+    match (change_feed, feed_age) {
+        (Some(n), age) => {
+            let mut r = pigeonhole::FeedRetention::bytes(n);
+            if let Some(a) = age {
+                r = r.age(a.0);
+            }
+            o = o.change_feed(r);
+        }
+        (None, Some(_)) => {
+            return Err(arg_error(
+                ruby,
+                "feed_age: needs change_feed: (the history's size in bytes)",
+            ));
+        }
+        (None, None) => {}
+    }
+    if let Some(t) = crate::convert::names(feed_tables)? {
+        o = o.feed_tables(t);
+    }
+    Ok(o)
+}

data/src/fork.rs

@@ -0,0 +1,64 @@
+//! Handles and `fork` (simp724's R1 on #697): pre-fork servers (Puma, Unicorn, Pitchfork
+//! with `preload_app`) fork after the app has opened its database.
+//!
+//! Every Ruby object that holds an engine handle keeps it in a [`ForkSafe`], which records
+//! the process that created it. In any other process (a forked child):
+//! - using it raises `Pigeonhole::Unsupported`, before the engine is reached (the engine
+//!   refuses too, ICR 0067, but some of its accessors are inert rather than failing);
+//! - dropping it (Ruby's GC, or the process exiting) **forgets** the handle instead of
+//!   dropping it: no close, flush or lock release runs on the parent's database. A `flock`
+//!   belongs to the open file description, which the child shares with the parent.
+
+use magnus::{Error, Ruby};
+use pigeonhole::ErrorCode;
+
+use crate::error::with_code;
+
+/// A value owned by the process that created it.
+pub(crate) struct ForkSafe<T> {
+    /// The creating process.
+    pid: u32,
+    /// The value; `None` only while dropping.
+    val: Option<T>,
+}
+
+impl<T> ForkSafe<T> {
+    /// Wraps `val`, owned by this process.
+    pub(crate) fn new(val: T) -> Self {
+        Self {
+            pid: std::process::id(),
+            val: Some(val),
+        }
+    }
+
+    /// Whether this is a process other than the one that created the value.
+    pub(crate) fn forked(&self) -> bool {
+        std::process::id() != self.pid
+    }
+
+    /// The value, or `Unsupported` in a forked child.
+    pub(crate) fn get(&self, ruby: &Ruby) -> Result<&T, Error> {
+        if self.forked() {
+            return Err(forked_error(ruby));
+        }
+        Ok(self.val.as_ref().expect("present until dropped"))
+    }
+}
+
+impl<T> Drop for ForkSafe<T> {
+    fn drop(&mut self) {
+        if self.forked() {
+            // The parent's handle: leave it alone (no close, no unlock, no thread join).
+            std::mem::forget(self.val.take());
+        }
+    }
+}
+
+/// The error a handle raises in a forked child.
+pub(crate) fn forked_error(ruby: &Ruby) -> Error {
+    with_code(
+        ruby,
+        ErrorCode::Unsupported,
+        "this database was opened in another process (fork); open it again here",
+    )
+}

data/src/gvl.rs

@@ -0,0 +1,112 @@
+//! Releasing the GVL around engine calls: the crate's one hand-written `unsafe` (ICR 0111,
+//! the owner's O3 exception to #696's macro-sites-only policy).
+//!
+//! magnus 0.9 doesn't wrap `rb_thread_call_without_gvl2`, so this module calls it through
+//! `rb-sys`. Everything else goes through [`without_gvl`], whose bounds are the soundness
+//! argument:
+//!
+//! - **`F: Send`, `R: Send`.** Every Ruby handle in magnus (`Value`, `RString`, the wrapped
+//!   classes' references, `Ruby` itself) is `!Send`, so the closure can capture no Ruby
+//!   object and return none: code that runs without the GVL is pure Rust by type.
+//! - **`rb_thread_call_without_gvl2`, not `rb_thread_call_without_gvl`** (simp724's G1 on
+//!   #697). The latter checks pending interrupts after the function returns and may
+//!   `longjmp` straight over these Rust frames (undefined behaviour, and a commit that
+//!   happened reported as an `Interrupt`). The `2` form never raises: it returns, and tells
+//!   us through `ran` whether the function ran. If it did, its result is returned and any
+//!   pending interrupt is handled by Ruby after the method returns. If an interrupt was
+//!   pending before it started, nothing ran, and the caller handles the interrupt through
+//!   magnus's safe `Ruby::thread_check_ints` before trying again.
+//! - **No unblocking function** (`NULL`): Ruby never calls into this module while the
+//!   function runs, so an engine call isn't interruptible midway. The calls are bounded
+//!   (waits take timeouts), and the guide says so.
+//! - **Panics** are caught inside the trampoline (`catch_unwind`), so none unwinds through
+//!   Ruby's C frames, and come back as a rescuable `Pigeonhole::Error` once the GVL is back
+//!   (simp724's A2 on #1399: magnus would turn a resumed panic into Ruby's unrescuable
+//!   `fatal`).
+//! - **A masked interrupt** (`Thread.handle_interrupt(... => :never)`) is pending but not
+//!   raised: `rb_thread_call_without_gvl2` declines to run, and `thread_check_ints` raises
+//!   nothing. Rather than loop (simp724's A1), the function then runs once with the GVL held:
+//!   the caller asked not to be interrupted, so keeping the GVL is the honest trade.
+#![allow(unsafe_code)]
+
+use std::ffi::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+use magnus::{Error, Ruby};
+
+/// The call the trampoline makes: the closure (taken when it runs) and its outcome.
+struct Call<F, R> {
+    f: Option<F>,
+    out: Option<std::thread::Result<R>>,
+}
+
+/// Runs the closure in `data` once, without the GVL.
+extern "C" fn trampoline<F: FnOnce() -> R, R>(data: *mut c_void) -> *mut c_void {
+    // SAFETY: `data` is the `&mut Call<F, R>` that `try_once` passed, which lives on its
+    // stack for the whole `rb_thread_call_without_gvl2` call; nothing else touches it until
+    // that call returns, and Ruby calls this function at most once per call.
+    let call = unsafe { &mut *data.cast::<Call<F, R>>() };
+    if let Some(f) = call.f.take() {
+        call.out = Some(catch_unwind(AssertUnwindSafe(f)));
+    }
+    std::ptr::null_mut()
+}
+
+/// One attempt: runs `call`'s closure without the GVL, unless an interrupt was pending.
+fn try_once<F: FnOnce() -> R + Send, R: Send>(call: &mut Call<F, R>) {
+    // SAFETY: called on a Ruby thread holding the GVL (every caller holds a `&Ruby`).
+    // `trampoline::<F, R>` matches the `void *(*)(void *)` signature and reads `data` as
+    // the `Call<F, R>` it is. No unblocking function is passed, so Ruby makes no other
+    // call. The `2` variant never raises or jumps: it returns, ran or not.
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl2(
+            Some(trampoline::<F, R>),
+            std::ptr::from_mut(call).cast::<c_void>(),
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+}
+
+/// Runs `f` with the GVL released and returns its result. A pending interrupt
+/// (`Thread#raise`, `Thread#kill`, a signal) that arrives before `f` starts is raised as a
+/// Ruby exception and `f` doesn't run; one that arrives while `f` runs is handled after
+/// this returns, so `f`'s result (a commit's outcome, say) is never lost. A panic in `f` is
+/// a `Pigeonhole::Error`.
+pub(crate) fn without_gvl<F, R>(ruby: &Ruby, f: F) -> Result<R, Error>
+where
+    F: FnOnce() -> R + Send,
+    R: Send,
+{
+    let mut call = Call {
+        f: Some(f),
+        out: None,
+    };
+    // At most two tries: a pending interrupt is raised between them; one still pending
+    // after that is masked, and `f` runs with the GVL held instead (A1).
+    for _ in 0..2 {
+        try_once(&mut call);
+        match call.out.take() {
+            Some(out) => return finish(ruby, out),
+            None => ruby.thread_check_ints()?,
+        }
+    }
+    let f = call.f.take().expect("not run yet");
+    finish(ruby, catch_unwind(AssertUnwindSafe(f)))
+}
+
+/// `f`'s outcome: its result, or its panic as a `Pigeonhole::Error`.
+fn finish<R>(ruby: &Ruby, out: std::thread::Result<R>) -> Result<R, Error> {
+    out.map_err(|panic| {
+        let what = panic
+            .downcast_ref::<&str>()
+            .map(|s| (*s).to_owned())
+            .or_else(|| panic.downcast_ref::<String>().cloned())
+            .unwrap_or_else(|| "a panic".into());
+        crate::error::uncoded(
+            ruby,
+            "Error",
+            &format!("internal error in an engine call (a panic: {what})"),
+        )
+    })
+}