lora-ruby 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41b5e0a62144ae0a4c9883e0d24c0ee865ade10db38c9ea79a4f24486d153af2
-  data.tar.gz: '07479b48e2fb8d00de5e1072fbde77ccf15a1172e08f47a9477ce59209554bce'
+  metadata.gz: 9219caa445bf7016b0f028045898a8d5f19aed79ef26dec23a37fddeec143a8a
+  data.tar.gz: 27bbd9ee828ee1b8ce9b81e17fbf20e6d6ed3226165f542428575c55c0bd55f2
 SHA512:
-  metadata.gz: e79be519134ea0065d3b3b8a0d3b22221b2cf01b22e655df01bd974c1f56dfe8d783d8dbe9927e13c02343236767eb9672ec90880e43ad850ecdbd65071503f4
-  data.tar.gz: 10c8e470fbe1bae4649ddbb5a83b46adce508db7f2d7db9954ea9094e15a8437e954534412a7bba5cc68ae86e22a2c7b974333813903428bdcb905af64cbdd39
+  metadata.gz: 5524d305cbd6d90db822fc1eda50ad8c9589cf74b9df4c05015a577c91b2b7daf7dc2ddb8ebb6ddc17b3e2243057150f8011d7b28cf9a0ac1f883cd6504c8c8a
+  data.tar.gz: 1d06df901d7c280d740c132d65a3643446390e9f781eedc403f4c5106290cb1093347ee0766b211a4563a76a9ce9a0d7172bc44b55a8ddd70c655aa0068ca722

data/README.md

@@ -206,14 +206,24 @@ db = LoraRuby::Database.open_wal(
 
 ## Concurrency (GVL release)
 
-`Database#execute` calls `rb_thread_call_without_gvl`, so other Ruby
-threads run while the engine is busy. Auto-commit reads can overlap on engine
-snapshots; write commits and explicit read-write transactions serialize.
+Every engine call that can block (`execute`, `explain`, `profile`, `clear`,
+snapshot save/load, opening and closing a database) runs under
+`rb_thread_call_without_gvl`, so other Ruby threads run while the engine is
+busy. `node_count` and `relationship_count` read a snapshot without waiting
+and keep the GVL. Auto-commit reads can overlap on engine snapshots; writes
+serialize on the engine's writer lock.
+
+A write waiting for that lock waits with the GVL released, and the Ruby
+binding has no interactive transactions: each write takes the lock and
+releases it within one call. So a waiting writer never blocks the writer
+holding the lock, however many threads write at once.
 
 The engine has no cancellation hook, so we pass a `NULL` unblock
-function. A thread interrupted mid-query (`Thread#kill`) will observe
-the interrupt **after** the current query finishes. Keep queries short
-if you rely on cooperative cancellation.
+function. A thread interrupted mid-query (`Thread#kill`, `Ctrl-C`) will
+observe the interrupt **after** the current call finishes, including a
+write that was still waiting for the writer lock (it runs, then the
+interrupt fires). Keep queries short if you rely on cooperative
+cancellation.
 
 ## Local development
 

data/lib/lora_ruby/version.rb

@@ -10,5 +10,5 @@ module LoraRuby
   # Guard against redefinition so re-requiring this file (or loading
   # both paths) doesn't emit a "warning: already initialized constant"
   # when the native extension loads second with the identical value.
-  VERSION = "0.18.0" unless const_defined?(:VERSION)
+  VERSION = "0.19.0" unless const_defined?(:VERSION)
 end

data/src/gvl.rs

@@ -4,6 +4,36 @@ use std::ffi::c_void;
 use std::fmt;
 use std::mem::MaybeUninit;
 use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+/// Calls running with the GVL released right now, process-wide.
+static RELEASED: AtomicUsize = AtomicUsize::new(0);
+
+/// Whether no thread runs a GVL-free call. Called with the GVL held, this
+/// means no other Ruby thread can hold or take the engine's writer lock
+/// before the caller does: taking it needs either the GVL or a GVL-free
+/// call (the binding has no interactive transactions or streams, and it
+/// is not Ractor-safe, so there is one GVL). Background threads of a
+/// persistent database are not covered.
+pub(crate) fn nothing_released() -> bool {
+    RELEASED.load(Ordering::SeqCst) == 0
+}
+
+/// Counts a call in [`RELEASED`] while alive.
+struct Released;
+
+impl Released {
+    fn enter() -> Self {
+        RELEASED.fetch_add(1, Ordering::SeqCst);
+        Self
+    }
+}
+
+impl Drop for Released {
+    fn drop(&mut self) {
+        RELEASED.fetch_sub(1, Ordering::SeqCst);
+    }
+}
 
 pub(crate) struct GvlPanic {
     payload: Box<dyn std::any::Any + Send>,
@@ -37,6 +67,13 @@ impl fmt::Display for GvlPanic {
 
 /// Run `f` with Ruby's Global VM Lock released.
 ///
+/// Every engine call that can wait for the writer lock goes through here.
+/// The binding has no interactive transactions: a writer takes the lock
+/// and releases it inside one call, entirely GVL-free, so the holder never
+/// needs the GVL to finish and a waiter always sees it released. Waiting
+/// with the GVL held would freeze every Ruby thread for the wait (and, with
+/// a lock held across Ruby calls, deadlock).
+///
 /// Semantics match `rb_thread_call_without_gvl` — other Ruby threads can
 /// progress while `f` runs. The closure MUST NOT touch Ruby state (no
 /// `Value`s, no allocations into the Ruby heap), which we arrange by
@@ -73,6 +110,7 @@ where
         func: Some(f),
         result: MaybeUninit::uninit(),
     };
+    let _released = Released::enter();
 
     unsafe {
         rb_sys::rb_thread_call_without_gvl(

data/src/lib.rs

@@ -183,17 +183,35 @@ fn database_open_wal(ruby: &Ruby, args: &[Value]) -> Result<Database, MagnusErro
     Ok(Database::from_db(db))
 }
 
+/// `clear` takes the engine's writer lock, so it waits for any write in
+/// flight. That wait runs with the GVL released like every other engine
+/// call: holding it would freeze every Ruby thread until the running
+/// writer committed. When no write can be in flight (an in-memory database
+/// and no GVL-free call running, see [`gvl::nothing_released`]) the lock
+/// is free and clear runs at once, so it skips the GVL round trip.
 fn database_clear(ruby: &Ruby, rb_self: &Database) -> Result<(), MagnusError> {
-    database_inner(ruby, rb_self)?.clear();
-    Ok(())
+    let db = database_inner(ruby, rb_self)?;
+    if db.wal().is_none() && gvl::nothing_released() {
+        return db.try_clear().map_err(|e| query_error_from_anyhow(ruby, e));
+    }
+    without_gvl_lora_result(ruby, move || db.try_clear())
 }
 
+/// Dropping the last handle to a persistent database flushes and closes its
+/// WAL, so that drop runs with the GVL released like any other engine
+/// call. An in-memory database has nothing to flush and drops in place.
 fn database_close(ruby: &Ruby, rb_self: &Database) -> Result<(), MagnusError> {
-    let mut slot = rb_self
+    let db = rb_self
         .db
         .lock()
-        .map_err(|_| query_error(ruby, "database lock poisoned"))?;
-    slot.take();
+        .map_err(|_| query_error(ruby, "database lock poisoned"))?
+        .take();
+    match db {
+        Some(db) if db.wal().is_some() => {
+            without_gvl(move || drop(db)).map_err(|panic| query_error(ruby, panic.to_string()))?
+        }
+        _ => {}
+    }
     Ok(())
 }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lora-ruby
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - LoraDB, Inc.