ratomic 0.2.1-x86_64-linux → 0.3.1-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b342a88351f8930ad904074de6a0210e1e8ed7523dbff36e5dc9c981b7450e58
-  data.tar.gz: 4bc6e2495415a993fd631112d3497c32564e550f2cb4aeee1990942b28ba8449
+  metadata.gz: f55637af7bce6a3ba2f1a70daae8f830b16ef51398f62a5bcb28e936b3ae57be
+  data.tar.gz: 8c31f7d92dcf197a3b0003fce4c544180680f21238537fe3f1ef724e93181f09
 SHA512:
-  metadata.gz: 4a9c078d8980fc788eba711420e596660e7b39c5d4031371aec30669a7db36f9aa35c8b5368fa4b68d2d4b716b940a52a120be2719282e4b75e68ef807522292
-  data.tar.gz: bb13dad126ea4b73358710a6bfae818f304287f9a1d3ef5de1100a664534abe1b016d2851d5dca06c7e759899cecb17a9437f305597dd5be9fde34754e97f908
+  metadata.gz: 12d4bbf098654e22c40c930403ce1aa066f3eba62c02fbd6a16eb97a562d6548db70125f387b90ed78d82f7a15ac46f207cd6aa15fdb5abfbafb5cadbfc10f6e
+  data.tar.gz: cb5609b996dd520b5e901462cb4ff8da87fa25c583fbdbf2ce8f61e2e31e6e01ab17e80bc5552384b96bcc1340f36eb67da03f76c083c1272a8223405aa6f1c6

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.3.1] - 2026-06-05
+
+- Realign `Counter`, `Map`, and `Queue` return semantics with Ruby conventions.
+- Expand YARD comments across the public API to keep full documentation coverage.
+- Move the top-level module docs to the gem entrypoint for a cleaner load path.
+
+## [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.

data/README.md

@@ -2,180 +2,247 @@
 
 [![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)
-[![Coverage Status](https://codecov.io/gh/mperham/ratomic/branch/main/graph/badge.svg)](https://codecov.io/gh/mperham/ratomic)
 [![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)
 
+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. `Pool` uses Ruby Ractor ownership-transfer primitives instead of the native Rust path.
 
-Ratomic provides mutable data structures for use with Ruby's Ractors.
-This allows Ruby code to scale beyond the infamous GVL.
+## Project Direction
 
-# HELP WANTED!
+Ratomic focuses on practical Ractor-safe primitives with a small API surface, clear
+ownership semantics, and honest documentation about sharp edges.
 
-> 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.
+`Ratomic::Map` is the current priority: a Ruby-facing concurrent Hash powered by
+DashMap, with atomic per-key operations designed for real Ractor workloads.
 
-## How to contribute
+## Requirements
 
-Please make sure to understand our [Code of Conduct](./CODE_OF_CONDUCT.md).
+- Ruby 4.0 or newer
+- Bundler
+- Rust toolchain when building the native extension from source
 
-After changing code, you can give it a spin with:
+## Installation
+
+Add Ratomic to your application's Gemfile:
 
 ```bash
-rake
+bundle add ratomic
 ```
 
-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.
+Then require it from Ruby:
 
-## Installation
+```ruby
+require "ratomic"
+```
 
-Install the gem and add to the application's Gemfile by executing:
+## Documentation
 
-```bash
-bundle add ratomic
-```
+API documentation is published to GitHub Pages:
 
-## Usage
+- [mperham.github.io/ratomic](https://mperham.github.io/ratomic/)
+
+## Examples And Benchmarks
 
-Ratomic provides several useful Ractor-safe structures.
-Note the APIs available are frequently very limited compared to Ruby's broad API.
+- [`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`.
 
-These structures are designed for use as class-level constants so they can be shared by numerous Ractors.
+## Usage
 
-Ratomic has two different safety models:
+Ratomic provides two 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
+```
+
+`Map` also includes atomic convenience methods for common bucket patterns:
+
+```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"}>
 ```
 
-`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.
+### `Ratomic::Queue`
+
+`Ratomic::Queue` is a Ractor-shareable multi-producer, multi-consumer queue.
 
-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
+queue = Ratomic::Queue.new(128)
 
-In that model:
+queue.push("hello")
+queue << "world"
 
-* 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
+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,51 +1,57 @@
 # 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) # => 1
+  #   counter.read # => 1
+  #
+  # @!method self.new
+  #   Create a counter initialized to zero.
+  #
+  #   @return [Ratomic::Counter] a new shareable counter
+  #
+  # @!method read
+  #   Read the current counter value.
+  #
+  #   @return [Integer] the current counter value
+  #
+  # @!method increment(amt)
+  #   Increment the counter by +amt+.
+  #
+  #   @param amt [Integer] amount to add to the counter
+  #   @return [Integer] the updated counter value
+  #
+  # @!method decrement(amt)
+  #   Decrement the counter by +amt+.
+  #
+  #   @param amt [Integer] amount to subtract from the counter
+  #   @return [Integer] the updated counter value
+  class Counter
     # Read the current counter value.
     #
-    # @return [Integer]
+    # @return [Integer] the current counter value
     def value
       read
     end
 
     # Coerce the counter to an Integer snapshot.
     #
-    # @return [Integer]
+    # @return [Integer] the current counter value
     def to_i
       read
     end
 
     # Check whether the current counter value is zero.
     #
-    # @return [Boolean]
+    # @return [Boolean] true when the counter currently reads zero
     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,15 +15,190 @@ 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] lookup key
+  #   @return [Object, nil] the stored value, or nil when the key is missing
+  #
+  # @!method set(key, value)
+  #   Set a value for +key+.
+  #
+  #   This is the method behind `#[]=` and follows Ruby setter semantics by
+  #   returning the assigned value.
+  #
+  #   @param key [Object] key to write
+  #   @param value [Object] value to store
+  #   @return [Object] the assigned value
+  #
+  # @!method []=(key, value)
+  #   Set a value for +key+.
+  #
+  #   In assignment form, Ruby returns the value assigned to the expression.
+  #
+  #   @param key [Object] key to write
+  #   @param value [Object] value to store
+  #   @return [Object] the assigned value
+  #
+  # @!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] lookup key
+  #   @return [Boolean] true when the key currently exists
+  #
+  # @!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] key to remove
+  #   @return [Object, nil] the previous value, or nil when the key was missing
+  #
+  # @!method clear
+  #   Remove all entries from the map.
+  #
+  #   @return [Ratomic::Map] self
+  #
+  # @!method size
+  #   Return the current number of entries.
+  #
+  #   Since this is a concurrent map, the value is a moment-in-time observation.
+  #
+  #   @return [Integer] the current number of entries
+  #
+  # @!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] key to modify in place
+  #   @yieldparam value [Object] the current stored value
+  #   @return [void] nothing useful is returned
+  #   @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] key to compute
+  #   @yieldparam value [Object, nil] the current stored value, or nil when 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] key to read or initialize
+  #   @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] key to update
+  #   @param initial [Object] value to use when the key is missing
+  #   @yieldparam value [Object, nil] the current stored value, or nil when missing
+  #   @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] counter key to increment
+  #   @param by [Numeric] amount to add
+  #   @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] counter key to decrement
+  #   @param by [Numeric] amount to subtract
+  #   @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] bucket key to append into
+  #   @param value [Object] value to append
+  #   @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] bucket key to update
+  #   @param value [Object] value to add to the set
+  #   @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]
-    # @param value [Object]
-    # @return [void]
+    # In assignment form, Ruby returns the assigned value.
+    #
+    # @param key [Object] key to write
+    # @param value [Object] value to store
+    # @return [Object] the assigned value
     def []=(key, value)
       set(key, value)
     end
@@ -31,26 +207,128 @@ module Ratomic
     #
     # Missing keys currently return nil, so storing nil is ambiguous.
     #
-    # @param key [Object]
-    # @return [Object, nil]
+    # @param key [Object] lookup key
+    # @return [Object, nil] the stored value, or nil when the key is missing
     def [](key)
       get(key)
     end
 
+    # Fetch a value by +key+.
+    #
+    # Unlike #[], this distinguishes missing keys from explicit nil values.
+    #
+    # @param key [Object] lookup key
+    # @param default [Object] fallback value to return when the key is missing
+    # @yieldparam key [Object] the missing key
+    # @return [Object] the found value, default, or block result
+    # @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] counter key to increment
+    # @param by [Numeric] amount to add
+    # @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] counter key to decrement
+    # @param by [Numeric] amount to subtract
+    # @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] bucket key to append into
+    # @param value [Object] value to append
+    # @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] bucket key to update
+    # @param value [Object] value to add to the set
+    # @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]
+    # @return [Integer] the current number of entries
     def length
       size
     end
 
     # Check whether the map currently has no entries.
     #
-    # @return [Boolean]
+    # @return [Boolean] true when the map currently has no entries
     def empty?
       size.zero?
     end
-  end
 
-  ConcurrentHashMap.prepend(MapMethods)
+    # Alias for #key?.
+    #
+    # @param key [Object] lookup key
+    # @return [Boolean] true when the key currently exists
+    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.
   #
@@ -26,9 +28,9 @@ module Ratomic
   class Pool
     # Create a pool and seed it with +size+ objects from the factory block.
     #
-    # @param size [Integer] number of pooled objects
+    # @param size [Integer] number of pooled objects to create up front
     # @param timeout [Numeric, nil] checkout timeout in seconds, or nil to wait indefinitely
-    # @yieldreturn [Object] mutable object to store in the pool
+    # @yieldreturn [Object] a mutable object to place into the pool
     # @raise [ArgumentError] if +size+ is not positive
     # @raise [LocalJumpError] if no factory block is given
     def initialize(size = 5, timeout = 1.0)
@@ -47,7 +49,7 @@ module Ratomic
     # The returned object has been moved from the pool to the caller. The caller
     # owns it until it is passed to #checkin.
     #
-    # @return [Object, nil] pooled object, or nil after timeout
+    # @return [Object, nil] the checked-out object, or nil if the timeout expires
     def checkout
       reply = Ractor::Port.new
       request_id = reply.object_id
@@ -66,8 +68,8 @@ module Ratomic
     # use the object after calling this method; Ruby raises Ractor::MovedError
     # for stale references.
     #
-    # @param object [Object] previously checked-out pooled object
-    # @return [nil]
+    # @param object [Object] the object previously checked out from the pool
+    # @return [nil] nothing useful is returned
     def checkin(object)
       @control.send([:checkin, object], move: true)
       nil
@@ -78,7 +80,7 @@ module Ratomic
     # This is primarily useful for tests and short-lived scripts. A closed pool
     # should not be used for further checkout/checkin operations.
     #
-    # @return [nil]
+    # @return [nil] nothing useful is returned
     def close
       @control << [:shutdown]
       @control.value
@@ -92,9 +94,9 @@ module Ratomic
     # This is the preferred API because it guarantees checkin through an ensure
     # block. If checkout times out, raises Ratomic::Error and does not yield.
     #
-    # @yieldparam object [Object] checked-out pooled object
+    # @yieldparam object [Object] the object checked out from the pool
     # @raise [Ratomic::Error] if checkout times out
-    # @return [Object] block return value
+    # @return [Object] the block return value
     def with
       object = checkout
       raise Ratomic::Error, "pool checkout timeout" if object.nil?

data/lib/ratomic/queue.rb

@@ -1,17 +1,71 @@
 # 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] maximum number of items the queue can hold
+  #   @return [Ratomic::Queue] a new shareable queue
+  #   @raise [ArgumentError] if +capacity+ is outside the supported range
+  #   @raise [TypeError] if +capacity+ cannot be converted to an Integer
+  #
+  # @!method push(item)
+  #   Push an item, blocking until space is available.
+  #
+  #   @param item [Object] the item to append to the queue
+  #   @return [Ratomic::Queue] self
+  #
+  # @!method pop
+  #   Pop an item, blocking until one is available.
+  #
+  #   @return [Object] the next queued item
+  #
+  # @!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] the next item, or nil if the queue is empty
+  #
+  # @!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] true when the queue currently has no items
+  #
+  # @!method size
+  #   Return the current queue size.
+  #
+  #   Since this is a concurrent queue, the value is a moment-in-time
+  #   observation.
+  #
+  #   @return [Integer] the current number of queued items
+  #
+  # @!method length
+  #   Alias for #size.
+  #
+  #   @return [Integer] the current number of queued items
+  class Queue
     # Push an item and return the queue for chaining.
     #
-    # @param item [Object]
-    # @return [Ratomic::Queue]
+    # @param item [Object] the item to append to the queue
+    # @return [Ratomic::Queue] self
     def <<(item)
       push(item)
       self
     end
   end
-
-  Queue.prepend(QueueMethods)
 end

data/lib/ratomic/undefined.rb

@@ -4,7 +4,9 @@ module Ratomic
   # Internal sentinel object for future Hash-like APIs that need to distinguish
   # missing keys from explicit nil values.
   class Undefined
-    # @return [String]
+    # Return the sentinel's stable inspection string.
+    #
+    # @return [String] a human-readable sentinel marker
     def inspect
       "#<Undefined>"
     end

data/lib/ratomic/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Ratomic
-  VERSION = "0.2.1"
+  # Current gem version string.
+  VERSION = "0.3.1"
 end

data/lib/ratomic.rb

@@ -1,16 +1,21 @@
 # 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"
-
+# 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. Pool uses Ruby
+# Ractor ownership-transfer primitives instead of the native Rust path.
+#
+# The public API currently includes {Counter}, {Map}, {Queue}, and {Pool}.
 module Ratomic
-  # Base error for Ratomic-specific runtime failures.
+  # Base error class for Ratomic-specific failures.
   class Error < StandardError; end
 end
+
+require "ratomic/ratomic"
+require "ratomic/version"
+
+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.1
+  version: 0.3.1
 platform: x86_64-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: []