ratomic 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5196316489486d3034c046db087ae5878dc7fcf2f2e3d4086d91c128f8a30dd5
-  data.tar.gz: 6bf7a6aed05756ff9a0f49f274d69ed91b1f722930c94a140cc5450746fec3f2
+  metadata.gz: bdf323b8b7b61fa10e96f376cf5cf5001b5df0c5155e0a2ab815a86561c2245d
+  data.tar.gz: c5d6536e0ef372bde684f19ca4af1174d1f7ab6a2143270bb884c674ab76fba2
 SHA512:
-  metadata.gz: f0276e6c7e78c7bdcbabb3839d59eb70e58289f3662fe1df244fce9abc9b3a1eeb3454a4116081cd0f0426e470ed64a3d0108f8a57650455e17cc96f111f51e7
-  data.tar.gz: 8eb3b4c4f248569568ea7394a89156961aeb8108b0448c5ef3012045486537cd3c862fff684ac39192d2c31842159e5ad798b9005ce48909281f19d1c9043827
+  metadata.gz: 268606f63d6868b2f1c02421ad27e09d8344c2b404653d2e2e43376db814f9deaafdd608bce146129addd72ba43fc4b534a4a1aca17851c9fec35aad8a781400
+  data.tar.gz: fc604b15381e5ef3bd9a48c4294eefb4dcdfc5c2d6dbdf526ecfe621ce9adcad26db861eba41a33cf1d1dd7388696ea6d2f959dd2992cb77e7f13e108e6f9de0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [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.

data/README.md

@@ -5,9 +5,7 @@
 [![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.
+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.
 
 ## Project Direction
 

data/ext/ratomic/src/lib.rs

@@ -46,12 +46,14 @@ impl Counter {
         make_shareable(ruby, value)
     }
 
-    fn increment(&self, amt: u64) {
+    fn increment(&self, amt: u64) -> u64 {
         self.0.inc(amt);
+        self.0.read()
     }
 
-    fn decrement(&self, amt: u64) {
+    fn decrement(&self, amt: u64) -> u64 {
         self.0.dec(amt);
+        self.0.read()
     }
 
     fn read(&self) -> u64 {
@@ -100,8 +102,9 @@ impl HashMap {
         self.0.contains_key(value_to_raw(key))
     }
 
-    fn set(&self, key: Value, value: Value) {
+    fn set(&self, key: Value, value: Value) -> Value {
         self.0.set(value_to_raw(key), value_to_raw(value));
+        value
     }
 
     fn delete(ruby: &Ruby, rb_self: &Self, key: Value) -> Value {
@@ -109,8 +112,10 @@ impl HashMap {
         unsafe { value_from_raw(raw) }.into_value_with(ruby)
     }
 
-    fn clear(&self) {
-        self.0.clear();
+    fn clear(_ruby: &Ruby, value: Value) -> Result<Value, Error> {
+        let rb_self: &Self = TryConvert::try_convert(value)?;
+        rb_self.0.clear();
+        Ok(value)
     }
 
     fn size(&self) -> usize {
@@ -307,9 +312,10 @@ impl Queue {
         make_shareable(ruby, value)
     }
 
-    fn push(&self, item: Value) {
+    fn push(ruby: &Ruby, rb_self: Value, item: Value) -> Result<Value, Error> {
+        let queue: &Self = TryConvert::try_convert(rb_self)?;
         let mut payload = PushPayload {
-            queue: &self.0,
+            queue: &queue.0,
             item: value_to_raw(item),
         };
         unsafe {
@@ -320,6 +326,7 @@ impl Queue {
                 std::ptr::null_mut(),
             );
         }
+        Ok(rb_self.into_value_with(ruby))
     }
 
     fn pop(&self) -> Value {

data/lib/ratomic/counter.rb

@@ -8,48 +8,48 @@ module Ratomic
   #
   # @example Count work across Ractors
   #   counter = Ratomic::Counter.new
-  #   counter.increment(1)
+  #   counter.increment(1) # => 1
   #   counter.read # => 1
   #
   # @!method self.new
   #   Create a counter initialized to zero.
   #
-  #   @return [Ratomic::Counter]
+  #   @return [Ratomic::Counter] a new shareable counter
   #
   # @!method read
   #   Read the current counter value.
   #
-  #   @return [Integer]
+  #   @return [Integer] the current counter value
   #
   # @!method increment(amt)
   #   Increment the counter by +amt+.
   #
-  #   @param amt [Integer]
-  #   @return [void]
+  #   @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]
-  #   @return [void]
+  #   @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

data/lib/ratomic/map.rb

@@ -22,15 +22,27 @@ module Ratomic
   #   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]
+  #   @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+.
   #
-  #   @param key [Object]
-  #   @param value [Object]
-  #   @return [void]
+  #   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.
@@ -38,8 +50,8 @@ module Ratomic
   #   Unlike #get and #[], this distinguishes missing keys from stored nil
   #   values.
   #
-  #   @param key [Object]
-  #   @return [Boolean]
+  #   @param key [Object] lookup key
+  #   @return [Boolean] true when the key currently exists
   #
   # @!method delete(key)
   #   Remove +key+ and return its previous value.
@@ -47,20 +59,20 @@ module Ratomic
   #   Missing keys return nil. Stored nil values also return nil; use #key?
   #   before deleting if that distinction matters.
   #
-  #   @param key [Object]
-  #   @return [Object, nil]
+  #   @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 [void]
+  #   @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]
+  #   @return [Integer] the current number of entries
   #
   # @!method fetch_and_modify(key)
   #   Replace the existing value for +key+ with the block return value.
@@ -73,9 +85,9 @@ module Ratomic
   #   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]
+  #   @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
   #
@@ -93,8 +105,8 @@ module Ratomic
   #   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
+  #   @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
@@ -112,7 +124,7 @@ module Ratomic
   #
   #   If the block raises, no entry is inserted.
   #
-  #   @param key [Object]
+  #   @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
@@ -131,9 +143,9 @@ module Ratomic
   #
   #   If the block raises, the previous value is preserved.
   #
-  #   @param key [Object]
-  #   @param initial [Object]
-  #   @yieldparam value [Object, nil] current value
+  #   @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
@@ -145,8 +157,8 @@ module Ratomic
   #   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]
+  #   @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
   #
@@ -155,8 +167,8 @@ module Ratomic
   #
   #   Missing keys start at zero.
   #
-  #   @param key [Object]
-  #   @param by [Numeric]
+  #   @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
   #
@@ -165,8 +177,8 @@ module Ratomic
   #
   #   The stored Array is replaced rather than mutated in place.
   #
-  #   @param key [Object]
-  #   @param value [Object]
+  #   @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
   #
@@ -175,16 +187,18 @@ module Ratomic
   #
   #   The stored Set is replaced rather than mutated in place.
   #
-  #   @param key [Object]
-  #   @param value [Object]
+  #   @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
@@ -193,8 +207,8 @@ 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
@@ -203,10 +217,10 @@ module Ratomic
     #
     # Unlike #[], this distinguishes missing keys from explicit nil values.
     #
-    # @param key [Object]
-    # @param default [Object]
-    # @yieldparam key [Object]
-    # @return [Object]
+    # @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)
@@ -222,8 +236,8 @@ module Ratomic
     # 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]
+    # @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)
@@ -236,8 +250,8 @@ module Ratomic
     #
     # Missing keys start at zero.
     #
-    # @param key [Object]
-    # @param by [Numeric]
+    # @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)
@@ -250,8 +264,8 @@ module Ratomic
     #
     # The stored Array is replaced rather than mutated in place.
     #
-    # @param key [Object]
-    # @param value [Object]
+    # @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)
@@ -274,8 +288,8 @@ module Ratomic
     #
     # The stored Set is replaced rather than mutated in place.
     #
-    # @param key [Object]
-    # @param value [Object]
+    # @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)
@@ -296,22 +310,22 @@ module Ratomic
 
     # 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
 
     # Alias for #key?.
     #
-    # @param key [Object]
-    # @return [Boolean]
+    # @param key [Object] lookup key
+    # @return [Boolean] true when the key currently exists
     def include?(key)
       key?(key)
     end

data/lib/ratomic/pool.rb

@@ -28,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)
@@ -49,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
@@ -68,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
@@ -80,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
@@ -94,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

@@ -14,21 +14,21 @@ module Ratomic
   # @!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
+  #   @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]
-  #   @return [void]
+  #   @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]
+  #   @return [Object] the next queued item
   #
   # @!method peek
   #   Return the next item without removing it.
@@ -36,7 +36,7 @@ module Ratomic
   #   Since this is a concurrent queue, the value is a moment-in-time
   #   observation.
   #
-  #   @return [Object, nil]
+  #   @return [Object, nil] the next item, or nil if the queue is empty
   #
   # @!method empty?
   #   Check whether the queue currently appears empty.
@@ -44,7 +44,7 @@ module Ratomic
   #   Since this is a concurrent queue, the value is a moment-in-time
   #   observation.
   #
-  #   @return [Boolean]
+  #   @return [Boolean] true when the queue currently has no items
   #
   # @!method size
   #   Return the current queue size.
@@ -52,17 +52,17 @@ module Ratomic
   #   Since this is a concurrent queue, the value is a moment-in-time
   #   observation.
   #
-  #   @return [Integer]
+  #   @return [Integer] the current number of queued items
   #
   # @!method length
   #   Alias for #size.
   #
-  #   @return [Integer]
+  #   @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

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,10 +1,6 @@
 # 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
-  # Current gem version.
-  VERSION = "0.3.0"
+  # Current gem version string.
+  VERSION = "0.3.1"
 end

data/lib/ratomic.rb

@@ -1,12 +1,19 @@
 # frozen_string_literal: true
 
-require "ratomic/ratomic"
-require "ratomic/version"
-
+# 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 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratomic
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Mike Perham