omq-ractor 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08afc746c52ec650ff7913ac2c58f164b206c547902539949ae2ac1c3e727e45'
-  data.tar.gz: e3ef4264d010e074fabc0076f3ff8fe5f743e940fd07b389b4ab4f84b8db0e17
+  metadata.gz: 4672a215899078075ce99ebd8fdff3b985803dee92e0e17577f9748f2e2a89d0
+  data.tar.gz: 7ca1e9d1cc2470901b2bd17c8a1ef8f4db19e08cb118cde74415c350c06e5f04
 SHA512:
-  metadata.gz: 9585c7fc0a48b60f5daf61629ba32850945ee8fd07799b6e09e6f4c35810d13950f67a8c1f08ab7ff42c041c93e6225d176755b91a329c120b1dcba6d461f746
-  data.tar.gz: 8a9295ef54bf9edc729d2e0c47593b8cdf11cc10cfb46bba1f8b004bcd28c89f9b809f3ab9577ef12ef75822773a0db44046a2ed751317278146b3c292ba3194
+  metadata.gz: f9702ec46b247fadeecedec98a4786992bfc4c47dffb01af09643514ffa835ca2747ae013b3a5e7bab5062d07997c4362a267ae4f8ab3c396f5fc8fa8a8cc63e
+  data.tar.gz: 90e3ed42c28560345f9171612029ed85d0f54b67b4ea9e2890da94b28797c4c2855f8b044b7f2c84968bddc974f870e545069a0803ac0c663f50aa884c78ea88

data/README.md

@@ -1,5 +1,10 @@
 # OMQ::Ractor -- Networked Ractors
 
+[![CI](https://github.com/paddor/omq-ractor/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/omq-ractor/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/omq-ractor?color=e9573f)](https://rubygems.org/gems/omq-ractor)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%204.0-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+
 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
@@ -45,8 +50,7 @@ Async do
   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
+    while msg = pull_p.receive    # nil on close
       push_p << expensive_transform(msg)
     end
   end
@@ -61,25 +65,36 @@ lightweight wrappers around `Ractor::Port` pairs.
 
 ### Multiplexing with Ractor.select
 
+`Ractor.select` waits on multiple `Ractor::Port` objects and returns
+`[port, value]`. Use `#to_port` to get the underlying port, and
+`#socket_for` to map back to the proxy:
+
 ```ruby
 worker = OMQ::Ractor.new(pull_a, pull_b, push) do |omq|
-  a, b, out = omq.sockets
+  sockets = omq.sockets
+  a, b, out = sockets
 
   loop do
-    source, msg = Ractor.select(a.to_port, b.to_port)
-    out << process(msg)
+    port, msg = Ractor.select(a.to_port, b.to_port)
+    break if msg.nil?  # socket closed
+    source = sockets.socket_for(port)  # => a or b
+    out << process(source, msg)
   end
 end
 ```
 
+Note: `Ractor.select` returns raw port values, bypassing `SocketProxy#receive`.
+For topic-based sockets, `msg` will be the full `[topic, payload]` array --
+use `#receive` or `#receive_with_topic` on a single proxy instead if you
+need topic stripping.
+
 ### Bidirectional (PAIR, REQ/REP, DEALER)
 
 ```ruby
 worker = OMQ::Ractor.new(pair) do |omq|
   p = omq.sockets.first
 
-  loop do
-    msg = p.receive
+  while msg = p.receive
     p << transform(msg)
   end
 end
@@ -122,8 +137,7 @@ Async do
 
     OMQ::Ractor.new(pull, push) do |omq|
       p_in, p_out = omq.sockets
-      loop do
-        msg = p_in.receive
+      while msg = p_in.receive
         p_out << expensive_transform(msg)
       end
     end
@@ -160,8 +174,9 @@ 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
+  while msg = p_in.receive          # frozen string array, e.g. ["hello"]
+    p_out << [msg.first.upcase]     # must send frozen string arrays
+  end
 end
 ```
 

data/lib/omq/ractor.rb

@@ -33,6 +33,7 @@ module OMQ
 
     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.
@@ -45,6 +46,8 @@ module OMQ
     # the wrapped class (e.g. DirectPipe) still work.
     #
     module TransparentDelegator
+      # @param klass [Class] class to check against
+      # @return [Boolean] true if self or the wrapped object is_a? klass
       def is_a?(klass)
         super || __getobj__.is_a?(klass)
       end
@@ -56,11 +59,18 @@ module OMQ
     # The send pump is single-threaded, so identity check suffices.
     #
     class SerializeCache
+      # @return [SerializeCache]
       def initialize
         @last  = nil
         @bytes = nil
       end
 
+
+      # Returns the Marshal-dumped bytes for +obj+, reusing the cached result
+      # if +obj+ is the same object as the last call.
+      #
+      # @param obj [Object] object to serialize
+      # @return [String] frozen Marshal bytes
       def marshal(obj)
         return @bytes if obj.equal?(@last)
         @last  = obj
@@ -75,19 +85,29 @@ module OMQ
     class MarshalConnection < SimpleDelegator
       include TransparentDelegator
 
+      # @param conn [Object] underlying connection to wrap
+      # @param cache [SerializeCache] shared serialization cache
       def initialize(conn, cache)
         super(conn)
         @cache = cache
       end
 
+
+      # @param parts [Array<String>] message frames to serialize and send
+      # @return [void]
       def send_message(parts)
         super([@cache.marshal(parts)])
       end
 
+
+      # @param parts [Array<String>] message frames to serialize and write
+      # @return [void]
       def write_message(parts)
         super([@cache.marshal(parts)])
       end
 
+
+      # @return [Object] deserialized message
       def receive_message
         Marshal.load(super.first)
       end
@@ -99,6 +119,8 @@ module OMQ
     class ShareableConnection < SimpleDelegator
       include TransparentDelegator
 
+      # @param obj [Object] message to freeze and send via Ractor.make_shareable
+      # @return [void]
       def send_message(obj)
         super(::Ractor.make_shareable(obj))
       end
@@ -112,19 +134,29 @@ module OMQ
     class TopicMarshalConnection < SimpleDelegator
       include TransparentDelegator
 
+      # @param conn [Object] underlying connection to wrap
+      # @param cache [SerializeCache] shared serialization cache
       def initialize(conn, cache)
         super(conn)
         @cache = cache
       end
 
+
+      # @param parts [Array<String>] message frames; first frame is topic
+      # @return [void]
       def send_message(parts)
         super([parts[0], @cache.marshal(parts[1..])])
       end
 
+
+      # @param parts [Array<String>] message frames; first frame is topic
+      # @return [void]
       def write_message(parts)
         super([parts[0], @cache.marshal(parts[1..])])
       end
 
+
+      # @return [Array<String>] deserialized message with topic as first element
       def receive_message
         parts = super
         [parts[0], *Marshal.load(parts[1])]
@@ -137,6 +169,8 @@ module OMQ
     class TopicShareableConnection < SimpleDelegator
       include TransparentDelegator
 
+      # @param parts [Array<String>] message frames to freeze and send
+      # @return [void]
       def send_message(parts)
         super(::Ractor.make_shareable(parts))
       end
@@ -148,10 +182,16 @@ module OMQ
     # 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 SocketClosedError < IOError
+    end
 
 
+    # Ractor-side proxy for an OMQ socket. Provides #receive, #<<, and #publish
+    # to communicate with the main-thread socket through Ractor ports.
     class SocketProxy
+      # @param input_port [Ractor::Port, nil] port for receiving messages (nil if write-only)
+      # @param output_port [Ractor::Port, nil] port for sending messages (nil if read-only)
+      # @param topic_type [Boolean] whether this is a topic-based socket (PUB/SUB, RADIO/DISH)
       def initialize(input_port, output_port, topic_type)
         @in         = input_port
         @out        = output_port
@@ -159,6 +199,7 @@ module OMQ
         @closed     = false
       end
 
+
       # Receives the next message from this socket.
       # Returns nil once when the socket closes, then raises
       # SocketClosedError on subsequent calls.
@@ -176,6 +217,7 @@ module OMQ
         @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
@@ -191,6 +233,7 @@ module OMQ
         [msg.first, msg.last]
       end
 
+
       # Sends a message through this socket.
       # For topic-based sockets, wraps as ["", obj] (all subscribers).
       #
@@ -207,6 +250,7 @@ module OMQ
         self
       end
 
+
       # Publishes a message with an explicit topic (PUB/SUB, RADIO/DISH).
       #
       # @param msg [Object] payload
@@ -219,6 +263,7 @@ module OMQ
         self
       end
 
+
       # Returns the input port for use with Ractor.select.
       #
       # @return [Ractor::Port]
@@ -230,19 +275,70 @@ module OMQ
     end
 
 
+    # Array of SocketProxy objects with a port→proxy lookup for
+    # Ractor.select results.
+    #
+    class SocketSet < Array
+      # @param proxies [Array<SocketProxy>] socket proxies to include
+      def initialize(proxies)
+        super(proxies)
+        @by_port = {}
+        proxies.each do |proxy|
+          begin
+            @by_port[proxy.to_port] = proxy if proxy.to_port
+          rescue ::Ractor::ClosedError
+            # Skip non-readable proxies.
+          end
+        end
+      end
+
+
+      # Returns the SocketProxy whose input port matches +port+.
+      # Use after Ractor.select to map back to the proxy:
+      #
+      #   port, msg = Ractor.select(a.to_port, b.to_port)
+      #   source = sockets.socket_for(port)
+      #
+      # @param port [Ractor::Port]
+      # @return [SocketProxy, nil]
+      #
+      def socket_for(port)
+        @by_port[port]
+      end
+    end
+
+
     # -- Context -------------------------------------------------------
 
     # Frozen, shareable context passed to the worker Ractor.
     # The user calls #sockets to trigger the setup handshake.
     #
+    # An optional +data+ object (any Ractor.make_shareable-able value)
+    # can be passed via OMQ::Ractor.new(data: …) and retrieved inside
+    # the worker block with +omq.data+. This is the only way to pass
+    # extra information into a worker block under Ruby 4.0's strict
+    # Ractor isolation, which forbids capturing any outer local variable.
+    #
     class Context
-      def initialize(setup_port, output_ports, socket_configs)
+      # @param setup_port [Ractor::Port] port for the setup handshake
+      # @param output_ports [Array<Ractor::Port, nil>] output ports for writable sockets
+      # @param socket_configs [Array<Hash>] per-socket configuration hashes
+      # @param data [Object, nil] optional shareable data for the worker
+      def initialize(setup_port, output_ports, socket_configs, data: nil)
         @setup_port     = setup_port
         @output_ports   = output_ports
         @socket_configs = socket_configs
+        @data           = data
         ::Ractor.make_shareable(self)
       end
 
+
+      # User-supplied shareable data (passed as +data:+ to OMQ::Ractor.new).
+      #
+      # @return [Object, nil]
+      #
+      attr_reader :data
+
       # Performs the setup handshake and returns SocketProxy objects.
       #
       # @return [Array<SocketProxy>]
@@ -252,9 +348,10 @@ module OMQ
 
         @setup_port.send(input_ports)
 
-        @socket_configs.each_with_index.map do |cfg, i|
+        proxies = @socket_configs.each_with_index.map do |cfg, i|
           SocketProxy.new(input_ports[i], @output_ports[i], cfg[:topic_type])
         end
+        SocketSet.new(proxies)
       end
     end
 
@@ -265,10 +362,14 @@ module OMQ
     #
     # @param sockets [Array<Socket>] sockets to bridge
     # @param serialize [Boolean] whether to auto-serialize per connection (default: true)
+    # @param data [Object, nil] optional shareable data accessible as +omq.data+
+    #   inside the worker block. Under Ruby 4.0's strict Ractor isolation,
+    #   worker blocks cannot close over outer local variables; use +data:+ to
+    #   pass configuration into the block.
     # @yield [Context] block executes inside the worker Ractor;
     #   must call omq.sockets immediately
     #
-    def initialize(*sockets, serialize: true, &block)
+    def initialize(*sockets, serialize: true, data: nil, &block)
       raise ArgumentError, "no sockets given"  if sockets.empty?
       raise ArgumentError, "no block given"    unless block
 
@@ -283,6 +384,7 @@ module OMQ
           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
@@ -293,7 +395,8 @@ module OMQ
       # 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)
+      frozen_data    = data ? ::Ractor.make_shareable(data) : nil
+      ctx = Context.new(setup_port, frozen_outputs, frozen_configs, data: frozen_data)
 
       # Install connection wrappers for per-connection serialization
       install_connection_wrappers(socket_configs) if serialize
@@ -328,6 +431,7 @@ module OMQ
     # Waits for the worker Ractor to finish naturally.
     # The worker must return from its block on its own.
     #
+    # @return [void]
     def join
       await_ractor { @ractor.join }
     ensure
@@ -338,6 +442,7 @@ module OMQ
     # Returns the worker Ractor's return value.
     # The worker must return from its block on its own.
     #
+    # @return [Object] the worker block's return value
     def value
       await_ractor { @ractor.value }
     ensure
@@ -349,6 +454,7 @@ module OMQ
     # Sends nil through all input ports, causing proxy.receive
     # to return nil (first time) or raise SocketClosedError.
     #
+    # @return [void]
     def close
       @input_ports.each { |p| p&.send(nil) rescue nil }
       await_ractor { @ractor.join } rescue nil
@@ -479,6 +585,7 @@ module OMQ
           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
@@ -504,6 +611,7 @@ module OMQ
 
     SHUTDOWN = :__omq_ractor_shutdown__
 
+
     def cleanup_bridges
       @input_tasks.each { |t| t.stop rescue nil }
       # Unblock output bridge Threads waiting on port.receive

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-ractor
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Patrik Wenger