ratomic 0.2.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3286cccf68f0a8ade3d2ac457a72d160f1118526ee307b5806aaa72f5a4dfdb
+  data.tar.gz: 14d72b6c235f3bb55152f22de80af2993e771fd3ad91e86ce177e7926bcfb1ee
+SHA512:
+  metadata.gz: 98091fcd188cf500f959e29e8cef6e7adc456bd8c19afba087098bd9b160400c6de98e2e0bafe69a40d824b76bad36992d601405ff39fdfad67abe58fa8a6c4c
+  data.tar.gz: ba08bd30f0e721faf954d5bb9f049b0d15eec2ad427be47b773c00b6666f362bbcdf83e9981a6faa79691ce19b25f58d59e6710cb8b9b82f7f89a026a9a08639

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-06-04
+
+- Drop Ruby 3.x support and require Ruby 4.
+- Add `length`, `size`, `peek`, and `empty?` methods to `Ratomic::Queue`.
+- Change `Ratomic::Pool` to use Ruby 4 `Ractor::Port` ownership transfer semantics, fixing the unsafe stale-reference behavior reported in [#5]
+(https://github.com/mperham/ratomic/issues/5).
+- Organize Ruby wrapper code by primitive.
+- Add primitive contract tests for `Counter`, `Map`, `Queue`, and `Pool`.
+- Add SimpleCov coverage reporting.
+- Undefine native typed-data default allocators to remove Ruby 4 warnings.
+
+## [0.1.0] - 2025-03-20
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Ilya Bylich
+Copyright (c) Contributed Systems LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,176 @@
+# Ratomic
+
+Ratomic provides mutable data structures for use with Ruby's Ractors.
+This allows Ruby code to scale beyond the infamous GVL.
+
+# HELP WANTED!
+
+> 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.
+
+## How to contribute
+
+Please make sure to understand our [Code of Conduct](./CODE_OF_CONDUCT.md).
+
+After changing code, you can give it a spin with:
+
+```bash
+rake
+```
+
+This should compile the Rust code and run all tests.
+The test suite writes a SimpleCov report to `coverage/index.html` so you can see which Ruby wrapper paths are covered.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add ratomic
+```
+
+TODO: We have not released a gem yet.
+
+## Usage
+
+Ratomic provides several useful Ractor-safe structures.
+Note the APIs available are frequently very limited compared to Ruby's broad API.
+
+These structures are designed for use as class-level constants so they can be shared by numerous Ractors.
+
+Ratomic has two different safety models:
+
+* `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.
+
+### `Ratomic::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
+```
+
+### `Ratomic::Pool`
+
+A Ractor-safe object pool:
+
+```ruby
+POOL = Ratomic::Pool.new(5, 1.0) { [] }
+POOL.with do |obj|
+  # do something with obj
+  obj << "work"
+end
+```
+
+`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.
+
+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.
+
+In that model:
+
+* 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
+
+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
+
+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`
+
+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"
+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:
+
+```ruby
+obj = POOL.checkout
+raise "pool checkout timeout" if obj.nil?
+
+begin
+  obj << "manual work"
+ensure
+  POOL.checkin(obj) if obj
+end
+```
+
+`checkout` returns `nil` if no pooled object becomes available before the configured timeout. `with` raises `Ratomic::Error` in that case.
+
+### `Ratomic::Map`
+
+A Ractor-safe map/hash structure:
+
+```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
+```
+
+### `Ratomic::Queue`
+
+A multi-producer, multi-consumer queue.
+
+```ruby
+q = Ratomic::Queue.new(128)
+
+q.push("hello")
+q << "world"
+
+q.size     # => 2
+q.empty?   # => false
+q.peek     # => "hello"
+item = q.pop # => "hello"
+item = q.pop # => "world"
+q.empty?   # => true
+```
+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.
+
+## 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!
+
+This repo is further research into the usability and limitations of Ractor-friendly structures in Ruby code and gems.
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT).

data/lib/ratomic/counter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ratomic
+  # Ruby convenience methods for {Counter}.
+  module CounterMethods
+    # Read the current counter value.
+    #
+    # @return [Integer]
+    def value
+      read
+    end
+
+    # Coerce the counter to an Integer snapshot.
+    #
+    # @return [Integer]
+    def to_i
+      read
+    end
+
+    # Check whether the current counter value is zero.
+    #
+    # @return [Boolean]
+    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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Ratomic
+  # A Ractor-shareable concurrent map.
+  #
+  # 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.
+  #
+  # This is not a full Hash replacement. Iteration and arbitrary mutable object
+  # borrowing are intentionally absent.
+  #
+  # @example Store pipeline offsets
+  #   OFFSETS = Ratomic::Map.new
+  #   OFFSETS[:source_a] = 42
+  #   OFFSETS[:source_a] # => 42
+  Map = ConcurrentHashMap
+
+  # Ruby convenience methods for {Map}.
+  module MapMethods
+    # Set a value for +key+.
+    #
+    # @param key [Object]
+    # @param value [Object]
+    # @return [void]
+    def []=(key, value)
+      set(key, value)
+    end
+
+    # Read a value by +key+.
+    #
+    # Missing keys currently return nil, so storing nil is ambiguous.
+    #
+    # @param key [Object]
+    # @return [Object, nil]
+    def [](key)
+      get(key)
+    end
+
+    # Alias for #size.
+    #
+    # @return [Integer]
+    def length
+      size
+    end
+
+    # Check whether the map currently has no entries.
+    #
+    # @return [Boolean]
+    def empty?
+      size.zero?
+    end
+  end
+
+  ConcurrentHashMap.prepend(MapMethods)
+end

data/lib/ratomic/pool.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Ratomic
+  # A Ractor-safe ownership-transfer pool for mutable Ruby objects.
+  #
+  # Pool follows a Rust-inspired ownership-transfer model: a pooled object has
+  # one active owner at a time. #checkout moves ownership from the pool to the
+  # caller; #checkin moves ownership back to the pool. Ruby enforces stale
+  # caller references dynamically with Ractor::MovedError.
+  #
+  # This is ownership transfer, not borrowing. Pool never lends shared mutable
+  # references across Ractors.
+  #
+  # Pool uses a private coordinator Ractor and caller-owned Ractor::Port reply
+  # ports. Objects are moved to callers on checkout and moved back to the pool
+  # on checkin. This is intentionally different from sharing the same mutable
+  # object between Ractors: at any instant, exactly one Ractor owns a checked-out
+  # object.
+  #
+  # @example Reuse mutable buffers safely
+  #   BUFFERS = Ratomic::Pool.new(4, 1.0) { [] }
+  #   BUFFERS.with do |buffer|
+  #     buffer.clear
+  #     buffer << :change
+  #   end
+  class Pool
+    # Create a pool and seed it with +size+ objects from the factory block.
+    #
+    # @param size [Integer] number of pooled objects
+    # @param timeout [Numeric, nil] checkout timeout in seconds, or nil to wait indefinitely
+    # @yieldreturn [Object] mutable object to store in the pool
+    # @raise [ArgumentError] if +size+ is not positive
+    # @raise [LocalJumpError] if no factory block is given
+    def initialize(size = 5, timeout = 1.0)
+      raise ArgumentError, "pool size must be positive" if size <= 0
+      raise LocalJumpError, "no block given" unless block_given?
+
+      @timeout = timeout&.to_f
+      @control = self.class.send(:new_control_ractor)
+      size.times { @control.send([:checkin, yield], move: true) }
+      freeze
+      Ractor.make_shareable(self)
+    end
+
+    # Checkout one object from the pool.
+    #
+    # 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
+    def checkout
+      reply = Ractor::Port.new
+      request_id = reply.object_id
+      @control << [:checkout, request_id, reply]
+      receive_checkout_reply(reply)
+    rescue Timeout::Error
+      nil
+    ensure
+      @control << [:cancel, request_id] if request_id
+      reply&.close unless reply&.closed?
+    end
+
+    # Return an object to the pool.
+    #
+    # This moves ownership from the caller back to the pool. The caller must not
+    # use the object after calling this method; Ruby raises Ractor::MovedError
+    # for stale references.
+    #
+    # @param object [Object] previously checked-out pooled object
+    # @return [nil]
+    def checkin(object)
+      @control.send([:checkin, object], move: true)
+      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
+    # block. If checkout times out, raises Ratomic::Error and does not yield.
+    #
+    # @yieldparam object [Object] checked-out pooled object
+    # @raise [Ratomic::Error] if checkout times out
+    # @return [Object] block return value
+    def with
+      object = checkout
+      raise Ratomic::Error, "pool checkout timeout" if object.nil?
+
+      yield object
+    ensure
+      checkin(object) unless object.nil?
+    end
+
+    def self.new_control_ractor
+      Ractor.new { Ratomic::Pool.send(:run_control_loop) }
+    end
+    private_class_method :new_control_ractor
+
+    def self.run_control_loop
+      available = []
+      waiting = {}
+
+      loop do
+        command, *args = Ractor.receive
+        handle_command(command, args, available, waiting)
+      end
+    end
+    private_class_method :run_control_loop
+
+    def self.handle_command(command, args, available, waiting)
+      case command
+      when :checkout
+        handle_checkout(args, available, waiting)
+      when :checkin
+        handle_checkin(args.fetch(0), available, waiting)
+      when :cancel
+        waiting.delete(args.fetch(0))
+      end
+    end
+    private_class_method :handle_command
+
+    def self.handle_checkout(args, available, waiting)
+      request_id, reply = args
+      if (object = available.shift)
+        reply.send(object, move: true)
+      else
+        waiting[request_id] = reply
+      end
+    end
+    private_class_method :handle_checkout
+
+    def self.handle_checkin(object, available, waiting)
+      loop do
+        _request_id, reply = waiting.shift
+        return available << object if reply.nil?
+
+        begin
+          reply.send(object, move: true)
+          return
+        rescue Ractor::ClosedError
+          next
+        end
+      end
+    end
+    private_class_method :handle_checkin
+
+    private
+
+    def receive_checkout_reply(reply)
+      return reply.receive unless @timeout
+
+      Timeout.timeout(@timeout) { reply.receive }
+    end
+  end
+end

data/lib/ratomic/queue.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Ratomic
+  # Ruby convenience methods for {Queue}.
+  module QueueMethods
+    # Push an item and return the queue for chaining.
+    #
+    # @param item [Object]
+    # @return [Ratomic::Queue]
+    def <<(item)
+      push(item)
+      self
+    end
+  end
+
+  Queue.prepend(QueueMethods)
+end

data/lib/ratomic/undefined.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Ratomic
+  # Internal sentinel object for future Hash-like APIs that need to distinguish
+  # missing keys from explicit nil values.
+  class Undefined
+    # @return [String]
+    def inspect
+      "#<Undefined>"
+    end
+  end
+
+  # Internal shareable missing-value sentinel.
+  UNDEFINED = Ractor.make_shareable(Undefined.new)
+end

data/lib/ratomic/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ratomic
+  VERSION = "0.2.0"
+end

data/lib/ratomic.rb

@@ -0,0 +1,16 @@
+# 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"
+
+module Ratomic
+  # Base error for Ratomic-specific runtime failures.
+  class Error < StandardError; end
+end

data/ratomic.gemspec

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "lib/ratomic/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ratomic"
+  spec.version = Ratomic::VERSION
+  spec.authors = ["Mike Perham", "Ken C. Demanawa"]
+  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.license = "MIT"
+  spec.required_ruby_version = ">= 4.0.0"
+
+  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["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = [
+    "Cargo.lock",
+    "Cargo.toml",
+    "CHANGELOG.md",
+    "LICENSE.txt",
+    "README.md",
+    "ratomic.gemspec"
+  ] + Dir[
+    "lib/**/*.rb",
+    "ext/ratomic/Cargo.toml",
+    "ext/ratomic/build.rs",
+    "ext/ratomic/extconf.rb",
+    "ext/ratomic/src/**/*.rs"
+  ]
+  spec.require_paths = ["lib"]
+  spec.extensions = ["ext/ratomic/extconf.rb"]
+
+  spec.add_dependency "rb_sys", "~> 0.9.128"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: ratomic
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: x86_64-linux
+authors:
+- Mike Perham
+- Ken C. Demanawa
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-04 00:00:00.000000000 Z
+dependencies: []
+description: Mutable data structures for Ractors
+email:
+- mike@perham.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ratomic.rb
+- lib/ratomic/3.0/ratomic.so
+- lib/ratomic/3.1/ratomic.so
+- lib/ratomic/3.2/ratomic.so
+- lib/ratomic/3.3/ratomic.so
+- lib/ratomic/3.4/ratomic.so
+- lib/ratomic/4.0/ratomic.so
+- lib/ratomic/counter.rb
+- lib/ratomic/map.rb
+- lib/ratomic/pool.rb
+- lib/ratomic/queue.rb
+- lib/ratomic/undefined.rb
+- lib/ratomic/version.rb
+- ratomic.gemspec
+homepage: https://github.com/mperham/ratomic
+licenses:
+- MIT
+metadata:
+  maintainers: Ken C. Demanawa
+  homepage_uri: https://github.com/mperham/ratomic
+  source_code_uri: https://github.com/mperham/ratomic
+  changelog_uri: https://github.com/mperham/ratomic
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Mutable data structures for Ractors
+test_files: []