ratomic 0.2.0 → 0.3.0

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: 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: []