ratomic 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a08c265d5b7a1c6f780a36dc2448b7cb49421c53f15957a242dd1457503b33c1
-  data.tar.gz: 5dcbb8b1fd92a0e162dcc4daa9ca6cec31117c918bb984ddf03a5ccb68df8779
+  metadata.gz: 764ab083a8815f4f2bd0958be83d5209b10b21d8765dc19720fedd6d042eec89
+  data.tar.gz: 5bf02090ace17e0ca172bcc9f9f2a56f79030f0a92ecf669adecba72aa2ec641
 SHA512:
-  metadata.gz: 0dccc6d4fcceed16ac0437d2550c25deb6ad83c4de57a5b0465d0de604f4376baa776312607d9bd361073c53eeef14e88c651db5cf3efb09bedcd3a38e9ee93d
-  data.tar.gz: b6e9154857321453b8e0b2919ee35551beab7763b80c02358172537e35375628420f10c434d3e97432f87f99e567794de6343855a791d74aa0540d7d11e5ea7c
+  metadata.gz: c7a3e86bfe551b27b28af6655bd7853c1be683d69e759d6b628388282e7443030fe8b56c7e036e1c25f8234de74052fc621747eb94484e84e979b771aaf7ebcc
+  data.tar.gz: 03e9c06d8c5771ab340e1219113b5f67c05da3e97c5ad2a5b7ddefb9e5b54103988eb6cb7c299e09a0808e27fec660b3eaea8a7a3fc200a5aa8dd84161faf484

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 ## [Unreleased]
 
+## 0.4.2
+
+### Fixed
+
+- Prevent `Map#compute` from deadlocking when multiple Ruby threads contend for the same key.
+
+## 0.4.1
+
+### Documentation
+
+- Document the `LocalPool` factory contract.
+- Clarify ownership-transfer versus resource-locality semantics.
+- Add guidance for designing Ractor-shareable factory objects.
+- Add examples of correct and incorrect factory implementations.
+- Improve `LocalPool` API documentation and YARD comments.
+
+### Smoke Tests
+
+- Add PostgreSQL smoke tests alongside Redis smoke tests.
+- Consolidate smoke-test documentation.
+- Add captured Redis and PostgreSQL validation snapshots.
+- Document expected outcomes and interpretation of smoke-test runs.
+
+### Validation
+
+Redis and PostgreSQL smoke tests now demonstrate:
+
+- successful Thread and Ractor execution
+- no `Ractor::MovedError`
+- no `Ractor::IsolationError`
+- successful queue draining
+- preservation of live resource ownership
+- safe reuse of Redis clients and PostgreSQL connections
+
+These tests validate that `LocalPool` is a general-purpose
+resource-locality primitive for stateful network clients rather
+than a Redis-specific abstraction.
+
 ## [0.4.0] - 2026-06-10
 
 ### Added
@@ -10,6 +48,8 @@
 * Added RBS definitions for `LocalPool`.
 * Expanded API documentation and usage examples.
 
+
+
 ### Design
 
 `Ratomic::Pool` and `Ratomic::LocalPool` serve different ownership models:

data/README.md

@@ -42,8 +42,8 @@ RBS signatures are included under `sig/` for downstream type checking.
 
 ## Examples And Benchmarks
 
-- [`redis_poc`](./redis_poc) contains local Redis scripts that exercise
-  `Ratomic::Map`, `Ratomic::Counter`, and `Ratomic::LocalPool` under Thread and
+- [`smoke_tests`](./smoke_tests) contains local Redis and PostgreSQL scripts that
+  exercise `Ratomic::LocalPool` with real stateful clients under Thread and
   Ractor workloads.
 - [`pgoutput-parser`](https://github.com/kanutocd/pgoutput-parser#relation-metadata-tracking)
   uses `Ratomic::Map` for relation metadata tracking in a real CDC pipeline
@@ -313,11 +313,12 @@ leave nested internal state unusable, producing errors such as
 `LocalPool` avoids that class of bug by not moving live resources at all. Work
 moves between Ractors. Live resources stay local.
 
-#### Redis smoke-test snapshot
+#### Redis and PostgreSQL smoke-test snapshots
 
-The Redis POC includes two scripts under `redis_poc/`.
+The smoke tests live under [`smoke_tests/`](./smoke_tests/) and exercise `LocalPool` with real
+Redis clients and PostgreSQL connections.
 
-`basic_redis.rb` exercises repeated Redis operations from both Threads and
+`redis/basic_redis.rb` exercises repeated Redis operations from both Threads and
 Ractors:
 
 ```text
@@ -328,7 +329,7 @@ Ractor
 [{"one" => 42419}, {"two" => 42186}, {"three" => 42400}, {"four" => 42206}, {"five" => 42568}]
 ```
 
-`queue_redis.rb` exercises a producer/consumer Redis queue workload:
+`redis/queue_redis.rb` exercises a producer/consumer Redis queue workload:
 
 ```text
 [:start, Ractor, 2026-06-10 01:17:57.584727984 +0800]
@@ -338,15 +339,24 @@ Ractor
 [:end, 2026-06-10 01:18:02.226310862 +0800]
 ```
 
-These numbers are a smoke-test snapshot, not a formal benchmark claim. The
+`postgres/basic_postgres.rb` exercises repeated PostgreSQL upserts from both
+Threads and Ractors. `postgres/queue_postgres.rb` exercises a table-backed
+producer/consumer workload using `FOR UPDATE SKIP LOCKED`.
+
+These numbers are smoke-test snapshots, not formal benchmark claims. The
 important interpretation is:
 
 - no `Ractor::MovedError`
 - no `Ractor::IsolationError`
 - no process crash
 - all produced queue items were consumed
-- Redis queues drained to zero
-- live Redis clients remained owned by the Ractor that created them
+- Redis queues and PostgreSQL table queues drained to zero
+- live Redis clients and PostgreSQL connections remained owned by the Ractor
+  that created them
+
+Redis proves the network-client shape. PostgreSQL proves the database-connection
+shape. Together they demonstrate that `LocalPool` is not Redis-specific; it is a
+resource-locality primitive for live stateful clients.
 
 #### Inception pool
 

data/ext/ratomic/src/hashmap.rs

@@ -54,6 +54,21 @@ impl MapStore {
         self.map.len()
     }
 
+    fn with_entry<F, R, W>(&self, key: VALUE, mut on_locked: W, f: F) -> R
+    where
+        F: FnOnce(Entry<'_, RubyHashEql, VALUE>) -> R,
+        W: FnMut(),
+    {
+        let mut f = Some(f);
+        loop {
+            if let Some(entry) = self.map.try_entry(RubyHashEql(key)) {
+                return f.take().expect("entry closure already used")(entry);
+            }
+
+            on_locked();
+        }
+    }
+
     pub fn fetch_and_modify<F>(&self, key: VALUE, f: F)
     where
         F: FnOnce(VALUE) -> VALUE,
@@ -61,11 +76,18 @@ impl MapStore {
         self.map.alter(&RubyHashEql(key), |_, value| f(value));
     }
 
-    pub fn compute<F, E>(&self, key: VALUE, missing: VALUE, f: F) -> Result<VALUE, E>
+    pub fn compute<F, E, W>(
+        &self,
+        key: VALUE,
+        missing: VALUE,
+        on_locked: W,
+        f: F,
+    ) -> Result<VALUE, E>
     where
         F: FnOnce(VALUE) -> Result<VALUE, E>,
+        W: FnMut(),
     {
-        match self.map.entry(RubyHashEql(key)) {
+        self.with_entry(key, on_locked, |entry| match entry {
             Entry::Occupied(mut entry) => {
                 let new_value = f(*entry.get())?;
                 entry.insert(new_value);
@@ -76,7 +98,7 @@ impl MapStore {
                 entry.insert(new_value);
                 Ok(new_value)
             }
-        }
+        })
     }
 
     pub fn update<F, E>(&self, key: VALUE, f: F) -> Result<VALUE, E>

data/ext/ratomic/src/lib.rs

@@ -18,7 +18,7 @@ use magnus::{
 use mpmc_queue::MpmcQueue;
 use parking_lot::Mutex;
 use rb_sys::{rb_ext_ractor_safe, rb_thread_call_without_gvl, ruby_special_consts, VALUE};
-use std::{ffi::c_void, mem::transmute};
+use std::{ffi::c_void, mem::transmute, time::Duration};
 
 fn value_to_raw(value: Value) -> VALUE {
     unsafe { transmute::<Value, VALUE>(value) }
@@ -38,6 +38,22 @@ fn make_shareable(ruby: &Ruby, value: Value) -> Result<Value, Error> {
     ractor.funcall("make_shareable", (value,))
 }
 
+unsafe extern "C" fn sleep_briefly_without_gvl(_: *mut c_void) -> *mut c_void {
+    std::thread::sleep(Duration::from_millis(1));
+    std::ptr::null_mut()
+}
+
+fn wait_for_entry_without_gvl() {
+    unsafe {
+        rb_thread_call_without_gvl(
+            Some(sleep_briefly_without_gvl),
+            std::ptr::null_mut(),
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+}
+
 struct Counter(AtomicCounter);
 
 impl Counter {
@@ -158,10 +174,15 @@ impl HashMap {
         }
 
         let proc = ruby.block_proc()?;
-        let raw = rb_self.0.compute(value_to_raw(key), qnil_raw(), |value| {
-            proc.call::<_, Value>((unsafe { value_from_raw(value) },))
-                .map(value_to_raw)
-        })?;
+        let raw = rb_self.0.compute(
+            value_to_raw(key),
+            qnil_raw(),
+            wait_for_entry_without_gvl,
+            |value| {
+                proc.call::<_, Value>((unsafe { value_from_raw(value) },))
+                    .map(value_to_raw)
+            },
+        )?;
 
         Ok(unsafe { value_from_raw(raw) }.into_value_with(ruby))
     }

data/lib/ratomic/version.rb

@@ -2,5 +2,5 @@
 
 module Ratomic
   # Current gem version string.
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratomic
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Mike Perham
@@ -81,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ractor-safe concurrent data structures for Ruby
 test_files: []