kobako 0.27.0 → 0.29.0

data/ext/kobako/src/runtime/filesystem/ruby.rs

@@ -0,0 +1,400 @@
+//! A Filesystem a Host App writes in Ruby: any object answering `open`
+//! and `stat`, asked through `gvl::reenter` on every call the guest makes.
+//!
+//! Its methods take the names and shapes of Ruby's own `File`, `Dir`, and
+//! `IO`, so a Host App can hand an open call on to a real `::File`. A
+//! change method the object lacks answers as read-only; any other method
+//! it lacks answers as unsupported. A file's `EOFError` from `pread` is
+//! its end, an `Errno` the guest has a class for reaches the guest as
+//! that code, and any other `StandardError` reaches the guest as `EIO`.
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{kwargs, prelude::*, Error as MagnusError, RClass, RModule, RString, Ruby, Value};
+
+use std::sync::Arc;
+
+use kobako_runtime::filesystem::{
+    DirEntry, File, FileType, Filesystem, FilesystemError, Hold, Metadata, OpenOptions, Rename,
+};
+
+use crate::runtime::pinned_value::PinnedValue;
+use crate::runtime::{escape, gvl};
+
+/// The Ruby object behind a Mount or a Layer. Whatever holds it on the
+/// Ruby side keeps it alive and in place: the invocation pinning its
+/// Mounts, or the Overlay marking its Layers.
+pub(crate) struct RubyFilesystem {
+    object: Opaque<Value>,
+    /// The device a stat without a `dev` names, the object's own.
+    dev: u64,
+}
+
+impl RubyFilesystem {
+    /// The object as a Filesystem, when it answers `open` and `stat`.
+    pub(crate) fn from_value(value: Value) -> Option<Self> {
+        let answers = |name| value.respond_to(name, false).unwrap_or(false);
+        (answers("open") && answers("stat")).then(|| Self {
+            object: Opaque::from(value),
+            dev: Metadata::unique_device(),
+        })
+    }
+}
+
+/// Ask `object` its `name` method with the GVL held, `answer` making the
+/// call and reading what it returns before Ruby runs anything else. An
+/// object lacking the method fails as `missing`.
+fn ask<T>(
+    object: Opaque<Value>,
+    name: &str,
+    missing: FilesystemError,
+    answer: impl FnOnce(&Ruby, Value) -> Result<T, MagnusError>,
+) -> Result<T, FilesystemError> {
+    ask_or(object, name, Err(missing), answer)
+}
+
+/// As `ask`, an object lacking the method answering `missing`.
+fn ask_or<T>(
+    object: Opaque<Value>,
+    name: &str,
+    missing: Result<T, FilesystemError>,
+    answer: impl FnOnce(&Ruby, Value) -> Result<T, MagnusError>,
+) -> Result<T, FilesystemError> {
+    gvl::reenter(|| {
+        let ruby = Ruby::get().expect("Ruby handle unavailable in a Filesystem call");
+        let object: Value = ruby.get_inner(object);
+        if !object.respond_to(name, false).unwrap_or(false) {
+            return missing;
+        }
+        answer(&ruby, object).map_err(|err| match escape::hold(&ruby, err) {
+            Err(err) => to_error(err),
+            // The invocation ends before the guest reads this.
+            Ok(()) => FilesystemError::Other(String::new()),
+        })
+    })
+}
+
+/// Ask `object` a change, answering nothing more than whether it was made.
+fn change(
+    object: Opaque<Value>,
+    name: &str,
+    args: impl magnus::ArgList,
+    missing: FilesystemError,
+) -> Result<(), FilesystemError> {
+    ask(object, name, missing, |_, object| {
+        object.funcall::<_, _, Value>(name, args).map(drop)
+    })
+}
+
+/// Ask `object` a change it may lack, an object lacking `name` having
+/// nothing of its own to change, while one that answers and refuses still
+/// fails, whatever `Errno` it raises.
+fn change_if_answered(object: Opaque<Value>, name: &str) -> Result<(), FilesystemError> {
+    ask_or(object, name, Ok(()), |_, object| {
+        object.funcall::<_, _, Value>(name, ()).map(drop)
+    })
+}
+
+/// The FilesystemError the nearest `Errno` class of `err` stands for, by
+/// its POSIX name; anything else is `Other`, which reaches the guest as
+/// `EIO`.
+fn to_error(err: MagnusError) -> FilesystemError {
+    let named = err.value().and_then(|exception| {
+        exception
+            .class()
+            .ancestors()
+            .into_iter()
+            .find_map(|module| {
+                let name: Option<String> = module.funcall("name", ()).ok()?;
+                FilesystemError::from_posix_name(name?.strip_prefix("Errno::")?)
+            })
+    });
+    named.unwrap_or_else(|| FilesystemError::Other(err.to_string()))
+}
+
+/// `File::Constants` flags for `options`, read from Ruby since their
+/// values differ by platform.
+fn to_flags(ruby: &Ruby, options: &OpenOptions) -> Result<i64, MagnusError> {
+    let constants: RModule = ruby
+        .class_object()
+        .const_get::<_, RClass>("File")?
+        .const_get("Constants")?;
+    let flag = |name| constants.const_get::<_, i64>(name);
+    let mut flags = match (options.read, options.write || options.truncate) {
+        (_, false) => flag("RDONLY")?,
+        (false, true) => flag("WRONLY")?,
+        (true, true) => flag("RDWR")?,
+    };
+    if options.create || options.create_new {
+        flags |= flag("CREAT")?;
+    }
+    if options.create_new {
+        flags |= flag("EXCL")?;
+    }
+    if options.truncate {
+        flags |= flag("TRUNC")?;
+    }
+    if options.nofollow {
+        flags |= flag("NOFOLLOW")?;
+    }
+    Ok(flags)
+}
+
+fn join(dir: &str, name: &str) -> String {
+    if dir.is_empty() {
+        name.to_string()
+    } else {
+        format!("{dir}/{name}")
+    }
+}
+
+impl Filesystem for RubyFilesystem {
+    fn open(&self, path: &str, options: &OpenOptions) -> Result<Box<dyn File>, FilesystemError> {
+        ask(
+            self.object,
+            "open",
+            FilesystemError::Unsupported,
+            |ruby, fs| {
+                let file: Value = fs.funcall("open", (path, to_flags(ruby, options)?))?;
+                Ok(Box::new(RubyFile::pin(ruby, file)) as Box<dyn File>)
+            },
+        )
+    }
+
+    fn metadata(&self, path: &str) -> Result<Metadata, FilesystemError> {
+        let own_dev = self.dev;
+        ask(
+            self.object,
+            "stat",
+            FilesystemError::Unsupported,
+            |_, fs| {
+                let stat: Value = fs.funcall("stat", (path,))?;
+                let metadata = if stat.funcall::<_, _, bool>("directory?", ())? {
+                    Metadata::new(FileType::Directory, 0)
+                } else {
+                    Metadata::new(FileType::File, stat.funcall("size", ())?)
+                };
+                // A stat names its identity as `File::Stat` does; without a
+                // `dev` the Filesystem stands for a device of its own, so it
+                // shares an identity with no other Filesystem.
+                let dev = if stat.respond_to("dev", false)? {
+                    stat.funcall("dev", ())?
+                } else {
+                    own_dev
+                };
+                Ok(metadata.with_identity(dev, stat.funcall("ino", ())?))
+            },
+        )
+    }
+
+    /// A Ruby object answers `stat` alone, so it holds no links.
+    fn symlink_metadata(&self, path: &str) -> Result<Metadata, FilesystemError> {
+        self.metadata(path)
+    }
+
+    /// A Ruby object matches names exactly, as its contract asks.
+    fn stored_path(&self, path: &str) -> Result<String, FilesystemError> {
+        Ok(path.to_string())
+    }
+
+    /// A Ruby object holds no links to follow.
+    fn canonicalize_beneath(&self, _base: &str, path: &str) -> Result<String, FilesystemError> {
+        Ok(path.to_string())
+    }
+
+    /// A Ruby object holds no links a Policy needs kept from being followed.
+    fn for_policy(&self) -> Option<Arc<dyn Filesystem>> {
+        None
+    }
+
+    /// A Ruby object keeps an `ino` its own while open, as its contract
+    /// asks, so nothing is held.
+    fn hold_directory(&self, _path: &str) -> Result<Option<Hold>, FilesystemError> {
+        Ok(None)
+    }
+
+    fn read_dir(&self, path: &str) -> Result<Vec<DirEntry>, FilesystemError> {
+        let names: Vec<String> = ask(
+            self.object,
+            "children",
+            FilesystemError::Unsupported,
+            |_, fs| fs.funcall("children", (path,)),
+        )?;
+        names
+            .into_iter()
+            .map(|name| {
+                let file_type = self.metadata(&join(path, &name))?.file_type;
+                Ok(DirEntry::new(name, file_type))
+            })
+            .collect()
+    }
+
+    fn create_dir(&self, path: &str) -> Result<(), FilesystemError> {
+        change(
+            self.object,
+            "mkdir",
+            (path,),
+            FilesystemError::ReadOnlyFilesystem,
+        )
+    }
+
+    fn remove_dir(&self, path: &str) -> Result<(), FilesystemError> {
+        change(
+            self.object,
+            "rmdir",
+            (path,),
+            FilesystemError::ReadOnlyFilesystem,
+        )
+    }
+
+    fn remove_file(&self, path: &str) -> Result<(), FilesystemError> {
+        change(
+            self.object,
+            "unlink",
+            (path,),
+            FilesystemError::ReadOnlyFilesystem,
+        )
+    }
+
+    /// `rename(from, to, directory:)`: `true` moves only a directory,
+    /// `false` only a file, `nil` either. What stands at `from` meanwhile
+    /// is the object's to keep still.
+    fn rename(&self, from: &str, to: &str, rename: Rename) -> Result<(), FilesystemError> {
+        // A move the keyword cannot tell the object is refused rather than
+        // widened into one of either kind.
+        let directory = match rename {
+            Rename::Any => None,
+            Rename::File => Some(false),
+            Rename::Directory => Some(true),
+            _ => return Err(FilesystemError::Unsupported),
+        };
+        change(
+            self.object,
+            "rename",
+            (from, to, kwargs!("directory" => directory)),
+            FilesystemError::ReadOnlyFilesystem,
+        )
+    }
+
+    /// Every Invocation shares the Ruby object.
+    fn for_invocation(&self) -> Option<Arc<dyn Filesystem>> {
+        None
+    }
+}
+
+/// One file the Ruby object opened, which only the guest's descriptor
+/// refers to.
+struct RubyFile {
+    file: PinnedValue,
+    closed: bool,
+}
+
+impl RubyFile {
+    fn pin(ruby: &Ruby, file: Value) -> Self {
+        Self {
+            file: PinnedValue::new(ruby, file),
+            closed: false,
+        }
+    }
+
+    /// Ask the file to close, a file lacking `close` having nothing to
+    /// release.
+    fn release(&mut self) -> Result<(), FilesystemError> {
+        self.closed = true;
+        change_if_answered(self.file.get(), "close")
+    }
+}
+
+impl File for RubyFile {
+    fn read_at(&mut self, buf: &mut [u8], offset: u64) -> Result<usize, FilesystemError> {
+        ask(
+            self.file.get(),
+            "pread",
+            FilesystemError::Unsupported,
+            |ruby, file| {
+                // `IO#pread` raises `EOFError` at the end of a file, which reads as nothing.
+                let read: Option<RString> = match file.funcall("pread", (buf.len(), offset)) {
+                    Err(err) if err.is_kind_of(ruby.exception_eof_error()) => None,
+                    read => read?,
+                };
+                let Some(read) = read else { return Ok(0) };
+                // SAFETY: the bytes are copied out before Ruby runs again.
+                let bytes = unsafe { read.as_slice() };
+                let len = bytes.len().min(buf.len());
+                buf[..len].copy_from_slice(&bytes[..len]);
+                Ok(len)
+            },
+        )
+    }
+
+    fn write_at(&mut self, buf: &[u8], offset: u64) -> Result<usize, FilesystemError> {
+        ask(
+            self.file.get(),
+            "pwrite",
+            FilesystemError::ReadOnlyFilesystem,
+            |ruby, file| file.funcall("pwrite", (ruby.str_from_slice(buf), offset)),
+        )
+        .and_then(|written: usize| match written {
+            written if written <= buf.len() => Ok(written),
+            written => Err(FilesystemError::Other(format!(
+                "pwrite answered {written} bytes written of the {} it was handed",
+                buf.len()
+            ))),
+        })
+    }
+
+    /// The file's `append` writes all of `buf` at its end in one step and
+    /// answers where the file then ends, as `IO#pos` does after a write to
+    /// a file opened to append. A file lacking it cannot append, since its
+    /// `size` and `pwrite` are two steps another writer can land between.
+    fn append(&mut self, buf: &[u8]) -> Result<(u64, usize), FilesystemError> {
+        ask(
+            self.file.get(),
+            "append",
+            FilesystemError::Unsupported,
+            |ruby, file| file.funcall("append", (ruby.str_from_slice(buf),)),
+        )
+        .and_then(|end: u64| match end.checked_sub(buf.len() as u64) {
+            Some(at) => Ok((at, buf.len())),
+            None => Err(FilesystemError::Other(format!(
+                "append answered the file ending at {end}, before the {} bytes it wrote",
+                buf.len()
+            ))),
+        })
+    }
+
+    fn metadata(&self) -> Result<Metadata, FilesystemError> {
+        ask(
+            self.file.get(),
+            "size",
+            FilesystemError::Unsupported,
+            |_, file| Ok(Metadata::new(FileType::File, file.funcall("size", ())?)),
+        )
+    }
+
+    fn set_len(&mut self, len: u64) -> Result<(), FilesystemError> {
+        change(
+            self.file.get(),
+            "truncate",
+            (len,),
+            FilesystemError::ReadOnlyFilesystem,
+        )
+    }
+
+    /// A file lacking `fsync` has nothing of its own to flush.
+    fn sync(&mut self) -> Result<(), FilesystemError> {
+        change_if_answered(self.file.get(), "fsync")
+    }
+
+    fn close(mut self: Box<Self>) -> Result<(), FilesystemError> {
+        self.release()
+    }
+}
+
+/// A file the guest never closed is closed here, its failure discarded.
+impl Drop for RubyFile {
+    fn drop(&mut self) {
+        if !self.closed {
+            let _ = self.release();
+        }
+    }
+}

data/ext/kobako/src/runtime/filesystem.rs

@@ -0,0 +1,236 @@
+//! The Ruby face of the Filesystem: `Kobako::Filesystem::Memory`,
+//! `Temporary`, `Directory`, and `Overlay`, each standing for the
+//! `kobako_runtime` Filesystem of that kind.
+//!
+//! A kind kobako ships runs in Rust; Ruby only picks it and the access.
+//! Ruby is asked again while the guest runs through a mount's block, at
+//! most once per open or change, and through a Filesystem written in
+//! Ruby, once per call.
+
+mod grants;
+mod ruby;
+
+use std::sync::Arc;
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{
+    function, gc, method, prelude::*, scan_args::get_kwargs, scan_args::scan_args,
+    DataTypeFunctions, Error as MagnusError, RHash, RModule, RString, Ruby, Symbol, TypedData,
+    Value,
+};
+
+use ruby::RubyFilesystem;
+
+use kobako_runtime::filesystem::{
+    Access, Blocking, Directory, Filesystem, Memory, Overlay, Temporary,
+};
+
+pub(super) use grants::{to_grants, validate_mount};
+
+macro_rules! filesystem_class {
+    ($name:ident, $class:literal) => {
+        #[magnus::wrap(class = $class, free_immediately, size)]
+        pub(super) struct $name(Arc<dyn Filesystem>);
+    };
+}
+
+filesystem_class!(MemoryFs, "Kobako::Filesystem::Memory");
+filesystem_class!(TemporaryFs, "Kobako::Filesystem::Temporary");
+filesystem_class!(DirectoryFs, "Kobako::Filesystem::Directory");
+
+/// The Overlay itself rather than a shared handle, so `layer` can answer a
+/// new one and leave this one as it was. It marks the Ruby object of
+/// every Layer, since a Filesystem written in Ruby has nothing else
+/// keeping it alive.
+#[derive(magnus::TypedData)]
+#[magnus(class = "Kobako::Filesystem::Overlay", free_immediately, size, mark)]
+pub(super) struct OverlayFs {
+    overlay: Overlay,
+    layers: Vec<Opaque<Value>>,
+}
+
+impl DataTypeFunctions for OverlayFs {
+    fn mark(&self, marker: &gc::Marker) {
+        marker.mark_slice(&self.layers);
+    }
+}
+
+pub(super) fn register(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
+    let module = kobako.define_module("Filesystem")?;
+    let memory = module.define_class("Memory", ruby.class_object())?;
+    memory.define_singleton_method("new", function!(memory_new, -1))?;
+    let temporary = module.define_class("Temporary", ruby.class_object())?;
+    temporary.define_singleton_method("new", function!(temporary_new, -1))?;
+    let directory = module.define_class("Directory", ruby.class_object())?;
+    directory.define_singleton_method("new", function!(directory_new, 1))?;
+    let overlay = module.define_class("Overlay", ruby.class_object())?;
+    overlay.define_singleton_method("new", function!(overlay_new, 0))?;
+    overlay.define_method("layer", method!(overlay_layer, -1))?;
+    MemoryFs::class(ruby);
+    TemporaryFs::class(ruby);
+    DirectoryFs::class(ruby);
+    OverlayFs::class(ruby);
+    Ok(())
+}
+
+/// `Memory.new(files = {}, limit: 64 MiB, inodes:)`: each
+/// `path => contents` pair becomes a file, its directories created along
+/// the way. Ruby hands a bare `"path" => contents` over as keywords, so
+/// every String keyword is a file too. Without `inodes:` the entries
+/// follow the limit.
+fn memory_new(args: &[Value]) -> Result<MemoryFs, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let args = scan_args::<(), (Option<RHash>,), (), (), RHash, ()>(args)?;
+    let mut files = Vec::new();
+    let mut limit = Some(Memory::DEFAULT_LIMIT);
+    let mut inodes = None;
+    let limit_key = ruby.to_symbol("limit");
+    let inodes_key = ruby.to_symbol("inodes");
+    for hash in args.optional.0.into_iter().chain([args.keywords]) {
+        hash.foreach(|key: Value, value: Value| {
+            match Symbol::from_value(key) {
+                Some(key) if key.equal(limit_key)? => limit = to_limit(value)?,
+                Some(key) if key.equal(inodes_key)? => inodes = Some(to_limit(value)?),
+                Some(key) => {
+                    return Err(MagnusError::new(
+                        ruby.exception_arg_error(),
+                        format!("unknown keyword: :{}", key.name()?),
+                    ))
+                }
+                None => files.push((
+                    String::try_convert(key)?,
+                    super::rstring_to_vec(RString::try_convert(value)?),
+                )),
+            }
+            Ok(magnus::r_hash::ForEach::Continue)
+        })?;
+    }
+    // A list no Memory holds is an `ArgumentError` the Host App can rescue.
+    let memory = Memory::try_from_iter(files)
+        .map_err(|error| MagnusError::new(ruby.exception_arg_error(), error.to_string()))?
+        .with_limit(limit);
+    Ok(MemoryFs(Arc::new(match inodes {
+        Some(inodes) => memory.with_inodes(inodes),
+        None => memory,
+    })))
+}
+
+/// `Temporary.new(limit: 64 MiB, inodes:)`.
+fn temporary_new(args: &[Value]) -> Result<TemporaryFs, MagnusError> {
+    let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+    let kwargs = get_kwargs::<_, (), (Option<Value>, Option<Value>), ()>(
+        args.keywords,
+        &[],
+        &["limit", "inodes"],
+    )?;
+    let (limit, inodes) = kwargs.optional;
+    let limit = match limit {
+        Some(limit) => to_limit(limit)?,
+        None => Some(Memory::DEFAULT_LIMIT),
+    };
+    let temporary = Temporary::new().with_limit(limit);
+    Ok(TemporaryFs(Arc::new(match inodes {
+        Some(inodes) => temporary.with_inodes(to_limit(inodes)?),
+        None => temporary,
+    })))
+}
+
+/// A `limit:` or `inodes:` count, or `nil` for none.
+fn to_limit(limit: Value) -> Result<Option<usize>, MagnusError> {
+    Option::<usize>::try_convert(limit)
+}
+
+fn directory_new(path: String) -> Result<DirectoryFs, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    Directory::new(&path)
+        .map(|directory| DirectoryFs(Arc::new(directory)))
+        .map_err(|err| {
+            MagnusError::new(
+                ruby.exception_arg_error(),
+                format!("cannot open host directory {path}: {err}"),
+            )
+        })
+}
+
+/// `Overlay.new`, with no Layer yet.
+fn overlay_new() -> OverlayFs {
+    OverlayFs {
+        overlay: Overlay::new().with_blocking(Arc::new(GvlFreeWait)),
+        layers: Vec::new(),
+    }
+}
+
+/// An Overlay's thread waits for its lock without the GVL, so a holder
+/// asking a Layer written in Ruby can take the GVL and finish.
+struct GvlFreeWait;
+
+impl Blocking for GvlFreeWait {
+    fn wait(&self, wait: &mut dyn FnMut()) {
+        super::gvl::region(super::gvl::holds(), wait);
+    }
+}
+
+/// `layer(filesystem, access: :read)`, a new Overlay with `filesystem`
+/// beneath this one's Layers.
+fn overlay_layer(overlay: &OverlayFs, args: &[Value]) -> Result<OverlayFs, MagnusError> {
+    let args = scan_args::<(Value,), (), (), (), RHash, ()>(args)?;
+    let kwargs = get_kwargs::<_, (), (Option<Value>,), ()>(args.keywords, &[], &["access"])?;
+    let (filesystem,) = args.required;
+    let access = match kwargs.optional.0 {
+        Some(access) => to_access(access)?,
+        None => Access::Read,
+    };
+    let mut layers = overlay.layers.clone();
+    layers.push(Opaque::from(filesystem));
+    Ok(OverlayFs {
+        overlay: overlay
+            .overlay
+            .clone()
+            .layer(to_filesystem(filesystem)?, access),
+        layers,
+    })
+}
+
+fn to_access(access: Value) -> Result<Access, MagnusError> {
+    let name = Symbol::from_value(access)
+        .map(|symbol| symbol.name())
+        .transpose()?;
+    match name.as_deref() {
+        Some("read") => Ok(Access::Read),
+        Some("read_write") => Ok(Access::ReadWrite),
+        _ => Err(MagnusError::new(
+            Ruby::get().expect("Ruby thread").exception_arg_error(),
+            format!(
+                "access must be :read or :read_write, got {}",
+                access.inspect()
+            ),
+        )),
+    }
+}
+
+/// The Filesystem a Ruby handle of any kobako kind stands for.
+fn to_filesystem(value: Value) -> Result<Arc<dyn Filesystem>, MagnusError> {
+    if let Ok(fs) = <&MemoryFs>::try_convert(value) {
+        return Ok(fs.0.clone());
+    }
+    if let Ok(fs) = <&TemporaryFs>::try_convert(value) {
+        return Ok(fs.0.clone());
+    }
+    if let Ok(fs) = <&DirectoryFs>::try_convert(value) {
+        return Ok(fs.0.clone());
+    }
+    if let Ok(fs) = <&OverlayFs>::try_convert(value) {
+        return Ok(Arc::new(fs.overlay.clone()));
+    }
+    if let Some(fs) = RubyFilesystem::from_value(value) {
+        return Ok(Arc::new(fs));
+    }
+    let ruby = Ruby::get().expect("Ruby thread");
+    Err(MagnusError::new(
+        ruby.exception_type_error(),
+        format!(
+            "expected a Kobako::Filesystem or an object answering open and stat, got {}",
+            value.class()
+        ),
+    ))
+}

data/ext/kobako/src/runtime/gvl.rs

@@ -1,4 +1,4 @@
-//! Releasing Ruby's GVL for the guest-execution span so distinct Sandboxes on
+//! Releasing Ruby's GVL for an invocation's guest span so distinct Sandboxes on
 //! distinct Threads run their guest code in parallel.
 //!
 //! `region` brackets one invocation's guest span, releasing the GVL when the
@@ -22,8 +22,6 @@ thread_local! {
     static GVL_RELEASED: Cell<bool> = const { Cell::new(false) };
 }
 
-/// Run `f` (one invocation's guest-execution span) and return its value,
-/// releasing the GVL for the span iff `release`. When holding, `f` runs inline.
 pub(crate) fn region<F, R>(release: bool, f: F) -> R
 where
     F: FnOnce() -> R,
@@ -37,10 +35,14 @@ where
     })
 }
 
-/// Run `f` (a guest→host dispatch callback) under the GVL. Re-acquires the GVL
-/// when the enclosing region released it, and runs inline when the GVL is
-/// already held — hold mode, or a nested dispatch whose outer frame re-acquired
-/// it.
+/// Whether this thread holds the GVL: outside any released region, or
+/// inside a dispatch that re-acquired it.
+pub(crate) fn holds() -> bool {
+    !GVL_RELEASED.with(|g| g.get())
+}
+
+/// Runs inline when the GVL is already held — hold mode, or a nested
+/// dispatch whose outer frame re-acquired it.
 pub(crate) fn reenter<F, R>(f: F) -> R
 where
     F: FnOnce() -> R,
@@ -79,9 +81,8 @@ struct GvlCtx<F, R> {
     result: Option<std::thread::Result<R>>,
 }
 
-/// The `extern "C"` shim the `rb_thread_call_*` functions call: it runs the
-/// erased closure under `catch_unwind` so a panic is captured here rather than
-/// unwinding across the C frame, and stashes the outcome for `call_via`.
+/// Runs the closure under `catch_unwind`, so a panic is captured here rather
+/// than unwinding across the C frame.
 unsafe extern "C" fn trampoline<F, R>(data: *mut c_void) -> *mut c_void
 where
     F: FnOnce() -> R,
@@ -92,9 +93,6 @@ where
     ptr::null_mut()
 }
 
-/// Drive `f` through one of the `rb_thread_call_*` entry points (`invoke`),
-/// erasing it to the C callback shape and re-raising on the caller's thread any
-/// panic the trampoline caught.
 fn call_via<F, R>(
     f: F,
     invoke: impl FnOnce(unsafe extern "C" fn(*mut c_void) -> *mut c_void, *mut c_void) -> *mut c_void,