ratomic 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fbef9f27ee3ebd3839fb95b3e3c4685aaa34be9c22f1314974726c5f38aada8
-  data.tar.gz: 668591405949669d19687a678029ca07f46f155b3740f9a7d5fff599a5d8003c
+  metadata.gz: 5196316489486d3034c046db087ae5878dc7fcf2f2e3d4086d91c128f8a30dd5
+  data.tar.gz: 6bf7a6aed05756ff9a0f49f274d69ed91b1f722930c94a140cc5450746fec3f2
 SHA512:
-  metadata.gz: e31111fffe0abc54d5e7c945c7bd618dc7b201a0b35c48c438dbe7cf3db414106c5638ac4680f67a018a55545f5f62d09e6efe79887577f9a8516b5d7d6569cc
-  data.tar.gz: b46b875f77412cfbb3edba3ed07fd2087fb70ded07023ad091d32f911d4fa5b9af06fa42a1db770bc24d357683828cc0ec3df5f429ae177c45bc3df4f7ebc9fb
+  metadata.gz: f0276e6c7e78c7bdcbabb3839d59eb70e58289f3662fe1df244fce9abc9b3a1eeb3454a4116081cd0f0426e470ed64a3d0108f8a57650455e17cc96f111f51e7
+  data.tar.gz: 8eb3b4c4f248569568ea7394a89156961aeb8108b0448c5ef3012045486537cd3c862fff684ac39192d2c31842159e5ad798b9005ce48909281f19d1c9043827

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-05
+
+- Promote the DashMap-backed `Ratomic::Map` API as the primary concurrent Hash primitive.
+- Add `Ratomic::Map#key?`, `#include?`, `#member?`, and `#delete`.
+- Add `Ratomic::Map#fetch`, `#compute`, `#fetch_or_store`, and `#upsert` for atomic per-key workflows.
+- Add `Ratomic::Map#increment`, `#decrement`, `#append`, and `#add_to_set` convenience methods for shared counters and bucket-style values.
+- Improve API documentation for `Counter`, `Map`, `Queue`, and `Pool`.
+- Add GitHub Pages deployment for generated YARD API documentation.
+- Add Redis POC scripts for exercising `Ratomic::Map`, `Ratomic::Counter`, and `Ratomic::Pool` under Thread and Ractor workloads.
+- Remove `Counter#inc` and `Counter#dec` in favor of the native `#increment` and `#decrement` methods.
+
+## [0.2.1] - 2026-06-04
+
+- Fix `Ratomic::Queue` slot indexing for non-power-of-two capacities.
+- Fix `Ratomic::Map#fetch_and_modify` to propagate block exceptions instead of panicking.
+
 ## [0.2.0] - 2026-06-04
 
 - Drop Ruby 3.x support and require Ruby 4.

data/README.md

@@ -1,176 +1,250 @@
 # Ratomic
 
-Ratomic provides mutable data structures for use with Ruby's Ractors.
-This allows Ruby code to scale beyond the infamous GVL.
+[![Gem Version](https://badge.fury.io/rb/ratomic.svg)](https://badge.fury.io/rb/ratomic)
+[![CI](https://github.com/mperham/ratomic/workflows/CI/badge.svg)](https://github.com/mperham/ratomic/actions)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%204.0-ruby.svg)](https://www.ruby-lang.org/en/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-# HELP WANTED!
+Ratomic provides mutable data structures for Ruby Ractors. Its primitives are backed by
+native Rust concurrency libraries so Ruby code can share useful state across Ractors
+without falling back to one global lock.
 
-> If you know Rust and Ruby C-extensions, we need your help!
-> This project is brand new and could use your knowledge!
-> If you don't know Rust or C, consider this a challenge to learn and solve.
-> Read through the [issues](//github.com/mperham/ratomic/issues) to find work that sounds interesting to you.
+## Project Direction
 
-## How to contribute
+Ratomic focuses on practical Ractor-safe primitives with a small API surface, clear
+ownership semantics, and honest documentation about sharp edges.
 
-Please make sure to understand our [Code of Conduct](./CODE_OF_CONDUCT.md).
+`Ratomic::Map` is the current priority: a Ruby-facing concurrent Hash powered by
+DashMap, with atomic per-key operations designed for real Ractor workloads.
 
-After changing code, you can give it a spin with:
+## Requirements
 
-```bash
-rake
-```
-
-This should compile the Rust code and run all tests.
-The test suite writes a SimpleCov report to `coverage/index.html` so you can see which Ruby wrapper paths are covered.
+- Ruby 4.0 or newer
+- Bundler
+- Rust toolchain when building the native extension from source
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add Ratomic to your application's Gemfile:
 
 ```bash
 bundle add ratomic
 ```
 
-TODO: We have not released a gem yet.
+Then require it from Ruby:
 
-## Usage
+```ruby
+require "ratomic"
+```
 
-Ratomic provides several useful Ractor-safe structures.
-Note the APIs available are frequently very limited compared to Ruby's broad API.
+## Documentation
+
+API documentation is published to GitHub Pages:
+
+- [mperham.github.io/ratomic](https://mperham.github.io/ratomic/)
+
+## Examples And Benchmarks
+
+- [`redis_poc`](./redis_poc) contains local Redis scripts that exercise
+  `Ratomic::Map`, `Ratomic::Counter`, and `Ratomic::Pool` under Thread and
+  Ractor workloads.
+- The [`cdc-parallel` Ratomic benchmark][cdc-parallel-ratomic] demonstrates
+  Ractor workers updating shared CDC processing metrics through `Ratomic::Map`
+  and `Ratomic::Counter`.
+
+## Usage
 
-These structures are designed for use as class-level constants so they can be shared by numerous Ractors.
+Ratomic provides two safety models:
 
-Ratomic has two different safety models:
+- `Counter`, `Map`, and `Queue` are shared concurrent structures.
+- `Pool` transfers ownership of mutable objects between Ractors.
 
-* `Counter`, `Map`, and `Queue` are shared concurrent structures.
-* `Pool` transfers ownership of mutable objects between Ractors.
+That distinction matters. A mutable pooled object is not shared by multiple Ractors
+at the same time. It is moved to the caller on checkout and moved back to the pool
+on checkin.
 
-That distinction matters. A mutable pooled object is not shared by multiple Ractors at the same time. It is moved to the caller on checkout and moved back to the pool on checkin.
+These structures are designed for use as class-level constants so they can be
+shared by many Ractors.
 
 ### `Ratomic::Counter`
 
+`Ratomic::Counter` is a Ractor-shareable atomic counter.
+
 ```ruby
-c = Ratomic::Counter.new
-c.read # => 0
-c.inc
-c.inc(5)
-c.dec(1)
-c.dec
-c.read # => 4
-c.to_i # => 4
-c.zero? # => false
+counter = Ratomic::Counter.new
+
+counter.read # => 0
+counter.increment(1)
+counter.increment(5)
+counter.decrement(1)
+counter.decrement(1)
+
+counter.read # => 4
+counter.to_i # => 4
+counter.zero? # => false
 ```
 
-### `Ratomic::Pool`
+### `Ratomic::Map`
 
-A Ractor-safe object pool:
+`Ratomic::Map` is a Ractor-safe concurrent Hash backed by Rust's DashMap. It is
+not a full `Hash` replacement; iteration and arbitrary mutable object borrowing
+are intentionally absent.
 
 ```ruby
-POOL = Ratomic::Pool.new(5, 1.0) { [] }
-POOL.with do |obj|
-  # do something with obj
-  obj << "work"
-end
+OFFSETS = Ratomic::Map.new
+
+OFFSETS["mike"] = 123
+OFFSETS["mike"] # => 123
+OFFSETS.key?("mike") # => true
+OFFSETS.fetch("missing", 0) # => 0
+
+OFFSETS.fetch_or_store("count") { 0 } # => 0
+OFFSETS.compute("mike") { |value| value + 1 } # => 124
+OFFSETS.upsert("mike", 1) { |value| value + 1 } # => 125
+OFFSETS.fetch_and_modify("mike") { |value| value + 1 }
+
+OFFSETS.delete("mike") # => 126
+OFFSETS.length
+OFFSETS.empty?
+OFFSETS.clear
 ```
 
-`Pool` is an ownership-transfer pool for mutable Ruby objects. It uses Ruby 4's `Ractor::Port` and `move: true` semantics so only one Ractor owns a checked-out object at a time.
+`Map` also includes atomic convenience methods for common bucket patterns:
 
-This design addresses [issue #5](https://github.com/mperham/ratomic/issues/5), where using a pooled object after `with` could lead to memory corruption or a process crash. The fix is Rust-inspired ownership transfer, not Rust's full borrow checker: Ruby enforces the boundary dynamically at runtime through Ractor move semantics, while Rust enforces ownership and borrowing statically at compile time.
+```ruby
+counts = Ratomic::Map.new
+counts.increment("jobs") # => 1
+counts.decrement("jobs") # => 0
+
+groups = Ratomic::Map.new
+groups.append("jobs", "import") # => ["import"]
+groups.add_to_set("workers", "alpha") # => #<Set: {"alpha"}>
+```
 
-In that model:
+### `Ratomic::Queue`
+
+`Ratomic::Queue` is a Ractor-shareable multi-producer, multi-consumer queue.
 
-* the Rust owner maps to the Ractor that currently checked out the pooled object
-* the Rust move maps to `Ractor::Port#send(..., move: true)`
-* Rust's "cannot use after move" rule maps to Ruby raising `Ractor::MovedError`
-* borrowing is not modeled; `Pool` transfers ownership instead of lending references
+```ruby
+queue = Ratomic::Queue.new(128)
+
+queue.push("hello")
+queue << "world"
+
+queue.size # => 2
+queue.empty? # => false
+queue.peek # => "hello"
+queue.pop # => "hello"
+queue.pop # => "world"
+queue.empty? # => true
+```
+
+The `.new(capacity)` method initializes the queue with a fixed-size buffer.
+Capacity must be at least `1` and at most `2**20`. Non-power-of-two capacities
+are supported exactly.
+
+Since `Ratomic::Queue` is concurrent, `size`, `empty?`, and `peek` are
+moment-in-time observations. Their results may already be stale by the time your
+code uses them.
+
+### `Ratomic::Pool`
+
+`Ratomic::Pool` is a Ractor-safe ownership-transfer pool for mutable Ruby objects.
+
+```ruby
+BUFFERS = Ratomic::Pool.new(5, 1.0) { [] }
+
+BUFFERS.with do |buffer|
+  buffer.clear
+  buffer << "work"
+end
+```
+
+`Pool` uses Ruby 4's `Ractor::Port` and `move: true` semantics so only one
+Ractor owns a checked-out object at a time.
 
 When an object is checked out:
 
-* the pool moves the object to the caller
-* the caller can mutate the object while it owns it
-* the pool cannot hand that object to another Ractor until it is checked in
+- the pool moves the object to the caller
+- the caller can mutate the object while it owns it
+- the pool cannot hand that object to another Ractor until it is checked in
 
 When an object is checked in:
 
-* ownership moves back to the pool
-* stale references held by the caller become moved objects
-* using those stale references raises `Ractor::MovedError`
+- ownership moves back to the pool
+- stale references held by the caller become moved objects
+- using those stale references raises `Ractor::MovedError`
 
-This means incorrect usage fails at the Ruby object-ownership boundary rather than allowing two Ractors to mutate the same object concurrently.
+This means incorrect usage fails at the Ruby object-ownership boundary rather
+than allowing two Ractors to mutate the same object concurrently.
 
 ```ruby
 outside = nil
 
-POOL.with do |obj|
-  outside = obj
-  obj << "inside"
+BUFFERS.with do |buffer|
+  outside = buffer
+  buffer << "inside"
 end
 
 outside << "outside"
 # raises Ractor::MovedError
 ```
 
-The lower-level `Ratomic::FixedSizeObjectPool` native class may still exist, but `Ratomic::Pool` does not inherit from it. The public `Pool` API is implemented in Ruby so it can use Ruby's Ractor ownership primitives directly.
-
-Manual checkout/checkin is also supported:
+Manual checkout and checkin are also supported:
 
 ```ruby
-obj = POOL.checkout
-raise "pool checkout timeout" if obj.nil?
+buffer = BUFFERS.checkout
+raise "pool checkout timeout" if buffer.nil?
 
 begin
-  obj << "manual work"
+  buffer << "manual work"
 ensure
-  POOL.checkin(obj) if obj
+  BUFFERS.checkin(buffer) if buffer
 end
 ```
 
-`checkout` returns `nil` if no pooled object becomes available before the configured timeout. `with` raises `Ratomic::Error` in that case.
+`checkout` returns `nil` if no pooled object becomes available before the
+configured timeout. `with` raises `Ratomic::Error` in that case.
 
-### `Ratomic::Map`
+`Pool` uses ownership transfer, not Rust's full borrow checker:
 
-A Ractor-safe map/hash structure:
+- the Rust owner maps to the Ractor that currently checked out the pooled object
+- the Rust move maps to `Ractor::Port#send(..., move: true)`
+- Rust's "cannot use after move" rule maps to Ruby raising `Ractor::MovedError`
+- borrowing is not modeled; `Pool` transfers ownership instead of lending references
 
-```ruby
-HASH = Ratomic::Map.new
-HASH["mike"] = 123
-HASH["mike"] # => 123
-HASH.fetch_and_modify("mike") { |value| value + 1 }
-HASH.length
-HASH.empty?
-HASH.clear
-```
+This design addresses [issue #5](https://github.com/mperham/ratomic/issues/5),
+where using a pooled object after `with` could lead to memory corruption or a
+process crash.
 
-### `Ratomic::Queue`
+The lower-level `Ratomic::FixedSizeObjectPool` native class may still exist, but
+`Ratomic::Pool` does not inherit from it. The public `Pool` API is implemented
+in Ruby so it can use Ruby's Ractor ownership primitives directly.
 
-A multi-producer, multi-consumer queue.
+## Contributing
 
-```ruby
-q = Ratomic::Queue.new(128)
+Please read the [Code of Conduct](./CODE_OF_CONDUCT.md) before contributing.
 
-q.push("hello")
-q << "world"
+After changing code, run:
 
-q.size     # => 2
-q.empty?   # => false
-q.peek     # => "hello"
-item = q.pop # => "hello"
-item = q.pop # => "world"
-q.empty?   # => true
+```bash
+rake
 ```
-The `.new(capacity)` method initializes the queue with a fixed-size buffer. The capacity must be greater than or equal to 1 and less than or equal to 2<sup>20</sup>.
-
-Values that are not a power of two are rounded up to the nearest greater power of two, which enables efficient indexing and wrap-around calculations in the underlying buffer.
 
-Since `Ratomic::Queue` is a concurrent queue, the `size`, `empty?`, and `peek` methods provide only a best-effort guess — the values they return might be stale or incorrect.
+This compiles the Rust code and runs the test suite. The test suite writes a
+SimpleCov report to `coverage/index.html` for the Ruby wrapper paths.
 
 ## Thanks
 
-[Ilya Bylich](https://github.com/iliabylich) wrote and documented his original research at [Ruby, Ractors, and Lock-free Data Structures/](https://iliabylich.github.io/ruby-ractors-and-lock-free-data-structures/).
-Thank you for your impressive work, Ilya!
+[Ilya Bylich](https://github.com/iliabylich) wrote and documented his original
+research at [Ruby, Ractors, and Lock-free Data Structures][ractor-research].
 
-This repo is further research into the usability and limitations of Ractor-friendly structures in Ruby code and gems.
+This repo continues that research into the usability and limitations of
+Ractor-friendly structures in Ruby code and gems.
 
 ## License
 
 [MIT License](https://opensource.org/licenses/MIT).
+
+[cdc-parallel-ratomic]: https://github.com/kanutocd/cdc-parallel/blob/main/benchmark/RATOMIC.md
+[ractor-research]: https://iliabylich.github.io/ruby-ractors-and-lock-free-data-structures/

data/ext/ratomic/src/hashmap.rs

@@ -1,3 +1,4 @@
+use dashmap::mapref::entry::Entry;
 use rb_sys::{rb_eql, rb_hash, VALUE};
 
 #[derive(Debug)]
@@ -18,11 +19,11 @@ impl std::hash::Hash for RubyHashEql {
     }
 }
 
-pub struct ConcurrentHashMap {
+pub struct MapStore {
     map: dashmap::DashMap<RubyHashEql, VALUE>,
 }
 
-impl ConcurrentHashMap {
+impl MapStore {
     pub fn new() -> Self {
         Self {
             map: dashmap::DashMap::new(),
@@ -33,10 +34,18 @@ impl ConcurrentHashMap {
         self.map.get(&RubyHashEql(key)).map(|v| *v)
     }
 
+    pub fn contains_key(&self, key: VALUE) -> bool {
+        self.map.contains_key(&RubyHashEql(key))
+    }
+
     pub fn set(&self, key: VALUE, value: VALUE) {
         self.map.insert(RubyHashEql(key), value);
     }
 
+    pub fn delete(&self, key: VALUE) -> Option<VALUE> {
+        self.map.remove(&RubyHashEql(key)).map(|(_, value)| value)
+    }
+
     pub fn clear(&self) {
         self.map.clear()
     }
@@ -52,6 +61,73 @@ impl ConcurrentHashMap {
         self.map.alter(&RubyHashEql(key), |_, value| f(value));
     }
 
+    pub fn compute<F, E>(&self, key: VALUE, missing: VALUE, f: F) -> Result<VALUE, E>
+    where
+        F: FnOnce(VALUE) -> Result<VALUE, E>,
+    {
+        match self.map.entry(RubyHashEql(key)) {
+            Entry::Occupied(mut entry) => {
+                let new_value = f(*entry.get())?;
+                entry.insert(new_value);
+                Ok(new_value)
+            }
+            Entry::Vacant(entry) => {
+                let new_value = f(missing)?;
+                entry.insert(new_value);
+                Ok(new_value)
+            }
+        }
+    }
+
+    pub fn update<F, E>(&self, key: VALUE, f: F) -> Result<VALUE, E>
+    where
+        F: FnOnce(Option<VALUE>) -> Result<VALUE, E>,
+    {
+        match self.map.entry(RubyHashEql(key)) {
+            Entry::Occupied(mut entry) => {
+                let new_value = f(Some(*entry.get()))?;
+                entry.insert(new_value);
+                Ok(new_value)
+            }
+            Entry::Vacant(entry) => {
+                let new_value = f(None)?;
+                entry.insert(new_value);
+                Ok(new_value)
+            }
+        }
+    }
+
+    pub fn fetch_or_store<F, E>(&self, key: VALUE, f: F) -> Result<VALUE, E>
+    where
+        F: FnOnce() -> Result<VALUE, E>,
+    {
+        match self.map.entry(RubyHashEql(key)) {
+            Entry::Occupied(entry) => Ok(*entry.get()),
+            Entry::Vacant(entry) => {
+                let value = f()?;
+                entry.insert(value);
+                Ok(value)
+            }
+        }
+    }
+
+    pub fn upsert<F, E>(&self, key: VALUE, initial: VALUE, f: F) -> Result<VALUE, E>
+    where
+        F: FnOnce(VALUE) -> Result<VALUE, E>,
+    {
+        match self.map.entry(RubyHashEql(key)) {
+            Entry::Occupied(mut entry) => {
+                let new_value = f(*entry.get())?;
+                entry.insert(new_value);
+                Ok(new_value)
+            }
+            Entry::Vacant(entry) => {
+                entry.insert(initial);
+                Ok(initial)
+            }
+        }
+    }
+
     pub fn mark<F>(&self, f: F)
     where
         F: Fn(VALUE),
@@ -63,7 +139,7 @@ impl ConcurrentHashMap {
     }
 }
 
-impl Default for ConcurrentHashMap {
+impl Default for MapStore {
     fn default() -> Self {
         Self::new()
     }