ratomic 0.1.0 → 0.2.1

data/ext/ratomic/src/mpmc_queue.rs

@@ -0,0 +1,164 @@
+use crate::{gc_guard::GcGuard, sem::Semaphore};
+use rb_sys::VALUE;
+use std::{
+    cell::Cell,
+    sync::atomic::{AtomicUsize, Ordering},
+};
+
+struct QueueElement {
+    sequence: AtomicUsize,
+    data: Cell<VALUE>,
+}
+
+unsafe impl Send for QueueElement {}
+unsafe impl Sync for QueueElement {}
+
+pub struct MpmcQueue {
+    buffer: Vec<QueueElement>,
+    buffer_size: usize,
+    enqueue_pos: AtomicUsize,
+    dequeue_pos: AtomicUsize,
+    gc_guard: GcGuard,
+    read_sem: Semaphore,
+    write_sem: Semaphore,
+}
+
+impl MpmcQueue {
+    pub fn new(buffer_size: usize, default: VALUE) -> Self {
+        let mut buffer = Vec::with_capacity(buffer_size);
+        for i in 0..buffer_size {
+            buffer.push(QueueElement {
+                sequence: AtomicUsize::new(i),
+                data: Cell::new(default),
+            });
+        }
+
+        let mut gc_guard = GcGuard::alloc();
+        gc_guard.init();
+        let mut read_sem = Semaphore::alloc();
+        read_sem.init(0);
+        let mut write_sem = Semaphore::alloc();
+        write_sem.init(buffer_size as u32);
+
+        Self {
+            buffer,
+            buffer_size,
+            enqueue_pos: AtomicUsize::new(0),
+            dequeue_pos: AtomicUsize::new(0),
+            gc_guard,
+            read_sem,
+            write_sem,
+        }
+    }
+
+    fn try_push(&self, data: VALUE) -> bool {
+        let mut cell;
+        let mut pos = self.enqueue_pos.load(Ordering::Relaxed);
+        loop {
+            cell = &self.buffer[pos % self.buffer_size];
+            let seq = cell.sequence.load(Ordering::Acquire);
+            let diff = seq as isize - pos as isize;
+            if diff == 0 {
+                if self
+                    .enqueue_pos
+                    .compare_exchange_weak(pos, pos + 1, Ordering::Relaxed, Ordering::Relaxed)
+                    .is_ok()
+                {
+                    break;
+                }
+            } else if diff < 0 {
+                return false;
+            } else {
+                pos = self.enqueue_pos.load(Ordering::Relaxed);
+            }
+        }
+        cell.data.set(data);
+        cell.sequence.store(pos + 1, Ordering::Release);
+        self.read_sem.post();
+        true
+    }
+
+    fn try_pop(&self) -> Option<VALUE> {
+        let mut cell;
+        let mut pos = self.dequeue_pos.load(Ordering::Relaxed);
+        loop {
+            cell = &self.buffer[pos % self.buffer_size];
+            let seq = cell.sequence.load(Ordering::Acquire);
+            let diff = seq as isize - (pos + 1) as isize;
+            if diff == 0 {
+                if self
+                    .dequeue_pos
+                    .compare_exchange_weak(pos, pos + 1, Ordering::Relaxed, Ordering::Relaxed)
+                    .is_ok()
+                {
+                    break;
+                }
+            } else if diff < 0 {
+                return None;
+            } else {
+                pos = self.dequeue_pos.load(Ordering::Relaxed);
+            }
+        }
+
+        let data = cell.data.get();
+        cell.sequence
+            .store(pos + self.buffer_size, Ordering::Release);
+        self.write_sem.post();
+
+        #[cfg(feature = "simulation")]
+        std::thread::sleep(std::time::Duration::from_millis(100));
+
+        Some(data)
+    }
+
+    pub fn push(&self, data: VALUE) {
+        loop {
+            if self.try_push(data) {
+                return;
+            }
+            self.write_sem.wait();
+        }
+    }
+
+    pub fn pop(&self) -> VALUE {
+        loop {
+            if let Some(data) = self.gc_guard.acquire_as_consumer(|| self.try_pop()) {
+                return data;
+            }
+            self.read_sem.wait();
+        }
+    }
+
+    pub fn peek(&self) -> Option<VALUE> {
+        let pos = self.dequeue_pos.load(Ordering::Relaxed);
+        let cell = &self.buffer[pos % self.buffer_size];
+        let seq = cell.sequence.load(Ordering::Acquire);
+        let diff = seq as isize - (pos + 1) as isize;
+        if diff == 0 {
+            Some(cell.data.get())
+        } else {
+            None
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.dequeue_pos.load(Ordering::Relaxed) == self.enqueue_pos.load(Ordering::Relaxed)
+    }
+
+    pub fn size(&self) -> usize {
+        self.enqueue_pos
+            .load(Ordering::Relaxed)
+            .wrapping_sub(self.dequeue_pos.load(Ordering::Relaxed))
+    }
+
+    pub fn mark<F>(&self, mark: F)
+    where
+        F: Fn(VALUE),
+    {
+        self.gc_guard.acquire_as_gc(|| {
+            for item in self.buffer.iter() {
+                mark(item.data.get());
+            }
+        });
+    }
+}

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,170 @@
+# 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
+
+    # 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
+    # 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
+        break if handle_command(command, args, available, waiting) == :shutdown
+      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))
+      when :shutdown
+        :shutdown
+      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.1"
 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