virgodb 0.1.4-x86_64-linux-gnu → 0.3.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfde1ca05cc7f6d12cd117d9ff1ec6bd215a5914637f4641b2b01822077357ac
-  data.tar.gz: 3c51aabe24cf49d04bc8fe1783c1b6533e830f57d1985bcdbc513067f250a4bf
+  metadata.gz: 6141e1a5628b4293f7d63bd3143fe20bcbff6f697df38fc67c1da4c2669369ab
+  data.tar.gz: 7814e9e3a10ba0ce4e5126e492d38410637aa818d21abb4352b6f038fc9b4139
 SHA512:
-  metadata.gz: c43403672c327752e7710e1bdfce3bbca7710d4b20d27f42529ded6272776bd553ec5d40894a2bc53e4e92cf6ba9628eb6a28860b3fdd9e72a6dfb3674f582da
-  data.tar.gz: 5162de79d2d0979f6677535250c612dd3c1e208266339a8120612fb0ae6a1a6fa8c0fe75ba2aaaf01c2289626d0e83155d41f7f9e24e3c72ed73547a312fad43
+  metadata.gz: '0468833ba6f07aed2d56ea13ca5d158a523fb64486ec4fa5259c969200f9c4e991fb96a545ad26a78c8531460855c59dcbcc0904be5a8d43f558dd2bb4f27255'
+  data.tar.gz: 475c654f9a604b83c05b0036c4cdffb478c339b05fb794a9cef445b5244584394cef90289bbb57cdc8f7c65a8918fb7a8111e545d9a790c6b375eca454929a47

data/lib/virgodb/table.rb

@@ -11,6 +11,19 @@ module Virgodb
   # just failing the first write attempt. Mutex-guarded so concurrent
   # callers in one process can't race to double-initialize.
   #
+  # The SAME mutex also serializes every actual write_row/tombstone/flush!
+  # call, not just lazy Writer init -- the underlying Rust Writer wraps a
+  # plain RefCell, explicitly documented "not thread-safe by design," so
+  # two Ruby threads calling in concurrently would double-borrow it. This
+  # is safe today even without a Ruby-level lock, PURELY because none of
+  # those three Rust entry points release the GVL (crates/virgodb_ruby/
+  # src/writer.rs, tombstone.rs) -- MRI's GVL already fully serializes them.
+  # That's an implicit invariant a future perf change could silently break
+  # (the read path already got its own GVL-release fix once, see the root
+  # README's "Known issues" -- the write path getting the same treatment
+  # someday isn't a hypothetical). Locking explicitly here means this
+  # class's correctness no longer depends on that invariant holding.
+  #
   # This is the boilerplate every host app embedding virgodb needs around
   # the raw Writer/start_maintenance/query FFI -- written once here instead
   # of once per host app. Deliberately does NOT rescue write failures: a
@@ -35,8 +48,18 @@ module Virgodb
 
     attr_reader :manifest_path
 
+    # `writer` is called BEFORE entering `@mutex.synchronize` here (and in
+    # `tombstone`/`flush!` below), never from inside it -- `writer`'s own
+    # lazy-init path takes the SAME mutex when it actually needs to build
+    # one, and Ruby's Mutex is not reentrant (a thread re-locking a mutex
+    # it already holds raises ThreadError immediately, it doesn't queue).
+    # Safe regardless of ordering: `@writer` is assigned at most once and
+    # never reassigned afterward, so the reference `writer` returns stays
+    # valid and correct for the rest of this object's lifetime no matter
+    # what happens between fetching it and entering the lock below.
     def write_row(**attrs)
-      writer.write_row(**attrs)
+      w = writer
+      @mutex.synchronize { w.write_row(**attrs) }
     end
 
     # `tombstone` alone doesn't touch the Writer -- calling `writer` first
@@ -45,19 +68,60 @@ module Virgodb
     # recorded for it to eventually act on.
     def tombstone(column:, value:)
       writer
-      Virgodb.tombstone(@manifest_path, @sql_table_name, column.to_s, value.to_s)
+      @mutex.synchronize { Virgodb.tombstone(@manifest_path, @sql_table_name, column.to_s, value.to_s) }
     end
 
     # Returns parsed JSON rows (Array of String-keyed Hash). `sql` must
     # refer to the table by its real SQL name (the `sql_table_name` this
     # instance was built with), not any shorthand a caller's own registry
-    # might use for it.
+    # might use for it. Not mutex-guarded -- a read never touches the
+    # Writer's RefCell state at all (Virgodb.query is a separate, already
+    # GVL-released, independently-safe-for-concurrency FFI entry point).
     def query(sql, partition_keys: nil)
       JSON.parse(Virgodb.query(@manifest_path, @sql_table_name, sql, partition_keys))
     end
 
     def flush!
-      writer.flush!
+      w = writer
+      @mutex.synchronize { w.flush! }
+    end
+
+    # This table's current maintenance status (a String-keyed Hash with
+    # "holder"/"lease_expires_at"/"last_attempt_at"/"last_success_at"/
+    # "last_error"), or nil if maintenance has never even attempted a lease
+    # claim yet (e.g. this Table hasn't done its first write, so
+    # start_maintenance was never called -- see `ensure_maintenance_started`).
+    # A real answer to "is this table's background maintenance actually
+    # working," not just "is the thread alive" -- meant to be polled by a
+    # host app's own health check, not by this class itself. Not
+    # mutex-guarded, same reasoning as `query` above: a read never touches
+    # the Writer's RefCell state.
+    def maintenance_health
+      json = Virgodb.maintenance_health(@manifest_path, @sql_table_name)
+      json && JSON.parse(json)
+    end
+
+    # Claims this table's maintenance lease as `holder` for the next
+    # `lease_duration_secs` seconds, locking out the real maintenance
+    # thread (its own claim attempts fail against an unexpired lease the
+    # same way two maintenance threads would contend) -- meant for a
+    # caller like a backup job that needs a window where compaction/vacuum
+    # won't rewrite or delete this table's data directory. Returns `false`
+    # (not an error) if someone else's lease is still active; callers
+    # should retry rather than treat that as failure. Doesn't call `writer`
+    # first (unlike `tombstone` above) -- claiming a lease has nothing to
+    # do with this table's Writer, and a caller like a backup job may never
+    # otherwise touch this table's Writer in this process at all. Not
+    # mutex-guarded, same reasoning as `query`/`maintenance_health` above.
+    def claim_maintenance_lease(holder:, lease_duration_secs:)
+      Virgodb.claim_maintenance_lease(@manifest_path, @sql_table_name, holder.to_s, lease_duration_secs)
+    end
+
+    # Releases a lease claimed via `claim_maintenance_lease` above, so the
+    # real maintenance thread can resume on its next poll rather than
+    # waiting out the full lease duration.
+    def release_maintenance_lease(holder:)
+      Virgodb.release_maintenance_lease(@manifest_path, @sql_table_name, holder.to_s)
     end
 
     private

data/lib/virgodb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Virgodb
-  VERSION = "0.1.4"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: virgodb
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.3.0
 platform: x86_64-linux-gnu
 authors:
 - virgodb
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   Embeds virgodb (an OLAP engine backed by Parquet + DataFusion) directly into a Ruby process