ratomic 0.2.1 → 0.3.1

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: ruby
 authors:
 - Mike Perham
@@ -24,7 +24,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.128
-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: []
@@ -55,14 +56,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'
 rdoc_options: []
 require_paths:
@@ -71,7 +72,10 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 4.0.0
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -80,5 +84,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Mutable data structures for Ractors
+summary: Ractor-safe concurrent data structures for Ruby
 test_files: []