ractor_queue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 47a22f9a81a1d6ce08a5588f4d1324e0d15006a57062057ec2ac74d5f44b8888
+  data.tar.gz: c56c3feadd7d4bfa98c28f9b10705fd749ca51d5fb56ab9004530fcba6d6b984
+SHA512:
+  metadata.gz: f381232cfc1aff09b17f0a41c35fdd22db4bbbbca1319135593c61c3f98dab892a811e59df1922e9eb0fcc55989b896460cf7587d911b6a3809306e28c7beb70
+  data.tar.gz: 335c0137bb03e242cd3fc63daad949e4a862fdf92eca3db068dbbf0728eec31e34210b833cd68376d9a9ac899c1b09f813bc871b6d083469336e3984419df705

data/README.md

@@ -0,0 +1,278 @@
+# ractor_queue
+
+A lock-free, bounded, MPMC queue that can be shared across Ruby Ractors.
+
+Ruby's built-in `Queue` uses a `Mutex` internally and cannot be passed as a shared reference across Ractor boundaries. `RactorQueue` has no mutex — it is always `Ractor.shareable?` and can be handed to any number of Ractors simultaneously.
+
+```ruby
+q = RactorQueue.new(capacity: 1024)
+
+producer = Ractor.new(q) { |queue| 1000.times { |i| queue.push(i) } }
+consumer = Ractor.new(q) { |queue| 1000.times { queue.pop } }
+
+producer.value
+consumer.value
+```
+
+Backed by the [max0x7ba/atomic_queue](https://github.com/max0x7ba/atomic_queue) C++14 header-only library via [Rice](https://github.com/jasonroelofs/rice) 4.x bindings.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "ractor_queue"
+```
+
+Or install directly:
+
+```sh
+gem install ractor_queue
+```
+
+Requires MRI Ruby 3.2+ and a C++17 compiler. The native extension is built automatically on `gem install`.
+
+---
+
+## Quick Start
+
+```ruby
+require "ractor_queue"
+
+# Create a bounded queue (capacity rounds up to the next power of two, minimum 4096)
+q = RactorQueue.new(capacity: 256)
+
+# Non-blocking
+q.try_push(42)      # => true  (enqueued)
+q.try_push(:hello)  # => true
+q.try_pop           # => 42
+q.try_pop           # => :hello
+q.try_pop           # => RactorQueue::EMPTY  (queue was empty)
+
+# Check for empty with identity comparison (never use ==)
+v = q.try_pop
+process(v) unless v.equal?(RactorQueue::EMPTY)
+
+# Blocking — spin-waits until space / item is available
+q.push(99)          # => self  (chainable)
+q.pop               # => 99
+
+# Blocking with timeout
+q.pop(timeout: 0.5) # raises RactorQueue::TimeoutError after 500 ms if still empty
+
+# State (approximate under concurrency)
+q.size              # => Integer
+q.empty?            # => true / false
+q.full?             # => true / false
+q.capacity          # => Integer (exact)
+
+# Always true — the queue itself is Ractor-shareable
+Ractor.shareable?(q) # => true
+```
+
+---
+
+## API
+
+| Method | Returns | Notes |
+|---|---|---|
+| `RactorQueue.new(capacity:, validate_shareable: false)` | `RactorQueue` instance | Capacity rounded up to power-of-two minimum |
+| `try_push(obj)` | `true` / `false` | Non-blocking; `false` if full |
+| `try_pop` | `obj` or `RactorQueue::EMPTY` | Non-blocking; `EMPTY` sentinel if queue was empty; `nil` if `nil` was pushed |
+| `push(obj, timeout: nil)` | `self` | Blocks until space; raises `TimeoutError` if timeout expires |
+| `pop(timeout: nil)` | `obj` | Blocks until item; raises `TimeoutError` if timeout expires |
+| `size` | Integer | Approximate element count |
+| `empty?` | Boolean | Approximate |
+| `full?` | Boolean | Approximate |
+| `capacity` | Integer | Exact allocated capacity |
+
+### Errors
+
+| Class / Constant | Meaning |
+|---|---|
+| `RactorQueue::EMPTY` | Sentinel returned by `try_pop` when the queue is empty. Check with `equal?`, never `==`. |
+| `RactorQueue::TimeoutError` | Raised by `push` or `pop` when the `timeout:` deadline expires. |
+| `RactorQueue::NotShareableError` | Raised by `push`/`try_push` when `validate_shareable: true` and the object is not Ractor-shareable. |
+
+### `validate_shareable`
+
+With `validate_shareable: true`, the queue raises `NotShareableError` at push time for any non-shareable object, catching mistakes before they reach a Ractor boundary:
+
+```ruby
+safe_q = RactorQueue.new(capacity: 64, validate_shareable: true)
+
+safe_q.push(42)             # ok — Integer is shareable
+safe_q.push("hello".freeze) # ok — frozen String is shareable
+safe_q.push([1, 2, 3])      # raises RactorQueue::NotShareableError
+```
+
+---
+
+## Ractor Patterns
+
+### 1. Single Producer / Single Consumer (1P1C)
+
+The baseline pattern — one Ractor feeds another through a shared queue.
+
+```ruby
+q = RactorQueue.new(capacity: 1024)
+
+producer = Ractor.new(q) do |queue|
+  100.times { |i| queue.push(i * i) }
+  queue.push(:done)
+end
+
+consumer = Ractor.new(q) do |queue|
+  results = []
+  loop do
+    v = queue.pop
+    break if v == :done
+    results << v
+  end
+  results
+end
+
+producer.value
+puts consumer.value.inspect
+```
+
+### 2. Worker Pool (MPMC)
+
+A shared job queue drained by N Ractor workers. Size the queues large enough to hold all in-flight items — chaining two small bounded queues risks deadlock (see [Concurrency Notes](#concurrency-notes)).
+
+```ruby
+WORKERS = 8
+jobs    = RactorQueue.new(capacity: 10_000)
+results = RactorQueue.new(capacity: 10_000)
+
+workers = WORKERS.times.map do
+  Ractor.new(jobs, results) do |jq, rq|
+    loop do
+      job = jq.pop(timeout: 30)
+      break if job == :stop
+      rq.push(job * job)        # do work
+    end
+  end
+end
+
+1000.times { |i| jobs.push(i) }
+WORKERS.times { jobs.push(:stop) }
+
+results_list = 1000.times.map { results.pop }
+workers.each(&:value)
+```
+
+### 3. Queue Pool (High Ractor Counts)
+
+When many Ractors share a single bounded queue, the spin-wait backoff keeps things moving, but beyond ~2× core count you get diminishing returns from cache-line contention. Use one queue per producer/consumer pair — zero cross-pair contention, linear scaling to core count:
+
+```ruby
+PAIRS = 16   # 32 Ractors total
+
+pairs = PAIRS.times.map do
+  q = RactorQueue.new(capacity: 1024)
+  p = Ractor.new(q) { |queue| 1000.times { |i| queue.push(i) } }
+  c = Ractor.new(q) { |queue| 1000.times { queue.pop } }
+  [p, c]
+end
+
+pairs.each { |p, c| p.value; c.value }
+```
+
+---
+
+## Concurrency Notes
+
+### Spin-wait backoff
+
+`push` and `pop` use an exponential backoff spin loop: the first 16 retries call `Thread.pass`; subsequent retries call `sleep(0.0001)`. The sleep actually suspends the OS thread, preventing scheduler thrashing when many Ractors are blocked on the same queue.
+
+This means `Thread#raise` and `Ctrl-C` can interrupt a blocked `push` or `pop` at any point.
+
+### Two-queue deadlock
+
+Chaining two bounded queues in a pipeline can deadlock when both queues are full simultaneously:
+
+```
+main blocks pushing to jobs (full)
+  ↓
+workers block pushing to results (full)
+  ↓
+main cannot drain results (it is blocked)
+  ↓  deadlock
+```
+
+**Fix:** size at least one queue large enough that its producer never blocks, or drain results asynchronously in a separate Ractor.
+
+### Spin-wait storm
+
+When more Ractors are actively spinning (blocked on `push`/`pop`) than there are idle cores, the OS scheduler can thrash. The sleep-based backoff mitigates this, but the practical ceiling for a single shared queue is roughly `2 × CPU cores` Ractors doing nothing but queue operations. For higher Ractor counts, use the queue pool pattern.
+
+### `nil` as a payload
+
+`try_pop` returns `RactorQueue::EMPTY` when the queue is empty and `nil` when `nil` was the pushed value — the two are unambiguous. Always check for empty with identity comparison:
+
+```ruby
+v = q.try_pop
+return if v.equal?(RactorQueue::EMPTY)
+process(v)   # v may be nil — that's fine, it's a real payload
+```
+
+Do not use `==` to check for `EMPTY` — use `equal?`.
+
+---
+
+## Performance
+
+Measured on Apple M2 Max (12 cores), Ruby 4.0.2:
+
+| Configuration | Throughput |
+|---|---|
+| 1 producer / 1 consumer Ractor | ~470K ops/s |
+| 2P / 2C shared queue | ~855K ops/s |
+| 4P / 4C shared queue | ~1.25M ops/s |
+| 8P / 8C shared queue | ~1.53M ops/s |
+| 8P / 8C queue pool (8 queues) | ~1.66M ops/s |
+| 50P / 50C queue pool | ~1.60M ops/s |
+
+Ruby's built-in `Queue` is not included — it cannot participate in Ractor benchmarks.
+
+Under MRI threads (no Ractors), Ruby's `Queue` is faster because the GVL makes lock-free atomics unnecessary. RactorQueue's advantage is exclusive to Ractor workloads.
+
+---
+
+## Running the Examples
+
+```sh
+bundle exec ruby examples/01_basic_usage.rb   # Ractor usage patterns
+bundle exec ruby examples/02_performance.rb   # Throughput benchmarks
+```
+
+---
+
+## Development
+
+```sh
+bundle install
+bundle exec rake compile   # build the native extension
+bundle exec rake test      # run the test suite
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [`examples/01_basic_usage.rb`](examples/01_basic_usage.rb) | Annotated Ractor usage patterns (1P1C, timeout, worker pool, pipeline, validate_shareable) |
+| [`examples/02_performance.rb`](examples/02_performance.rb) | Throughput benchmarks across queue topologies and Ractor counts |
+| [`docs/superpowers/specs/2026-04-10-atomic-queue-design.md`](docs/superpowers/specs/2026-04-10-atomic-queue-design.md) | Original design specification (C extension architecture, Rice bindings, API design decisions) |
+| [`docs/superpowers/plans/`](docs/superpowers/plans/) | Implementation plans for each development phase |
+
+---
+
+## License
+
+MIT. The vendored [max0x7ba/atomic_queue](https://github.com/max0x7ba/atomic_queue) C++ library is also MIT licensed.

data/ext/ractor_queue/extconf.rb

@@ -0,0 +1,10 @@
+require "mkmf-rice"
+
+$INCFLAGS << " -I$(srcdir)/../../vendor/atomic_queue/include"
+$CPPFLAGS << " -std=c++17"
+
+unless find_header("atomic_queue/atomic_queue.h")
+  abort "Cannot find atomic_queue/atomic_queue.h — check vendor/ directory"
+end
+
+create_makefile "ractor_queue/ractor_queue"

data/ext/ractor_queue/ractor_queue.cpp

@@ -0,0 +1,45 @@
+#include <rice/rice.hpp>
+#include <atomic_queue/atomic_queue.h>
+#include <ruby.h>
+#include "standard_queue.h"
+
+using namespace Rice;
+
+// Global sentinel — a unique frozen Ruby Object used to signal "queue empty"
+// from c_try_pop. Pinned as a permanent GC root so it is never collected.
+VALUE g_empty_sentinel = Qnil;  // Set in Init_ractor_queue
+
+extern "C" void Init_ractor_queue() {
+  // Marks methods registered via rb_define_method (which Rice uses internally for
+  // define_method) as Ractor-safe. Verified working with Rice 4.x on Ruby 4.0 —
+  // cross-Ractor queue access passes without Ractor::IsolationError.
+  rb_ext_ractor_safe(true);
+
+  // Define RactorQueue as the class itself — wraps AtomicQueueB2<VALUE>.
+  // Arg("v").setValue() tells Rice 4.x to treat VALUE as a raw Ruby object
+  // pointer (no conversion). Return().setValue() does the same for return values.
+  Data_Type<StandardQueue> rb_cRQ = define_class<StandardQueue>("RactorQueue")
+    .define_constructor(Constructor<StandardQueue, unsigned>())
+    .define_method("c_try_push", &StandardQueue::try_push,
+                   Arg("v").setValue())
+    .define_method("c_try_pop",  &StandardQueue::try_pop,
+                   Return().setValue())
+    .define_method("capacity",   &StandardQueue::capacity)
+    .define_method("was_size",   &StandardQueue::was_size)
+    .define_method("was_empty",  &StandardQueue::was_empty)
+    .define_method("was_full",   &StandardQueue::was_full);
+
+  // Create the permanent EMPTY_SENTINEL object and pin it as a GC root.
+  g_empty_sentinel = rb_obj_alloc(rb_cObject);
+  rb_obj_freeze(g_empty_sentinel);
+  rb_gc_register_mark_object(g_empty_sentinel);
+  rb_define_const(rb_cRQ, "EMPTY_SENTINEL", g_empty_sentinel);
+
+  // Mark the wrapped C++ type as Ractor-shareable when frozen.
+  // Rice only sets RUBY_TYPED_FREE_IMMEDIATELY; we OR-in RUBY_TYPED_FROZEN_SHAREABLE
+  // so that Ractor.make_shareable(instance) succeeds after Ruby-side freeze.
+  Data_Type<StandardQueue>::ruby_data_type()->flags |= RUBY_TYPED_FROZEN_SHAREABLE;
+
+  // Restore: methods defined after this point (by other code) are not auto-marked Ractor-safe.
+  rb_ext_ractor_safe(false);
+}

data/ext/ractor_queue/standard_queue.h

@@ -0,0 +1,29 @@
+#pragma once
+#include <atomic_queue/atomic_queue.h>
+#include <ruby.h>
+
+// Global sentinel — initialized in Init_ractor_queue, returned by try_pop when empty.
+// Never a valid user-pushed VALUE; only used by the Ruby layer to detect "empty."
+extern VALUE g_empty_sentinel;
+
+class StandardQueue {
+  atomic_queue::AtomicQueueB2<VALUE> q_;
+
+public:
+  explicit StandardQueue(unsigned capacity) : q_(capacity) {}
+
+  // Non-blocking push. Returns true if element was enqueued, false if full.
+  bool try_push(VALUE v) { return q_.try_push(v); }
+
+  // Non-blocking pop. Returns the VALUE if one was available,
+  // or g_empty_sentinel if the queue was empty.
+  VALUE try_pop() {
+    VALUE v;
+    return q_.try_pop(v) ? v : g_empty_sentinel;
+  }
+
+  unsigned capacity()  const { return q_.capacity(); }
+  unsigned was_size()  const { return q_.was_size(); }
+  bool     was_empty() const { return q_.was_empty(); }
+  bool     was_full()  const { return q_.was_full(); }
+};

data/lib/ractor_queue/errors.rb

@@ -0,0 +1,5 @@
+class RactorQueue
+  class Error             < StandardError; end
+  class NotShareableError < Error; end
+  class TimeoutError      < Error; end
+end

data/lib/ractor_queue/interface.rb

@@ -0,0 +1,107 @@
+class RactorQueue
+  module Interface
+    # Non-blocking push. Returns true if enqueued, false if full.
+    def try_push(obj)
+      validate_shareable!(obj) if @validate_shareable
+      c_try_push(obj)
+    end
+
+    # Non-blocking pop. Returns the object, or RactorQueue::EMPTY if the queue
+    # is empty. EMPTY is a unique frozen sentinel distinct from nil, so nil is
+    # an unambiguous payload value.
+    #
+    #   entry = q.try_pop
+    #   if entry.equal?(RactorQueue::EMPTY)
+    #     # queue was empty
+    #   else
+    #     process(entry)   # entry may be nil if nil was pushed
+    #   end
+    def try_pop
+      c_try_pop
+    end
+
+    # Blocking push. Spins until space is available. Returns self.
+    # Raises RactorQueue::TimeoutError if timeout expires.
+    # Ruby interrupt-aware via Thread.pass between retries.
+    def push(obj, timeout: nil)
+      validate_shareable!(obj) if @validate_shareable
+      blocking_push(obj, timeout)
+    end
+
+    # Blocking pop. Spins until an element is available. Returns the object.
+    # Raises RactorQueue::TimeoutError if timeout expires.
+    def pop(timeout: nil)
+      blocking_pop(timeout)
+    end
+
+    # Approximate current element count.
+    def size    = was_size
+
+    # True if queue appears empty (approximate).
+    def empty?  = was_empty
+
+    # True if queue appears full (approximate).
+    def full?   = was_full
+
+    private
+
+    def validate_shareable!(obj)
+      raise NotShareableError, "#{obj.inspect} is not Ractor-shareable" \
+        unless Ractor.shareable?(obj)
+    end
+
+    # Ruby-level spin loop with exponential backoff.
+    #
+    # Phase 1 — Thread.pass (spins 0..SPIN_THRESHOLD-1):
+    #   Cheap busy-wait. Fast when the queue clears quickly (light contention).
+    #   Triggers Ruby interrupt checking, so Thread#raise / Ctrl-C can escape.
+    #
+    # Phase 2 — sleep(SLEEP_INTERVAL) after SPIN_THRESHOLD passes:
+    #   Suspends the OS thread rather than calling sched_yield. Critical inside
+    #   Ractors: each Ractor IS its own OS thread, so Thread.pass only calls
+    #   sched_yield, which under high contention just rotates threads at the
+    #   same priority without making progress. sleep() actually yields the core,
+    #   preventing spin-wait storms when many Ractors share a full/empty queue.
+    #
+    # NOTE: timeout: 0 means "try once, raise if not immediately successful."
+    # The operation is attempted before the deadline check on the first iteration,
+    # so a single try is always made (never a pure no-op raise).
+    SPIN_THRESHOLD = 16
+    SLEEP_INTERVAL = 0.0001  # 100 µs — short enough to keep latency low
+
+    def blocking_push(obj, timeout)
+      deadline = timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout : nil
+      spins = 0
+      loop do
+        return self if c_try_push(obj)
+        raise TimeoutError if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        if spins < SPIN_THRESHOLD
+          spins += 1
+          Thread.pass
+        else
+          sleep(SLEEP_INTERVAL)
+        end
+      end
+    end
+
+    # Ruby-level spin loop for blocking pop (same backoff strategy).
+    # NOTE: timeout: 0 tries once before checking the deadline.
+    def blocking_pop(timeout)
+      deadline = timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout : nil
+      spins = 0
+      loop do
+        result = c_try_pop
+        # No sentinel conversion here — only the sentinel (empty queue) continues the loop;
+        # any actual value (including nil) is returned as-is, consistent with try_pop behavior.
+        return result unless result.equal?(RactorQueue::EMPTY_SENTINEL)
+        raise TimeoutError if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        if spins < SPIN_THRESHOLD
+          spins += 1
+          Thread.pass
+        else
+          sleep(SLEEP_INTERVAL)
+        end
+      end
+    end
+  end
+end

data/lib/ractor_queue/ractor_queue.rb

@@ -0,0 +1,22 @@
+class RactorQueue
+  include Interface
+
+  # Public sentinel returned by try_pop when the queue is empty.
+  # Use equal? (identity) to check — never == — so that nil is an
+  # unambiguous payload.
+  #
+  #   entry = q.try_pop
+  #   return if entry.equal?(RactorQueue::EMPTY)
+  EMPTY = EMPTY_SENTINEL
+
+  # @param capacity [Integer] Maximum number of elements the queue can hold.
+  # @param validate_shareable [Boolean] Raise NotShareableError on non-shareable pushes.
+  def self.new(capacity:, validate_shareable: false)
+    instance = super(capacity)
+    instance.instance_variable_set(:@validate_shareable, validate_shareable)
+    # Make the queue instance itself Ractor-shareable. This deep-freezes the Ruby
+    # wrapper object. The C++ AtomicQueueB2 buffer is not affected by Ruby's freeze.
+    Ractor.make_shareable(instance)
+    instance
+  end
+end

data/lib/ractor_queue/version.rb

@@ -0,0 +1,3 @@
+class RactorQueue
+  VERSION = "0.1.0"
+end

data/lib/ractor_queue.rb

@@ -0,0 +1,5 @@
+require "ractor_queue/ractor_queue.#{RbConfig::CONFIG['DLEXT']}"   # native C extension (Standard, EMPTY_SENTINEL)
+require_relative "ractor_queue/version"
+require_relative "ractor_queue/errors"
+require_relative "ractor_queue/interface"
+require_relative "ractor_queue/ractor_queue"  # Ruby layer (factory)