omq-ractor 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '08afc746c52ec650ff7913ac2c58f164b206c547902539949ae2ac1c3e727e45'
+  data.tar.gz: e3ef4264d010e074fabc0076f3ff8fe5f743e940fd07b389b4ab4f84b8db0e17
+SHA512:
+  metadata.gz: 9585c7fc0a48b60f5daf61629ba32850945ee8fd07799b6e09e6f4c35810d13950f67a8c1f08ab7ff42c041c93e6225d176755b91a329c120b1dcba6d461f746
+  data.tar.gz: 8a9295ef54bf9edc729d2e0c47593b8cdf11cc10cfb46bba1f8b004bcd28c89f9b809f3ab9577ef12ef75822773a0db44046a2ed751317278146b3c292ba3194

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026, Patrik Wenger
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,264 @@
+# OMQ::Ractor -- Networked Ractors
+
+Ruby Ractors give you true parallelism -- each Ractor gets its own GVL,
+so CPU-bound work runs on separate cores. But they can only talk to each
+other inside a single process, using `Ractor::Port`. No networking, no
+message patterns, no load balancing.
+
+`OMQ::Ractor` changes that. It connects Ractors to OMQ sockets -- a
+pure Ruby messaging library with TCP, IPC, and in-process transports.
+Your Ractors can now talk across processes, across machines, using
+patterns like load-balanced pipelines, publish/subscribe, and
+request/reply. All in pure Ruby, no C extensions.
+
+The I/O stays in the main Ractor (on the Async fiber scheduler). Worker
+Ractors do pure computation. Messages flow between them transparently,
+serialized per-connection: zero-copy for in-process, Marshal for the
+network.
+
+
+## The problem
+
+Ractors and Async don't mix. `Async::Queue` wraps a `Thread::Queue`
+internally -- it can't be shared between Ractors or even copied into
+one. So you can't just pass an Async queue to a Ractor and have objects
+flow between them.
+
+`Ractor::Port#receive` blocks the fiber scheduler. Calling it inside
+Async freezes the entire reactor -- no other fibers run until the port
+has data. Same for `Ractor#join` and `Ractor#value`.
+
+Without OMQ::Ractor, connecting Ractors to the network means writing
+your own bridge: threads, pipes, queues, serialization, error handling.
+For every direction, every transport.
+
+
+## Usage
+
+```ruby
+require "omq"
+
+Async do
+  pull = OMQ::PULL.bind("tcp://0.0.0.0:5555")
+  push = OMQ::PUSH.connect("tcp://results.internal:5556")
+
+  worker = OMQ::Ractor.new(pull, push) do |omq|
+    pull_p, push_p = omq.sockets  # handshake (must be first call)
+
+    loop do
+      msg = pull_p.receive
+      push_p << expensive_transform(msg)
+    end
+  end
+
+  worker.join
+end
+```
+
+The block runs inside a Ruby Ractor with its own GVL. `omq.sockets`
+performs a setup handshake and returns `SocketProxy` objects --
+lightweight wrappers around `Ractor::Port` pairs.
+
+### Multiplexing with Ractor.select
+
+```ruby
+worker = OMQ::Ractor.new(pull_a, pull_b, push) do |omq|
+  a, b, out = omq.sockets
+
+  loop do
+    source, msg = Ractor.select(a.to_port, b.to_port)
+    out << process(msg)
+  end
+end
+```
+
+### Bidirectional (PAIR, REQ/REP, DEALER)
+
+```ruby
+worker = OMQ::Ractor.new(pair) do |omq|
+  p = omq.sockets.first
+
+  loop do
+    msg = p.receive
+    p << transform(msg)
+  end
+end
+```
+
+### PUB/SUB with topics
+
+```ruby
+worker = OMQ::Ractor.new(pub) do |omq|
+  pub_p = omq.sockets.first
+
+  pub_p << obj                             # all subscribers (empty topic)
+  pub_p.publish(obj, topic: "prices.")     # matching subscribers only
+end
+
+worker = OMQ::Ractor.new(sub) do |omq|
+  sub_p = omq.sockets.first
+
+  obj = sub_p.receive                      # payload only (topic stripped)
+  topic, obj = sub_p.receive_with_topic    # both
+end
+```
+
+Topic prefix matching works normally. The topic stays as a plain string
+frame; only the payload is serialized.
+
+### Worker pool
+
+PUSH round-robins across connected peers. Multiple Ractors on the same
+endpoint = parallel workers:
+
+```ruby
+Async do
+  source = OMQ::PUSH.bind("inproc://work")
+  sink   = OMQ::PULL.bind("inproc://results")
+
+  workers = 4.times.map do
+    pull = OMQ::PULL.connect("inproc://work")
+    push = OMQ::PUSH.connect("inproc://results")
+
+    OMQ::Ractor.new(pull, push) do |omq|
+      p_in, p_out = omq.sockets
+      loop do
+        msg = p_in.receive
+        p_out << expensive_transform(msg)
+      end
+    end
+  end
+
+  # Feed work, collect results
+  100.times { |i| source << job(i) }
+  100.times { sink.receive }
+end
+```
+
+
+## Per-connection serialization
+
+With `serialize: true` (default), messages are automatically converted
+between Ruby objects and wire-format bytes:
+
+    transport   send                        receive
+    ---------   --------------------------  ---------------
+    inproc      Ractor.make_shareable       pass-through
+                (freeze in place, no copy)
+    ipc/tcp     Marshal.dump                Marshal.load
+                (cached for fan-out)
+
+Serialization happens at the connection level, not the socket level. A
+single socket with both inproc and tcp connections serializes differently
+for each.
+
+For ipc/tcp, a SerializeCache ensures fan-out (PUB to N subscribers)
+calls Marshal.dump once per message regardless of subscriber count.
+
+Use `serialize: false` for raw messages (frozen string arrays):
+
+```ruby
+worker = OMQ::Ractor.new(pull, push, serialize: false) do |omq|
+  p_in, p_out = omq.sockets
+  msg = p_in.receive          # frozen string array, e.g. ["hello"]
+  p_out << [msg.first.upcase] # must send frozen string arrays
+end
+```
+
+With `serialize: true`, both ends of a tcp/ipc connection must agree on
+the format. Two OMQ::Ractor instances communicate Ruby objects
+transparently. Mixing Ractor-wrapped and regular sockets over tcp/ipc
+requires `serialize: false`.
+
+
+## Architecture
+
+```
+Main Ractor (Async)                 Worker Ractor
+-------------------                 --------------
+socket.receive ---> input_port ---> proxy.receive
+  (Async fiber)     (worker owns)     (user code)
+
+socket.send    <--- output_port <--- proxy.<<
+  (Async fiber)     (main owns)       (user code)
+      ^
+      |
+  IO.pipe + Thread::Queue
+  (Thread does port.receive,
+   signals Async via pipe)
+```
+
+Input bridge: Async fiber reads from socket, sends to worker's input
+port. Ractor::Port#send is non-blocking, safe in Async.
+
+Output bridge: a Thread reads from the worker's output port
+(port.receive blocks the fiber scheduler, can't be an Async fiber),
+pushes to a Thread::Queue, and signals an Async fiber via IO.pipe. The
+Async fiber drains the queue and feeds the engine directly -- avoiding
+a Reactor.run round-trip per message.
+
+Setup handshake: the worker must call `omq.sockets` as its first
+action. This creates worker-owned input ports, sends them to the main
+Ractor, and returns SocketProxy objects. The main Ractor waits up to
+100ms; if the handshake doesn't complete, the Ractor is stopped and
+an error is raised.
+
+
+## Performance
+
+Inproc, Ruby 4.0.2 +YJIT, 4-core VM. Speedup relative to inline
+(single-core, no Ractor):
+
+```
+                 bare Ractor    OMQ::Ractor
+                 -----------    -----------
+fib(30) ~25ms/call, 200 items:
+  1 worker:        1.0x           0.9x
+  2 workers:       1.7x           1.6x
+  4 workers:       3.1x           2.3x
+
+fib(32) ~61ms/call, 100 items:
+  1 worker:        1.0x           0.8x
+  2 workers:       1.6x           1.4x
+  4 workers:       2.5x           2.2x
+```
+
+Bare Ractors top out around 2.5-3.1x on 4 cores. fib allocates no
+objects (small Integers are immediate values), so this isn't GC -- it's
+Ruby's Ractor overhead itself (YJIT code cache contention, VM internal
+locks, OS thread scheduling). OMQ adds a 5th thread (main reactor)
+competing for 4 cores. The gap narrows with heavier work per message
+(0.8x at 25ms, 0.3x at 61ms).
+
+Bridge overhead (passthrough, no CPU work):
+
+```
+Baseline (no Ractor):  528k msg/s   1.9 us/msg
+OMQ::Ractor:           149k msg/s   6.7 us/msg
+```
+
+Reactor responsiveness during CPU work:
+
+```
+Echo latency while 50x fib(30) crunches in Ractor:
+  p50: 54 us    p95: 3.1 ms (GC)    max: 13 ms (GC)
+
+Without Ractor: reactor blocked for 1252ms
+```
+
+
+## Limitations
+
+- Worker Ractors do pure computation. No Async, no I/O scheduling, no
+  fiber scheduler. All I/O stays in the main Ractor.
+
+- Each OMQ::Ractor wraps its own socket instances. For parallel workers,
+  create multiple Ractors with separate sockets connected to the same
+  endpoint (see worker pool above).
+
+- `omq.sockets` must be the first call in the block. Doing anything else
+  before the handshake triggers a timeout error.
+
+- With `serialize: true` over tcp/ipc, both ends must use OMQ::Ractor
+  (or handle Marshal encoding manually). Use `serialize: false` when
+  talking to regular sockets or non-Ruby peers.

data/lib/omq/ractor.rb

@@ -0,0 +1,516 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "omq"
+
+module OMQ
+  # Bridges OMQ sockets into a Ruby Ractor for true parallel processing.
+  #
+  # Sockets stay in the main Ractor (Async context). Bridge fibers/threads
+  # shuttle messages to/from a worker Ractor. Per-connection serialization
+  # converts between Ruby objects and ZMQ byte frames transparently:
+  # inproc uses Ractor.make_shareable, ipc/tcp use Marshal.
+  #
+  # @example Simple pipeline
+  #   Async do
+  #     pull = OMQ::PULL.new
+  #     pull.bind("tcp://127.0.0.1:5555")
+  #     push = OMQ::PUSH.new
+  #     push.connect("tcp://127.0.0.1:5556")
+  #
+  #     worker = OMQ::Ractor.new(pull, push) do |omq|
+  #       pull_p, push_p = omq.sockets
+  #       loop do
+  #         msg = pull_p.receive
+  #         push_p << transform(msg)
+  #       end
+  #     end
+  #
+  #     worker.join
+  #   end
+  #
+  class Ractor
+
+    HANDSHAKE_TIMEOUT = 0.1
+
+    # Socket types that use topic/group-based routing.
+    # These get topic-aware connection wrappers that preserve
+    # the first frame (topic/group) as a plain string for matching.
+    TOPIC_SOCKET_TYPES = %i[PUB SUB XPUB XSUB RADIO DISH].freeze
+
+
+    # -- Connection wrappers -------------------------------------------
+
+    # Mixed into all connection wrappers so is_a? checks against
+    # the wrapped class (e.g. DirectPipe) still work.
+    #
+    module TransparentDelegator
+      def is_a?(klass)
+        super || __getobj__.is_a?(klass)
+      end
+      alias_method :kind_of?, :is_a?
+    end
+
+
+    # Shared cache for Marshal.dump so fan-out serializes once.
+    # The send pump is single-threaded, so identity check suffices.
+    #
+    class SerializeCache
+      def initialize
+        @last  = nil
+        @bytes = nil
+      end
+
+      def marshal(obj)
+        return @bytes if obj.equal?(@last)
+        @last  = obj
+        @bytes = Marshal.dump(obj).freeze
+      end
+    end
+
+
+    # Wraps a tcp/ipc Connection with transparent Marshal serialization.
+    # Serializes/deserializes the entire parts array.
+    #
+    class MarshalConnection < SimpleDelegator
+      include TransparentDelegator
+
+      def initialize(conn, cache)
+        super(conn)
+        @cache = cache
+      end
+
+      def send_message(parts)
+        super([@cache.marshal(parts)])
+      end
+
+      def write_message(parts)
+        super([@cache.marshal(parts)])
+      end
+
+      def receive_message
+        Marshal.load(super.first)
+      end
+    end
+
+
+    # Wraps an inproc DirectPipe with Ractor.make_shareable.
+    #
+    class ShareableConnection < SimpleDelegator
+      include TransparentDelegator
+
+      def send_message(obj)
+        super(::Ractor.make_shareable(obj))
+      end
+    end
+
+
+    # Topic-aware Marshal wrapper for PUB/XPUB/RADIO (send side).
+    # Preserves parts[0] (topic/group) as a plain string for
+    # subscription matching; serializes parts[1..] (payload).
+    #
+    class TopicMarshalConnection < SimpleDelegator
+      include TransparentDelegator
+
+      def initialize(conn, cache)
+        super(conn)
+        @cache = cache
+      end
+
+      def send_message(parts)
+        super([parts[0], @cache.marshal(parts[1..])])
+      end
+
+      def write_message(parts)
+        super([parts[0], @cache.marshal(parts[1..])])
+      end
+
+      def receive_message
+        parts = super
+        [parts[0], *Marshal.load(parts[1])]
+      end
+    end
+
+
+    # Topic-aware shareable wrapper for inproc PUB/SUB.
+    #
+    class TopicShareableConnection < SimpleDelegator
+      include TransparentDelegator
+
+      def send_message(parts)
+        super(::Ractor.make_shareable(parts))
+      end
+    end
+
+
+    # -- SocketProxy ---------------------------------------------------
+
+    # Raised by SocketProxy#receive after the socket has been closed.
+    # The first receive after closure returns nil; subsequent calls raise.
+    #
+    class SocketClosedError < IOError; end
+
+
+    class SocketProxy
+      def initialize(input_port, output_port, topic_type)
+        @in         = input_port
+        @out        = output_port
+        @topic_type = topic_type
+        @closed     = false
+      end
+
+      # Receives the next message from this socket.
+      # Returns nil once when the socket closes, then raises
+      # SocketClosedError on subsequent calls.
+      #
+      # @return [Object, nil] deserialized message, or nil on close
+      #
+      def receive
+        raise ::Ractor::ClosedError, "not readable" unless @in
+        raise SocketClosedError, "socket closed" if @closed
+        msg = @in.receive
+        if msg.nil?
+          @closed = true
+          return nil
+        end
+        @topic_type ? msg.last : msg
+      end
+
+      # Receives the next message with its topic (PUB/SUB, RADIO/DISH).
+      #
+      # @return [Array(String, Object), nil] [topic, payload], or nil on close
+      #
+      def receive_with_topic
+        raise ::Ractor::ClosedError, "not readable" unless @in
+        raise SocketClosedError, "socket closed" if @closed
+        msg = @in.receive
+        if msg.nil?
+          @closed = true
+          return nil
+        end
+        [msg.first, msg.last]
+      end
+
+      # Sends a message through this socket.
+      # For topic-based sockets, wraps as ["", obj] (all subscribers).
+      #
+      # @param msg [Object] message
+      # @return [self]
+      #
+      def <<(msg)
+        raise ::Ractor::ClosedError, "not writable" unless @out
+        if @topic_type
+          @out.send(["".b.freeze, msg])
+        else
+          @out.send(msg)
+        end
+        self
+      end
+
+      # Publishes a message with an explicit topic (PUB/SUB, RADIO/DISH).
+      #
+      # @param msg [Object] payload
+      # @param topic [String] topic string for subscription matching
+      # @return [self]
+      #
+      def publish(msg, topic:)
+        raise ::Ractor::ClosedError, "not writable" unless @out
+        @out.send([topic.b.freeze, msg])
+        self
+      end
+
+      # Returns the input port for use with Ractor.select.
+      #
+      # @return [Ractor::Port]
+      #
+      def to_port
+        raise ::Ractor::ClosedError, "not readable" unless @in
+        @in
+      end
+    end
+
+
+    # -- Context -------------------------------------------------------
+
+    # Frozen, shareable context passed to the worker Ractor.
+    # The user calls #sockets to trigger the setup handshake.
+    #
+    class Context
+      def initialize(setup_port, output_ports, socket_configs)
+        @setup_port     = setup_port
+        @output_ports   = output_ports
+        @socket_configs = socket_configs
+        ::Ractor.make_shareable(self)
+      end
+
+      # Performs the setup handshake and returns SocketProxy objects.
+      #
+      # @return [Array<SocketProxy>]
+      #
+      def sockets
+        input_ports = @socket_configs.map { |cfg| cfg[:readable] ? ::Ractor::Port.new : nil }
+
+        @setup_port.send(input_ports)
+
+        @socket_configs.each_with_index.map do |cfg, i|
+          SocketProxy.new(input_ports[i], @output_ports[i], cfg[:topic_type])
+        end
+      end
+    end
+
+
+    # -- Constructor ---------------------------------------------------
+
+    # Creates a new OMQ::Ractor that bridges the given sockets into a worker Ractor.
+    #
+    # @param sockets [Array<Socket>] sockets to bridge
+    # @param serialize [Boolean] whether to auto-serialize per connection (default: true)
+    # @yield [Context] block executes inside the worker Ractor;
+    #   must call omq.sockets immediately
+    #
+    def initialize(*sockets, serialize: true, &block)
+      raise ArgumentError, "no sockets given"  if sockets.empty?
+      raise ArgumentError, "no block given"    unless block
+
+      @sockets   = sockets
+      @serialize = serialize
+
+      # Categorize sockets
+      socket_configs = sockets.map do |s|
+        type_sym   = s.class.name.split("::").last.to_sym
+        topic_type = TOPIC_SOCKET_TYPES.include?(type_sym)
+        { readable: s.is_a?(Readable), writable: s.is_a?(Writable),
+          serialize: serialize, topic_type: topic_type }
+      end
+
+      # Main Ractor creates output ports (one per writable socket)
+      @output_ports = socket_configs.map { |cfg| cfg[:writable] ? ::Ractor::Port.new : nil }
+      output_ports  = @output_ports
+
+      # Setup port for the handshake (main-owned, main receives)
+      setup_port = ::Ractor::Port.new
+
+      # Build frozen context for the worker
+      frozen_configs = ::Ractor.make_shareable(socket_configs)
+      frozen_outputs = ::Ractor.make_shareable(output_ports)
+      ctx = Context.new(setup_port, frozen_outputs, frozen_configs)
+
+      # Install connection wrappers for per-connection serialization
+      install_connection_wrappers(socket_configs) if serialize
+
+      # Start the worker Ractor
+      @ractor = ::Ractor.new(ctx, &block)
+
+      # Wait for the handshake with timeout
+      @input_ports = await_handshake(setup_port)
+      input_ports  = @input_ports
+
+      # Start bridges on the correct task.
+      # Inside Async: spawn under current task.
+      # Outside Async: dispatch to the IO thread via Reactor.run.
+      @input_tasks    = []
+      @output_threads = []
+      @output_pipes   = []
+      if Async::Task.current?
+        @parent_task = Async::Task.current
+        start_input_bridges(input_ports, socket_configs)
+        start_output_bridges(output_ports, socket_configs)
+      else
+        @parent_task = Reactor.root_task
+        Reactor.run do
+          start_input_bridges(input_ports, socket_configs)
+          start_output_bridges(output_ports, socket_configs)
+        end
+      end
+    end
+
+
+    # Waits for the worker Ractor to finish naturally.
+    # The worker must return from its block on its own.
+    #
+    def join
+      await_ractor { @ractor.join }
+    ensure
+      cleanup_bridges
+    end
+
+
+    # Returns the worker Ractor's return value.
+    # The worker must return from its block on its own.
+    #
+    def value
+      await_ractor { @ractor.value }
+    ensure
+      cleanup_bridges
+    end
+
+
+    # Signals the worker to stop, then waits for it to finish.
+    # Sends nil through all input ports, causing proxy.receive
+    # to return nil (first time) or raise SocketClosedError.
+    #
+    def close
+      @input_ports.each { |p| p&.send(nil) rescue nil }
+      await_ractor { @ractor.join } rescue nil
+      cleanup_bridges
+    end
+
+
+    private
+
+
+    # Waits for the worker to call omq.sockets (handshake).
+    # Times out after HANDSHAKE_TIMEOUT seconds.
+    #
+    def await_handshake(setup_port)
+      rd, wr = IO.pipe
+      input_ports = nil
+      Thread.new do
+        input_ports = setup_port.receive
+      ensure
+        wr.close
+      end
+      unless rd.wait_readable(HANDSHAKE_TIMEOUT)
+        rd.close
+        @ractor.close rescue nil
+        raise ArgumentError, "worker Ractor must call omq.sockets before doing anything else"
+      end
+      rd.close
+      input_ports
+    end
+
+
+    # Runs a block in a Thread, returning the result via an
+    # IO.pipe so the Async reactor stays responsive.
+    #
+    def await_ractor
+      rd, wr = IO.pipe
+      result = nil
+      error  = nil
+      Thread.new do
+        result = yield
+      rescue => e
+        error = e
+      ensure
+        wr.close
+      end
+      rd.wait_readable
+      rd.close
+      raise error if error
+      result
+    end
+
+
+    def install_connection_wrappers(socket_configs)
+      @sockets.each_with_index do |socket, i|
+        cache      = SerializeCache.new
+        topic_type = socket_configs[i][:topic_type]
+        engine     = socket.instance_variable_get(:@engine)
+
+        engine.connection_wrapper = ->(conn) do
+          inproc = conn.is_a?(Transport::Inproc::DirectPipe)
+          if topic_type
+            inproc ? TopicShareableConnection.new(conn) : TopicMarshalConnection.new(conn, cache)
+          else
+            inproc ? ShareableConnection.new(conn) : MarshalConnection.new(conn, cache)
+          end
+        end
+      end
+    end
+
+
+    # Input bridges: socket -> Ractor (Async fibers).
+    #
+    def start_input_bridges(input_ports, socket_configs)
+      @sockets.each_with_index do |socket, i|
+        port = input_ports[i]
+        next unless port
+
+        do_serialize = socket_configs[i][:serialize]
+        topic_type   = socket_configs[i][:topic_type]
+
+        @input_tasks << @parent_task.async(transient: true, annotation: "ractor input bridge") do
+          loop do
+            msg = socket.receive
+            if do_serialize && !topic_type
+              msg = msg.first
+            end
+            port.send(msg)
+          rescue IOError, Async::Stop
+            port.send(nil) rescue nil
+            break
+          rescue ::Ractor::ClosedError
+            break
+          end
+        end
+      end
+    end
+
+
+    # Output bridges: Ractor -> socket.
+    #
+    # A Thread reads from the Ractor port (blocking, can't run in Async)
+    # and pushes messages to a Thread::Queue. An Async task waits on an
+    # IO.pipe signal and drains the queue directly into the engine --
+    # avoiding the Reactor.run synchronization round-trip per message.
+    #
+    def start_output_bridges(output_ports, socket_configs)
+      @sockets.each_with_index do |socket, i|
+        port = output_ports[i]
+        next unless port
+
+        do_serialize = socket_configs[i][:serialize]
+        topic_type   = socket_configs[i][:topic_type]
+        engine       = socket.instance_variable_get(:@engine)
+        queue        = Thread::Queue.new
+        rd, wr       = IO.pipe
+        @output_pipes << rd << wr
+
+        # Thread: port.receive -> queue + pipe signal
+        @output_threads << Thread.new do
+          loop do
+            msg = port.receive
+            break if msg.equal?(SHUTDOWN)
+            queue << msg
+            wr.write_nonblock("x") rescue nil
+          rescue ::Ractor::ClosedError
+            break
+          end
+          wr.close rescue nil
+        end
+
+        # Async task: wait on pipe, drain queue, enqueue to engine
+        @input_tasks << @parent_task.async(transient: true, annotation: "ractor output bridge") do
+          loop do
+            rd.wait_readable
+            rd.read_nonblock(4096) rescue nil
+
+            while (msg = queue.pop(true) rescue nil)
+              if do_serialize
+                parts = topic_type && msg.is_a?(Array) ? msg : [msg]
+                engine.enqueue_send(parts)
+              else
+                parts = socket.__send__(:freeze_message, msg)
+                engine.enqueue_send(parts)
+              end
+            end
+          rescue IOError, Async::Stop
+            break
+          end
+        end
+      end
+    end
+
+
+    SHUTDOWN = :__omq_ractor_shutdown__
+
+    def cleanup_bridges
+      @input_tasks.each { |t| t.stop rescue nil }
+      # Unblock output bridge Threads waiting on port.receive
+      # (port.close does NOT unblock a waiting receive)
+      @output_ports.each { |p| p&.send(SHUTDOWN) rescue nil }
+      @output_pipes.each { |io| io.close rescue nil }
+      @output_threads.each { |t| t.join(1) }
+    end
+  end
+end

data/lib/omq-ractor.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "omq/ractor"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: omq-ractor
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Patrik Wenger
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/omq-ractor.rb
+- lib/omq/ractor.rb
+homepage: https://github.com/paddor/omq-ractor
+licenses:
+- ISC
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Bridge OMQ sockets into Ruby Ractors for true parallel processing
+test_files: []