ratomic 0.2.0-aarch64-linux → 0.3.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4daad186ea78dee734a51a45058796088a136dc4581b2aca8069c1b537d18700
-  data.tar.gz: 16eb668ab1e0a204fdf9d88d8e947d401782b1aa6662e0af6677a34d98e4e98a
+  metadata.gz: 2a9a21c9f48aee3bcf45cf6ff9b4fdb5c387162c09d320498dfc572279ebcefe
+  data.tar.gz: 8f24205fefa107afedd669aaa2772012339195669cf8c6c95fdea6c2e431cc84
 SHA512:
-  metadata.gz: 7d2f7ea9508fe6990a5b4da2f5309754da78b8a46193039155e9a9326a5411c32285c15dc0440bd159cbc1a50629e4765d3ad394fd25a497be68557e4f1fc827
-  data.tar.gz: 26938fc5cd19ce5a71fdf70b156e6a945eaf151e091c70bca8ee95cd543bccd89111eea221992b00383113dc1829ffe7a7e988480267fe36250ac8143e9206bf
+  metadata.gz: 15180c7c0f215d43c0eedfa12187d2e3b8c868bb1a24c92cf38f163864ea7a0ec3c5e1589e0fe9fe7d23a48ccfb40a039f6bd687e5ddce2d37d25d1c559efae9
+  data.tar.gz: 1e5aa4f5be6fb3af99a838e12cc6bb787787f5e22194cc72b27e4602eacc02cbbfd97740bed484c31978957c23e94fd78355773428a655a7f16474c1d5bb619c

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/lib/ratomic/counter.rb

@@ -1,8 +1,38 @@
 # frozen_string_literal: true
 
 module Ratomic
-  # Ruby convenience methods for {Counter}.
-  module CounterMethods
+  # A Ractor-shareable atomic counter.
+  #
+  # Counter stores an unsigned integer in native Rust atomics and can be shared
+  # safely across Ractors.
+  #
+  # @example Count work across Ractors
+  #   counter = Ratomic::Counter.new
+  #   counter.increment(1)
+  #   counter.read # => 1
+  #
+  # @!method self.new
+  #   Create a counter initialized to zero.
+  #
+  #   @return [Ratomic::Counter]
+  #
+  # @!method read
+  #   Read the current counter value.
+  #
+  #   @return [Integer]
+  #
+  # @!method increment(amt)
+  #   Increment the counter by +amt+.
+  #
+  #   @param amt [Integer]
+  #   @return [void]
+  #
+  # @!method decrement(amt)
+  #   Decrement the counter by +amt+.
+  #
+  #   @param amt [Integer]
+  #   @return [void]
+  class Counter
     # Read the current counter value.
     #
     # @return [Integer]
@@ -23,29 +53,5 @@ module Ratomic
     def zero?
       read.zero?
     end
-
-    # Increment the counter.
-    #
-    # @param amt [Integer] amount to add
-    # @raise [ArgumentError] if +amt+ is negative
-    # @return [void]
-    def inc(amt = 1)
-      raise ArgumentError, "amount must be positive: #{amt}" if amt.negative?
-
-      increment(amt)
-    end
-
-    # Decrement the counter.
-    #
-    # @param amt [Integer] amount to subtract
-    # @raise [ArgumentError] if +amt+ is negative
-    # @return [void]
-    def dec(amt = 1)
-      raise ArgumentError, "amount must be positive: #{amt}" if amt.negative?
-
-      decrement(amt)
-    end
   end
-
-  Counter.prepend(CounterMethods)
 end

data/lib/ratomic/map.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module Ratomic
-  # A Ractor-shareable concurrent map.
+  # A Ractor-shareable concurrent Hash backed by Rust's DashMap.
   #
-  # Map is a public alias for the native ConcurrentHashMap class. It is suitable
-  # for runtime state with shareable keys and values that are safe to access
-  # from multiple Ractors, such as counters or immutable offsets.
+  # Map gives Ruby code a small, Ruby-shaped API over DashMap's concurrent
+  # storage. It is suitable for runtime state with shareable keys and values
+  # that are safe to access from multiple Ractors, such as integer counters or
+  # immutable offsets.
   #
   # This is not a full Hash replacement. Iteration and arbitrary mutable object
   # borrowing are intentionally absent.
@@ -14,10 +15,171 @@ module Ratomic
   #   OFFSETS = Ratomic::Map.new
   #   OFFSETS[:source_a] = 42
   #   OFFSETS[:source_a] # => 42
-  Map = ConcurrentHashMap
-
-  # Ruby convenience methods for {Map}.
-  module MapMethods
+  #
+  # @!method get(key)
+  #   Read a value by +key+.
+  #
+  #   Missing keys return nil, so use #key? or #fetch when stored nil values
+  #   need to be distinguished from missing entries.
+  #
+  #   @param key [Object]
+  #   @return [Object, nil]
+  #
+  # @!method set(key, value)
+  #   Set a value for +key+.
+  #
+  #   @param key [Object]
+  #   @param value [Object]
+  #   @return [void]
+  #
+  # @!method key?(key)
+  #   Check whether +key+ currently exists in the map.
+  #
+  #   Unlike #get and #[], this distinguishes missing keys from stored nil
+  #   values.
+  #
+  #   @param key [Object]
+  #   @return [Boolean]
+  #
+  # @!method delete(key)
+  #   Remove +key+ and return its previous value.
+  #
+  #   Missing keys return nil. Stored nil values also return nil; use #key?
+  #   before deleting if that distinction matters.
+  #
+  #   @param key [Object]
+  #   @return [Object, nil]
+  #
+  # @!method clear
+  #   Remove all entries from the map.
+  #
+  #   @return [void]
+  #
+  # @!method size
+  #   Return the current number of entries.
+  #
+  #   Since this is a concurrent map, the value is a moment-in-time observation.
+  #
+  #   @return [Integer]
+  #
+  # @!method fetch_and_modify(key)
+  #   Replace the existing value for +key+ with the block return value.
+  #
+  #   TODO: Revisit this name once the Map API settles. Prefer public method
+  #   names that stay as close as possible to Ruby Hash semantics.
+  #
+  #   The key must already exist. The operation is atomic for the key. The block
+  #   runs while the map entry is locked, so avoid using this method for
+  #   Ractor-hot loops or calling back into the same map from inside the block.
+  #   If the block raises, the previous value is preserved.
+  #
+  #   @param key [Object]
+  #   @yieldparam value [Object] current value
+  #   @return [void]
+  #   @raise [LocalJumpError] if no block is given
+  #   @raise [Exception] any exception raised by the block
+  #
+  # @!method compute(key)
+  #   Atomically compute and store a value for +key+.
+  #
+  #   If +key+ exists, yields the current value. If +key+ is missing, yields
+  #   nil. The block return value is stored and returned.
+  #
+  #   The operation is atomic for the key. The block runs while the map entry is
+  #   locked, so avoid using this method for Ractor-hot loops or calling back
+  #   into the same map from inside the block. Prefer native update helpers such
+  #   as #increment when they fit the workflow.
+  #
+  #   If the block raises, the previous value is preserved. If the key was
+  #   missing, no entry is inserted.
+  #
+  #   @param key [Object]
+  #   @yieldparam value [Object, nil] current value, or nil if missing
+  #   @return [Object] the newly stored value
+  #   @raise [LocalJumpError] if no block is given
+  #   @raise [Exception] any exception raised by the block
+  #
+  # @!method fetch_or_store(key)
+  #   Return the existing value for +key+, or atomically store the block result.
+  #
+  #   If +key+ exists, returns the current value and does not yield. If +key+
+  #   is missing, yields once, stores the block return value, and returns it.
+  #
+  #   The operation is atomic for the key. Under contention, only one stored
+  #   value wins for a missing key. The block runs while the map entry is locked,
+  #   so avoid using this method for Ractor-hot loops or calling back into the
+  #   same map from inside the block.
+  #
+  #   If the block raises, no entry is inserted.
+  #
+  #   @param key [Object]
+  #   @return [Object] the existing or newly stored value
+  #   @raise [LocalJumpError] if no block is given
+  #   @raise [Exception] any exception raised by the block
+  #
+  # @!method upsert(key, initial)
+  #   Atomically insert +initial+ for a missing key, or update an existing value.
+  #
+  #   If +key+ is missing, stores and returns +initial+ without yielding. If
+  #   +key+ exists, yields the current value, stores the block return value, and
+  #   returns it.
+  #
+  #   The operation is atomic for the key. The block runs while the map entry is
+  #   locked, so avoid using this method for Ractor-hot loops or calling back
+  #   into the same map from inside the block. Prefer native update helpers such
+  #   as #increment when they fit the workflow.
+  #
+  #   If the block raises, the previous value is preserved.
+  #
+  #   @param key [Object]
+  #   @param initial [Object]
+  #   @yieldparam value [Object, nil] current value
+  #   @return [Object] the inserted or newly stored value
+  #   @raise [LocalJumpError] if no block is given
+  #   @raise [Exception] any exception raised by the block
+  #
+  # @!method increment(key, by = 1)
+  #   Atomically increment the numeric value for +key+.
+  #
+  #   Missing keys start at zero. Existing non-numeric values raise TypeError
+  #   and are left unchanged. This uses a native update path and is the preferred
+  #   counter primitive for Ractor-heavy workloads.
+  #
+  #   @param key [Object]
+  #   @param by [Numeric]
+  #   @return [Numeric] the newly stored value
+  #   @raise [TypeError] if +by+ or the existing value is not numeric
+  #
+  # @!method decrement(key, by = 1)
+  #   Atomically decrement the numeric value for +key+.
+  #
+  #   Missing keys start at zero.
+  #
+  #   @param key [Object]
+  #   @param by [Numeric]
+  #   @return [Numeric] the newly stored value
+  #   @raise [TypeError] if +by+ or the existing value is not numeric
+  #
+  # @!method append(key, value)
+  #   Atomically append +value+ to an Array bucket for +key+.
+  #
+  #   The stored Array is replaced rather than mutated in place.
+  #
+  #   @param key [Object]
+  #   @param value [Object]
+  #   @return [Array] the newly stored frozen Array
+  #   @raise [TypeError] if the existing value is not an Array
+  #
+  # @!method add_to_set(key, value)
+  #   Atomically add +value+ to a Set bucket for +key+.
+  #
+  #   The stored Set is replaced rather than mutated in place.
+  #
+  #   @param key [Object]
+  #   @param value [Object]
+  #   @return [Set] the newly stored frozen Set
+  #   @raise [TypeError] if the existing value is not a Set
+  class Map
     # Set a value for +key+.
     #
     # @param key [Object]
@@ -37,6 +199,101 @@ module Ratomic
       get(key)
     end
 
+    # Fetch a value by +key+.
+    #
+    # Unlike #[], this distinguishes missing keys from explicit nil values.
+    #
+    # @param key [Object]
+    # @param default [Object]
+    # @yieldparam key [Object]
+    # @return [Object]
+    # @raise [KeyError] if +key+ is missing and no default or block is provided
+    def fetch(key, default = UNDEFINED)
+      return get(key) if key?(key)
+      return yield key if block_given?
+      return default unless default.equal?(UNDEFINED)
+
+      raise KeyError, "key not found: #{key.inspect}"
+    end
+
+    # Atomically increment the numeric value for +key+.
+    #
+    # Missing keys start at zero. Existing non-numeric values raise TypeError
+    # and are left unchanged. This uses a native update path and is the preferred
+    # counter primitive for Ractor-heavy workloads.
+    #
+    # @param key [Object]
+    # @param by [Numeric]
+    # @return [Numeric] the newly stored value
+    # @raise [TypeError] if +by+ or the existing value is not numeric
+    def increment(key, by = 1)
+      raise TypeError, "amount must be numeric: #{by.inspect}" unless by.is_a?(Numeric)
+
+      __increment_numeric(key, by)
+    end
+
+    # Atomically decrement the numeric value for +key+.
+    #
+    # Missing keys start at zero.
+    #
+    # @param key [Object]
+    # @param by [Numeric]
+    # @return [Numeric] the newly stored value
+    # @raise [TypeError] if +by+ or the existing value is not numeric
+    def decrement(key, by = 1)
+      raise TypeError, "amount must be numeric: #{by.inspect}" unless by.is_a?(Numeric)
+
+      increment(key, -by)
+    end
+
+    # Atomically append +value+ to an Array bucket for +key+.
+    #
+    # The stored Array is replaced rather than mutated in place.
+    #
+    # @param key [Object]
+    # @param value [Object]
+    # @return [Array] the newly stored frozen Array
+    # @raise [TypeError] if the existing value is not an Array
+    def append(key, value)
+      missing = !key?(key)
+      compute(key) do |old_value|
+        if old_value.nil? && missing
+          [value].freeze
+        else
+          unless old_value.is_a?(Array)
+            raise TypeError,
+                  "existing value for #{key.inspect} must be an Array: #{old_value.inspect}"
+          end
+
+          (old_value + [value]).freeze
+        end
+      end
+    end
+
+    # Atomically add +value+ to a Set bucket for +key+.
+    #
+    # The stored Set is replaced rather than mutated in place.
+    #
+    # @param key [Object]
+    # @param value [Object]
+    # @return [Set] the newly stored frozen Set
+    # @raise [TypeError] if the existing value is not a Set
+    def add_to_set(key, value)
+      missing = !key?(key)
+      compute(key) do |old_value|
+        if old_value.nil? && missing
+          Set[value].freeze
+        else
+          unless old_value.is_a?(Set)
+            raise TypeError,
+                  "existing value for #{key.inspect} must be a Set: #{old_value.inspect}"
+          end
+
+          (old_value | [value]).freeze
+        end
+      end
+    end
+
     # Alias for #size.
     #
     # @return [Integer]
@@ -50,7 +307,14 @@ module Ratomic
     def empty?
       size.zero?
     end
-  end
 
-  ConcurrentHashMap.prepend(MapMethods)
+    # Alias for #key?.
+    #
+    # @param key [Object]
+    # @return [Boolean]
+    def include?(key)
+      key?(key)
+    end
+    alias member? include?
+  end
 end

data/lib/ratomic/pool.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Ratomic
   # A Ractor-safe ownership-transfer pool for mutable Ruby objects.
   #
@@ -73,6 +75,20 @@ module Ratomic
       nil
     end
 
+    # Stop the private coordinator Ractor.
+    #
+    # This is primarily useful for tests and short-lived scripts. A closed pool
+    # should not be used for further checkout/checkin operations.
+    #
+    # @return [nil]
+    def close
+      @control << [:shutdown]
+      @control.value
+      nil
+    rescue Ractor::ClosedError, Ractor::Error
+      nil
+    end
+
     # Checkout an object, yield it, then move it back to the pool.
     #
     # This is the preferred API because it guarantees checkin through an ensure
@@ -101,7 +117,7 @@ module Ratomic
 
       loop do
         command, *args = Ractor.receive
-        handle_command(command, args, available, waiting)
+        break if handle_command(command, args, available, waiting) == :shutdown
       end
     end
     private_class_method :run_control_loop
@@ -114,6 +130,8 @@ module Ratomic
         handle_checkin(args.fetch(0), available, waiting)
       when :cancel
         waiting.delete(args.fetch(0))
+      when :shutdown
+        :shutdown
       end
     end
     private_class_method :handle_command

data/lib/ratomic/queue.rb

@@ -1,8 +1,64 @@
 # frozen_string_literal: true
 
 module Ratomic
-  # Ruby convenience methods for {Queue}.
-  module QueueMethods
+  # A Ractor-shareable multi-producer, multi-consumer queue.
+  #
+  # Queue stores Ruby objects in a fixed-size native ring buffer. Push blocks
+  # when the queue is full; pop blocks when the queue is empty.
+  #
+  # @example Push and pop work
+  #   queue = Ratomic::Queue.new(128)
+  #   queue << "job"
+  #   queue.pop # => "job"
+  #
+  # @!method self.new(capacity)
+  #   Create a queue with a fixed capacity.
+  #
+  #   @param capacity [Integer]
+  #   @return [Ratomic::Queue]
+  #   @raise [ArgumentError] if capacity is outside the supported range
+  #   @raise [TypeError] if capacity is not an Integer
+  #
+  # @!method push(item)
+  #   Push an item, blocking until space is available.
+  #
+  #   @param item [Object]
+  #   @return [void]
+  #
+  # @!method pop
+  #   Pop an item, blocking until one is available.
+  #
+  #   @return [Object]
+  #
+  # @!method peek
+  #   Return the next item without removing it.
+  #
+  #   Since this is a concurrent queue, the value is a moment-in-time
+  #   observation.
+  #
+  #   @return [Object, nil]
+  #
+  # @!method empty?
+  #   Check whether the queue currently appears empty.
+  #
+  #   Since this is a concurrent queue, the value is a moment-in-time
+  #   observation.
+  #
+  #   @return [Boolean]
+  #
+  # @!method size
+  #   Return the current queue size.
+  #
+  #   Since this is a concurrent queue, the value is a moment-in-time
+  #   observation.
+  #
+  #   @return [Integer]
+  #
+  # @!method length
+  #   Alias for #size.
+  #
+  #   @return [Integer]
+  class Queue
     # Push an item and return the queue for chaining.
     #
     # @param item [Object]
@@ -12,6 +68,4 @@ module Ratomic
       self
     end
   end
-
-  Queue.prepend(QueueMethods)
 end

data/lib/ratomic/version.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Ratomic provides Ractor-friendly mutable data structures backed by native
+# Rust concurrency primitives.
+#
+# The public API currently includes {Counter}, {Map}, {Queue}, and {Pool}.
 module Ratomic
-  VERSION = "0.2.0"
+  # Current gem version.
+  VERSION = "0.3.0"
 end

data/lib/ratomic.rb

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 
-require "timeout"
-
-require_relative "ratomic/version"
-require_relative "ratomic/ratomic"
-require_relative "ratomic/counter"
-require_relative "ratomic/undefined"
-require_relative "ratomic/pool"
-require_relative "ratomic/map"
-require_relative "ratomic/queue"
+require "ratomic/ratomic"
+require "ratomic/version"
 
 module Ratomic
-  # Base error for Ratomic-specific runtime failures.
   class Error < StandardError; end
 end
+
+require "ratomic/undefined"
+require "ratomic/counter"
+require "ratomic/map"
+require "ratomic/queue"
+require "ratomic/pool"

data/ratomic.gemspec

@@ -9,15 +9,16 @@ Gem::Specification.new do |spec|
   spec.email = ["mike@perham.net"]
   spec.metadata["maintainers"] = "Ken C. Demanawa"
 
-  spec.summary = "Mutable data structures for Ractors"
-  spec.description = spec.summary
-  spec.homepage = "https://github.com/mperham/ratomic"
+  spec.summary = "Ractor-safe concurrent data structures for Ruby"
+  spec.description = "Ractor-safe counters, maps, queues, and ownership-transfer pools " \
+                     "backed by native Rust concurrency primitives."
+  spec.homepage = "https://mperham.github.io/ratomic"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 4.0.0"
+  spec.required_ruby_version = [">= 4.0", "< 4.1.dev"]
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/mperham/ratomic"
-  spec.metadata["changelog_uri"] = "https://github.com/mperham/ratomic"
+  spec.metadata["changelog_uri"] = "https://github.com/mperham/ratomic/blob/trunk/CHANGELOG.md"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   # Specify which files should be added to the gem when it is released.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratomic
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: aarch64-linux
 authors:
 - Mike Perham
@@ -9,9 +9,10 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies: []
-description: Mutable data structures for Ractors
+description: Ractor-safe counters, maps, queues, and ownership-transfer pools backed
+  by native Rust concurrency primitives.
 email:
 - mike@perham.net
 executables: []
@@ -35,14 +36,14 @@ files:
 - lib/ratomic/undefined.rb
 - lib/ratomic/version.rb
 - ratomic.gemspec
-homepage: https://github.com/mperham/ratomic
+homepage: https://mperham.github.io/ratomic
 licenses:
 - MIT
 metadata:
   maintainers: Ken C. Demanawa
-  homepage_uri: https://github.com/mperham/ratomic
+  homepage_uri: https://mperham.github.io/ratomic
   source_code_uri: https://github.com/mperham/ratomic
-  changelog_uri: https://github.com/mperham/ratomic
+  changelog_uri: https://github.com/mperham/ratomic/blob/trunk/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
@@ -65,5 +66,5 @@ requirements: []
 rubygems_version: 3.5.23
 signing_key: 
 specification_version: 4
-summary: Mutable data structures for Ractors
+summary: Ractor-safe concurrent data structures for Ruby
 test_files: []