virgodb 0.1.4-x86_64-linux-gnu → 0.2.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfde1ca05cc7f6d12cd117d9ff1ec6bd215a5914637f4641b2b01822077357ac
-  data.tar.gz: 3c51aabe24cf49d04bc8fe1783c1b6533e830f57d1985bcdbc513067f250a4bf
+  metadata.gz: b2c55249e7aad1d1fa30b2e5b0b33faeededd48155b6a1d31cad1d66c86f150f
+  data.tar.gz: e7f80300627403933ea3dcfb0bc3e8e3321caa3b0f0d11309238978fa65915a0
 SHA512:
-  metadata.gz: c43403672c327752e7710e1bdfce3bbca7710d4b20d27f42529ded6272776bd553ec5d40894a2bc53e4e92cf6ba9628eb6a28860b3fdd9e72a6dfb3674f582da
-  data.tar.gz: 5162de79d2d0979f6677535250c612dd3c1e208266339a8120612fb0ae6a1a6fa8c0fe75ba2aaaf01c2289626d0e83155d41f7f9e24e3c72ed73547a312fad43
+  metadata.gz: '00849d11354b21ffa53f665b607aad25114b02f78d296b9b8594016962ea378eb1bdcc905c77d5024e1cf4376b28af183da2c3918d30965bba7f3080547d238e'
+  data.tar.gz: b8190d81fdcd7276cf12ead7c054a10e8e61d6f25daa2f39ad42f2166b8118c917cfe031b26cfbfa6239d420ad4ba5ce8e3e8c14b010028c8e8b019871df4d83

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,37 @@ 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
 
     private

data/lib/virgodb/version.rb

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

metadata

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