omq-ractor 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15931abc881035b0cac7d80667168cd3dbdd120226178b76725d2fa40260ac5f
-  data.tar.gz: 82c4e9531bb7afc5e471d435fadb068b0e7cbf92b9a8db70a063c7623a9cb5bc
+  metadata.gz: 4672a215899078075ce99ebd8fdff3b985803dee92e0e17577f9748f2e2a89d0
+  data.tar.gz: 7ca1e9d1cc2470901b2bd17c8a1ef8f4db19e08cb118cde74415c350c06e5f04
 SHA512:
-  metadata.gz: 41ebd53843bb6e69859a6546bc1d6f7926f8e03894c10de1bffdbd2a6d294e282bc1b8c04d735920178ea4b25bdd509d5822fee1979121dc6b307224150785fb
-  data.tar.gz: 7f490382cb90a176d28a1d67e75f4edd5f53b2e10740366d81d49c0f5e73b21e63284ae084b1eb7616a9f54d609d64cc42b2e3ff39738f57e035293f6e8d6963
+  metadata.gz: f9702ec46b247fadeecedec98a4786992bfc4c47dffb01af09643514ffa835ca2747ae013b3a5e7bab5062d07997c4362a267ae4f8ab3c396f5fc8fa8a8cc63e
+  data.tar.gz: 90e3ed42c28560345f9171612029ed85d0f54b67b4ea9e2890da94b28797c4c2855f8b044b7f2c84968bddc974f870e545069a0803ac0c663f50aa884c78ea88

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]
@@ -234,14 +279,20 @@ module OMQ
     # 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|
-          @by_port[proxy.to_port] = proxy if proxy.to_port rescue nil
+          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:
       #
@@ -262,14 +313,32 @@ module OMQ
     # 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>]
@@ -293,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
 
@@ -311,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
@@ -321,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
@@ -356,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
@@ -366,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
@@ -377,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
@@ -507,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
@@ -532,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.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Patrik Wenger