ratomic 0.1.0 → 0.2.0

data/ext/ratomic/src/sem.rs

@@ -0,0 +1,72 @@
+use std::sync::{Condvar, Mutex};
+
+pub(crate) struct Semaphore {
+    // Wrap the state in a heap-allocated Box so the raw pointer `self.inner` remains stable
+    inner: *mut SemaphoreInner,
+}
+
+struct SemaphoreInner {
+    lock: Mutex<u32>, // the current count of permits
+    cvar: Condvar,
+}
+
+impl Semaphore {
+    pub(crate) fn alloc() -> Self {
+        Self {
+            inner: std::ptr::null_mut(),
+        }
+    }
+
+    pub(crate) fn init(&mut self, initial: u32) {
+        let inner_struct = SemaphoreInner {
+            lock: Mutex::new(initial),
+            cvar: Condvar::new(),
+        };
+        // Box into raw pointer to manage memory life manually
+        self.inner = Box::into_raw(Box::new(inner_struct));
+    }
+
+    pub(crate) fn post(&self) {
+        if self.inner.is_null() {
+            return;
+        }
+        
+        let inner = unsafe { &*self.inner };
+        let mut count = inner.lock.lock().unwrap();
+        *count += 1;
+        
+        // notify to wake up a waiting thread
+        inner.cvar.notify_one();
+    }
+
+    pub(crate) fn wait(&self) {
+        if self.inner.is_null() {
+            return;
+        }
+
+        let inner = unsafe { &*self.inner };
+        let mut count = inner.lock.lock().unwrap();
+        
+        // Block the thread while there are no available permits
+        while *count == 0 {
+            count = inner.cvar.wait(count).unwrap();
+        }
+        
+        *count -= 1;
+    }
+}
+
+impl Drop for Semaphore {
+    fn drop(&mut self) {
+        if !self.inner.is_null() {
+            unsafe {
+                // Safely reclaim and drop the heap allocated struct
+                let _ = Box::from_raw(self.inner);
+            }
+            self.inner = std::ptr::null_mut();
+        }
+    }
+}
+
+unsafe impl Send for Semaphore {}
+unsafe impl Sync for Semaphore {}

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

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

data/lib/ratomic.rb

@@ -1,68 +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
-
-  ##
-  # An atomic counter which can be incremented and decremented
-  # safely by multiple Ractors concurrently.
-  class Counter
-    def value
-      read
-    end
-
-    def inc(amt = 1)
-      raise ArgumentError, "amount must be positive: #{amt}" if amt < 0
-      increment(amt)
-    end
-
-    def dec(amt = 1)
-      raise ArgumentError, "amount must be positive: #{amt}" if amt < 0
-      decrement(amt)
-    end
-  end
-
-  class Undefined
-    def inspect
-      "#<Undefined>"
-    end
-  end
-  UNDEFINED = Ractor.make_shareable(Undefined.new)
-
-  class Pool < FixedSizeObjectPool
-    def initialize(size = 5, timeout = 1.0)
-      super(size, (timeout * 1000).to_i)
-    end
-
-    def with
-      obj_and_idx = checkout
-      if obj_and_idx.nil?
-        raise Ratomic::Error, "pool checkout timeout"
-      else
-        yield obj_and_idx[0]
-      end
-    ensure
-      unless obj_and_idx.nil?
-        checkin(obj_and_idx[1])
-      end
-    end
-  end
-
-  class Map < ConcurrentHashMap
-    def []=(key, value)
-      set(key, value)
-    end
-
-    def [](key)
-      get(key)
-    end
-
-    # TODO add as much of the Hash API as possible.
-    # Stretch goal? Support Enumerable if DashMap can safely
-    # iterate.
-  end
-
 end

data/ratomic.gemspec

@@ -5,35 +5,41 @@ require_relative "lib/ratomic/version"
 Gem::Specification.new do |spec|
   spec.name = "ratomic"
   spec.version = Ratomic::VERSION
-  spec.authors = ["Mike Perham"]
+  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 = ">= 3.4.0"
+  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.
-  gemspec = File.basename(__FILE__)
-  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
-    ls.readlines("\x0", chomp: true).select do |f|
-      (f == gemspec) || f.start_with?(*%w[lib/ ext/ rs/])
-    end
-  end
-  %w(lib/ratomic/ratomic.bundle lib/ratomic/ratomic.so).each do |file|
-    File.exist?(file) && spec.files << file
-  end
+  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"]
 
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
+  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

metadata

@@ -1,14 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ratomic
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mike Perham
+- Ken C. Demanawa
 bindir: bin
 cert_chain: []
-date: 2025-03-22 00:00:00.000000000 Z
-dependencies: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.128
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.128
 description: Mutable data structures for Ractors
 email:
 - mike@perham.net
@@ -17,35 +32,38 @@ extensions:
 - ext/ratomic/extconf.rb
 extra_rdoc_files: []
 files:
-- ext/ratomic/counter.h
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/ratomic/Cargo.toml
+- ext/ratomic/build.rs
 - ext/ratomic/extconf.rb
-- ext/ratomic/fixed-size-object-pool.h
-- ext/ratomic/hashmap.h
-- ext/ratomic/mpmc-queue.h
-- ext/ratomic/ratomic.c
+- ext/ratomic/src/counter.rs
+- ext/ratomic/src/fixed_size_object_pool.rs
+- ext/ratomic/src/gc_guard.rs
+- ext/ratomic/src/hashmap.rs
+- ext/ratomic/src/lib.rs
+- ext/ratomic/src/mpmc_queue.rs
+- ext/ratomic/src/sem.rs
 - lib/ratomic.rb
-- lib/ratomic/ratomic.bundle
+- 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
-- rs/Cargo.lock
-- rs/Cargo.toml
-- rs/cbindgen.toml
-- rs/rust-atomics.h
-- rs/src/bin/mpmc_queue.rs
-- rs/src/counter.rs
-- rs/src/fixed_size_object_pool.rs
-- rs/src/gc_guard.rs
-- rs/src/hashmap.rs
-- rs/src/lib.rs
-- rs/src/mpmc_queue.rs
-- rs/src/sem.rs
 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'
 rdoc_options: []
 require_paths:
 - lib
@@ -53,14 +71,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0
+      version: 4.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Mutable data structures for Ractors
 test_files: []

data/ext/ratomic/counter.h

@@ -1,45 +0,0 @@
-#include "rust-atomics.h"
-#include <ruby.h>
-
-const rb_data_type_t atomic_counter_data = {
-    .function = {.dfree = RUBY_DEFAULT_FREE},
-    .flags = RUBY_TYPED_FROZEN_SHAREABLE};
-
-VALUE rb_atomic_counter_alloc(VALUE klass) {
-  atomic_counter_t *counter;
-  TypedData_Make_Struct0(obj, klass, atomic_counter_t, ATOMIC_COUNTER_SIZE,
-                         &atomic_counter_data, counter);
-  atomic_counter_init(counter, 0);
-  VALUE rb_cRactor = rb_const_get(rb_cObject, rb_intern("Ractor"));
-  rb_funcall(rb_cRactor, rb_intern("make_shareable"), 1, obj);
-  return obj;
-}
-
-VALUE rb_atomic_counter_increment(VALUE self, VALUE amt) {
-  atomic_counter_t *counter;
-  TypedData_Get_Struct(self, atomic_counter_t, &atomic_counter_data, counter);
-  atomic_counter_increment(counter, FIX2LONG(amt));
-  return Qnil;
-}
-
-VALUE rb_atomic_counter_decrement(VALUE self, VALUE amt) {
-  atomic_counter_t *counter;
-  TypedData_Get_Struct(self, atomic_counter_t, &atomic_counter_data, counter);
-  atomic_counter_decrement(counter, FIX2LONG(amt));
-  return Qnil;
-}
-
-VALUE rb_atomic_counter_read(VALUE self) {
-  atomic_counter_t *counter;
-  TypedData_Get_Struct(self, atomic_counter_t, &atomic_counter_data, counter);
-  return LONG2FIX(atomic_counter_read(counter));
-}
-
-static void init_counter(VALUE rb_mRoot) {
-  VALUE rb_cAtomicCounter =
-      rb_define_class_under(rb_mRoot, "Counter", rb_cObject);
-  rb_define_alloc_func(rb_cAtomicCounter, rb_atomic_counter_alloc);
-  rb_define_method(rb_cAtomicCounter, "increment", rb_atomic_counter_increment, 1);
-  rb_define_method(rb_cAtomicCounter, "decrement", rb_atomic_counter_decrement, 1);
-  rb_define_method(rb_cAtomicCounter, "read", rb_atomic_counter_read, 0);
-}