omq 0.5.1 → 0.6.1

data/lib/omq/zmtp/routing/push.rb

@@ -16,37 +16,44 @@ module OMQ
           init_round_robin(engine)
         end
 
+
         # @return [Async::LimitedQueue]
         #
         attr_reader :send_queue
 
+
         # PUSH is write-only.
         #
         def recv_queue
           raise "PUSH sockets cannot receive"
         end
 
+
         # @param connection [Connection]
         #
         def connection_added(connection)
           @connections << connection
           signal_connection_available
           start_send_pump unless @send_pump_started
-          start_monitor(connection)
+          start_reaper(connection)
         end
 
+
         # @param connection [Connection]
         #
         def connection_removed(connection)
           @connections.delete(connection)
         end
 
+
         # @param parts [Array<String>]
         #
         def enqueue(parts)
           @send_queue.enqueue(parts)
         end
 
+
+        # Stops all background tasks (send pump, reapers).
         #
         def stop
           @tasks.each(&:stop)
@@ -55,13 +62,13 @@ module OMQ
 
         private
 
-        # Monitors a connection for disconnection.
-        # Write-only sockets have no recv pump, so without this monitor
-        # a dead peer is only detected on the next send — which may
-        # succeed if the kernel send buffer absorbs the data.
+
+        # Detects peer disconnection on write-only sockets. Without
+        # this, a dead peer is only noticed on the next send — which
+        # may succeed if the kernel send buffer absorbs the data.
         #
-        def start_monitor(conn)
-          @tasks << Reactor.spawn_pump do
+        def start_reaper(conn)
+          @tasks << Reactor.spawn_pump(annotation: "reaper") do
             conn.receive_message # blocks until peer disconnects
           rescue *ZMTP::CONNECTION_LOST
             @engine.connection_lost(conn)

data/lib/omq/zmtp/routing/radio.rb

@@ -21,6 +21,7 @@ module OMQ
           @groups            = {} # connection => Set of joined groups
           @send_queue        = Async::LimitedQueue.new(engine.options.send_hwm)
           @send_pump_started = false
+          @conflate          = engine.options.conflate
           @tasks             = []
         end
 
@@ -67,23 +68,44 @@ module OMQ
 
         def start_send_pump
           @send_pump_started = true
-          @tasks << Reactor.spawn_pump do
+          @tasks << @engine.spawn_pump_task(annotation: "send pump") do
             loop do
+              @send_pump_idle = true
               batch = [@send_queue.dequeue]
+              @send_pump_idle = false
               Routing.drain_send_queue(@send_queue, batch)
 
               written = Set.new
-              batch.each do |parts|
-                group = parts[0]
-                body  = parts[1] || "".b
-                @connections.each do |conn|
-                  next unless @groups[conn]&.include?(group)
+
+              if @conflate
+                # Keep only the last matching message per connection.
+                latest = {} # conn => [group, body]
+                batch.each do |parts|
+                  group = parts[0]
+                  body  = parts[1] || "".b
+                  @connections.each do |conn|
+                    next unless @groups[conn]&.include?(group)
+                    latest[conn] = [group, body]
+                  end
+                end
+                latest.each do |conn, msg|
                   begin
-                    # Wire format: group frame (MORE) + body frame
-                    conn.write_message([group, body])
+                    conn.write_message(msg)
                     written << conn
                   rescue *ZMTP::CONNECTION_LOST
-                    # connection dead — will be cleaned up
+                  end
+                end
+              else
+                batch.each do |parts|
+                  group = parts[0]
+                  body  = parts[1] || "".b
+                  @connections.each do |conn|
+                    next unless @groups[conn]&.include?(group)
+                    begin
+                      conn.write_message([group, body])
+                      written << conn
+                    rescue *ZMTP::CONNECTION_LOST
+                    end
                   end
                 end
               end
@@ -91,14 +113,13 @@ module OMQ
               written.each do |conn|
                 conn.flush
               rescue *ZMTP::CONNECTION_LOST
-                # connection dead — will be cleaned up
               end
             end
           end
         end
 
         def start_group_listener(conn)
-          @tasks << Reactor.spawn_pump do
+          @tasks << Reactor.spawn_pump(annotation: "recv pump") do
             loop do
               frame = conn.read_frame
               next unless frame.command?

data/lib/omq/zmtp/routing/rep.rb

@@ -19,6 +19,7 @@ module OMQ
           @pending_replies   = []
           @tasks             = []
           @send_pump_started = false
+          @send_pump_idle    = true
         end
 
         # @return [Async::LimitedQueue]
@@ -29,13 +30,11 @@ module OMQ
         #
         def connection_added(connection)
           transform = ->(msg) {
-            envelope = []
-            while msg.first && !msg.first.empty?
-              envelope << msg.shift
-            end
-            msg.shift # remove empty delimiter
+            delimiter = msg.index(&:empty?) || msg.size
+            envelope  = msg[0, delimiter]
+            body      = msg[(delimiter + 1)..] || []
             @pending_replies << { conn: connection, envelope: envelope }
-            msg
+            body
           }
           task = @engine.start_recv_pump(connection, @recv_queue, transform: transform)
           @tasks << task if task
@@ -64,11 +63,16 @@ module OMQ
 
         private
 
+        def send_pump_idle? = @send_pump_idle
+
+
         def start_send_pump
           @send_pump_started = true
-          @tasks << Reactor.spawn_pump do
+          @tasks << @engine.spawn_pump_task(annotation: "send pump") do
             loop do
+              @send_pump_idle = true
               batch = [@send_queue.dequeue]
+              @send_pump_idle = false
               Routing.drain_send_queue(@send_queue, batch)
 
               written = Set.new

data/lib/omq/zmtp/routing/req.rb

@@ -61,8 +61,7 @@ module OMQ
         # REQ strips the leading empty delimiter frame on receive.
         #
         def transform_recv(msg)
-          msg.shift if msg.first&.empty?
-          msg
+          msg.first&.empty? ? msg[1..] : msg
         end
       end
     end

data/lib/omq/zmtp/routing/round_robin.rb

@@ -15,20 +15,31 @@ module OMQ
       module RoundRobin
         private
 
+
+        # Initializes round-robin state for the including class.
+        #
+        # @param engine [Engine]
+        #
         def init_round_robin(engine)
           @connections          = []
           @cycle                = @connections.cycle
           @connection_available = Async::Promise.new
           @send_queue           = Async::LimitedQueue.new(engine.options.send_hwm)
           @send_pump_started    = false
+          @send_pump_idle       = true
         end
 
+
+        # Resolves the connection-available promise so blocked
+        # senders can proceed.
+        #
         def signal_connection_available
           unless @connection_available.resolved?
             @connection_available.resolve(true)
           end
         end
 
+
         # Blocks until a connection is available, then returns
         # the next one in round-robin order.
         #
@@ -43,6 +54,7 @@ module OMQ
           retry
         end
 
+
         # Transforms parts before sending. Override in subclasses
         # (e.g. REQ prepends an empty delimiter frame).
         #
@@ -51,11 +63,21 @@ module OMQ
         #
         def transform_send(parts) = parts
 
+
+        # Starts the background send pump that dequeues messages
+        # and dispatches them round-robin across connections.
+        #
+        # @return [Boolean] true when the send pump is idle (not sending a batch)
+        def send_pump_idle? = @send_pump_idle
+
+
         def start_send_pump
           @send_pump_started = true
-          @tasks << Reactor.spawn_pump do
+          @tasks << @engine.spawn_pump_task(annotation: "send pump") do
             loop do
+              @send_pump_idle = true
               batch = [@send_queue.dequeue]
+              @send_pump_idle = false
               Routing.drain_send_queue(@send_queue, batch)
 
               if batch.size == 1
@@ -67,6 +89,12 @@ module OMQ
           end
         end
 
+
+        # Sends a single message, retrying on a new connection if
+        # the current one is lost.
+        #
+        # @param parts [Array<String>]
+        #
         def send_with_retry(parts)
           conn = next_connection
           conn.send_message(transform_send(parts))
@@ -75,6 +103,12 @@ module OMQ
           retry
         end
 
+
+        # Sends a batch of messages, writing without flushing for
+        # throughput. Falls back to #send_with_retry on failure.
+        #
+        # @param batch [Array<Array<String>>]
+        #
         def send_batch(batch)
           written = Set.new
           batch.each_with_index do |parts, i|

data/lib/omq/zmtp/routing/router.rb

@@ -21,6 +21,7 @@ module OMQ
           @connections_by_identity = {}
           @tasks                   = []
           @send_pump_started       = false
+          @send_pump_idle          = true
         end
 
         # @return [Async::LimitedQueue]
@@ -68,11 +69,16 @@ module OMQ
 
         private
 
+        def send_pump_idle? = @send_pump_idle
+
+
         def start_send_pump
           @send_pump_started = true
-          @tasks << Reactor.spawn_pump do
+          @tasks << @engine.spawn_pump_task(annotation: "send pump") do
             loop do
+              @send_pump_idle = true
               batch = [@send_queue.dequeue]
+              @send_pump_idle = false
               Routing.drain_send_queue(@send_queue, batch)
 
               written = Set.new

data/lib/omq/zmtp/routing/scatter.rb

@@ -16,37 +16,44 @@ module OMQ
           init_round_robin(engine)
         end
 
+
         # @return [Async::LimitedQueue]
         #
         attr_reader :send_queue
 
+
         # SCATTER is write-only.
         #
         def recv_queue
           raise "SCATTER sockets cannot receive"
         end
 
+
         # @param connection [Connection]
         #
         def connection_added(connection)
           @connections << connection
           signal_connection_available
           start_send_pump unless @send_pump_started
-          start_monitor(connection)
+          start_reaper(connection)
         end
 
+
         # @param connection [Connection]
         #
         def connection_removed(connection)
           @connections.delete(connection)
         end
 
+
         # @param parts [Array<String>]
         #
         def enqueue(parts)
           @send_queue.enqueue(parts)
         end
 
+
+        # Stops all background tasks (send pump, reapers).
         #
         def stop
           @tasks.each(&:stop)
@@ -55,8 +62,14 @@ module OMQ
 
         private
 
-        def start_monitor(conn)
-          @tasks << Reactor.spawn_pump do
+
+        # Detects peer disconnection on write-only sockets by
+        # blocking on a receive that only returns on disconnect.
+        #
+        # @param conn [Connection]
+        #
+        def start_reaper(conn)
+          @tasks << Reactor.spawn_pump(annotation: "reaper") do
             conn.receive_message
           rescue *ZMTP::CONNECTION_LOST
             @engine.connection_lost(conn)

data/lib/omq/zmtp/routing/server.rb

@@ -21,6 +21,7 @@ module OMQ
           @connections_by_routing_id  = {}
           @tasks                      = []
           @send_pump_started          = false
+          @send_pump_idle             = true
         end
 
         # @return [Async::LimitedQueue]
@@ -59,11 +60,16 @@ module OMQ
 
         private
 
+        def send_pump_idle? = @send_pump_idle
+
+
         def start_send_pump
           @send_pump_started = true
-          @tasks << Reactor.spawn_pump do
+          @tasks << @engine.spawn_pump_task(annotation: "send pump") do
             loop do
+              @send_pump_idle = true
               batch = [@send_queue.dequeue]
+              @send_pump_idle = false
               Routing.drain_send_queue(@send_queue, batch)
 
               written = Set.new

data/lib/omq/zmtp/routing/xsub.rb

@@ -19,6 +19,7 @@ module OMQ
           @send_queue        = Async::LimitedQueue.new(engine.options.send_hwm)
           @tasks             = []
           @send_pump_started = false
+          @send_pump_idle    = true
         end
 
         # @return [Async::LimitedQueue]
@@ -54,11 +55,16 @@ module OMQ
 
         private
 
+        def send_pump_idle? = @send_pump_idle
+
+
         def start_send_pump
           @send_pump_started = true
-          @tasks << Reactor.spawn_pump do
+          @tasks << @engine.spawn_pump_task(annotation: "send pump") do
             loop do
+              @send_pump_idle = true
               parts = @send_queue.dequeue
+              @send_pump_idle = false
               frame = parts.first&.b
               next if frame.nil? || frame.empty?
 

data/lib/omq/zmtp/transport/inproc.rb

@@ -46,6 +46,7 @@ module OMQ
             Listener.new(endpoint)
           end
 
+
           # Connects to a bound inproc endpoint.
           #
           # @param endpoint [String] e.g. "inproc://my-endpoint"
@@ -76,6 +77,7 @@ module OMQ
             establish_link(engine, bound_engine, endpoint)
           end
 
+
           # Removes a bound endpoint from the registry.
           #
           # @param endpoint [String]
@@ -85,6 +87,7 @@ module OMQ
             @mutex.synchronize { @registry.delete(endpoint) }
           end
 
+
           # Resets the registry. Used in tests.
           #
           # @return [void]
@@ -96,8 +99,17 @@ module OMQ
             end
           end
 
+
           private
 
+
+          # Wires up a client-server inproc pipe pair after validating
+          # that the two socket types are compatible.
+          #
+          # @param client_engine [Engine] the connecting engine
+          # @param server_engine [Engine] the bound engine
+          # @param endpoint [String] the inproc endpoint name
+          #
           def establish_link(client_engine, server_engine, endpoint)
             client_type = client_engine.socket_type
             server_type = server_engine.socket_type
@@ -138,8 +150,15 @@ module OMQ
             server_engine.connection_ready(server_pipe, endpoint: endpoint)
           end
 
+
+          # Spawns a background task that periodically retries
+          # #establish_link until the endpoint appears in the registry.
+          #
+          # @param endpoint [String] the inproc endpoint name
+          # @param engine [Engine] the connecting engine
+          #
           def start_connect_retry(endpoint, engine)
-            Reactor.spawn_pump do
+            Reactor.spawn_pump(annotation: "reconnect") do
               ri  = engine.options.reconnect_interval
               ivl = ri.is_a?(Range) ? ri.begin : ri
               loop do
@@ -161,12 +180,14 @@ module OMQ
           #
           attr_reader :endpoint
 
+
           # @param endpoint [String]
           #
           def initialize(endpoint)
             @endpoint = endpoint
           end
 
+
           # Stops the listener by removing it from the registry.
           #
           # @return [void]
@@ -183,32 +204,38 @@ module OMQ
         #
         # When a routing strategy sets {#direct_recv_queue} on a pipe,
         # {#send_message} enqueues directly into the peer's recv queue,
-        # bypassing the intermediate internal queues and the recv pump
-        # task entirely.  This reduces inproc from 3 queue hops to 1.
+        # bypassing the intermediate pipe queues and the recv pump task.
+        # This reduces inproc from 3 queue hops to 2 (send_queue →
+        # recv_queue), eliminating the internal pipe queue in between.
         #
         class DirectPipe
           # @return [String] peer's socket type
           #
           attr_reader :peer_socket_type
 
+
           # @return [String] peer's identity
           #
           attr_reader :peer_identity
 
+
           # @return [DirectPipe, nil] the other end of this pipe pair
           #
           attr_accessor :peer
 
+
           # @return [Async::LimitedQueue, nil] when set, {#send_message}
           #   enqueues directly here instead of using the internal queue
           #
           attr_reader :direct_recv_queue
 
+
           # @return [Proc, nil] optional transform applied before
           #   enqueuing into {#direct_recv_queue}
           #
           attr_accessor :direct_recv_transform
 
+
           # @param send_queue [Async::Queue, nil] outgoing command queue
           #   (nil for non-PUB/SUB types that don't exchange commands)
           # @param receive_queue [Async::Queue, nil] incoming command queue
@@ -227,6 +254,7 @@ module OMQ
             @pending_direct        = nil
           end
 
+
           # Sets the direct recv queue. Drains any messages that were
           # buffered before the queue was available.
           #
@@ -240,6 +268,7 @@ module OMQ
             end
           end
 
+
           # Sends a multi-frame message.
           #
           # When {#direct_recv_queue} is set (inproc fast path), the
@@ -252,24 +281,27 @@ module OMQ
           def send_message(parts)
             raise IOError, "closed" if @closed
             if @direct_recv_queue
-              msg = @direct_recv_transform ? @direct_recv_transform.call(parts) : parts
+              msg = @direct_recv_transform ? @direct_recv_transform.call(parts).freeze : parts
               @direct_recv_queue.enqueue(msg)
             elsif @send_queue
               @send_queue.enqueue(parts)
             else
-              msg = @direct_recv_transform ? @direct_recv_transform.call(parts) : parts
+              msg = @direct_recv_transform ? @direct_recv_transform.call(parts).freeze : parts
               (@pending_direct ||= []) << msg
             end
           end
 
+
           alias write_message send_message
 
+
           # No-op — inproc has no IO buffer to flush.
           #
           # @return [void]
           #
           def flush = nil
 
+
           # Receives a multi-frame message.
           #
           # @return [Array<String>]
@@ -281,6 +313,7 @@ module OMQ
             msg
           end
 
+
           # Sends a command via the internal command queue.
           # Only available for PUB/SUB-family pipes.
           #
@@ -292,6 +325,7 @@ module OMQ
             @send_queue.enqueue([:command, command])
           end
 
+
           # Reads one command frame from the internal command queue.
           # Used by PUB/XPUB subscription listeners.
           #
@@ -308,6 +342,7 @@ module OMQ
             end
           end
 
+
           # Closes this pipe end.
           #
           # @return [void]

data/lib/omq/zmtp/transport/ipc.rb

@@ -28,16 +28,11 @@ module OMQ
 
             server = UNIXServer.new(sock_path)
 
-            accept_task = Reactor.spawn_pump do
+            accept_task = Reactor.spawn_pump(annotation: "ipc accept #{endpoint}") do
               loop do
                 client = server.accept
-                Reactor.run do
+                Async::Task.current.defer_stop do
                   engine.handle_accepted(IO::Stream::Buffered.wrap(client), endpoint: endpoint)
-                rescue ProtocolError, *ZMTP::CONNECTION_LOST
-                  # peer disconnected during handshake
-                rescue
-                  client&.close rescue nil
-                  raise
                 end
               end
             rescue IOError
@@ -92,6 +87,12 @@ module OMQ
           #
           attr_reader :endpoint
 
+
+          # @param endpoint [String] the IPC endpoint URI
+          # @param server [UNIXServer]
+          # @param accept_task [#stop] the accept loop handle
+          # @param path [String] filesystem or abstract namespace path
+          #
           def initialize(endpoint, server, accept_task, path)
             @endpoint = endpoint
             @server = server
@@ -99,6 +100,7 @@ module OMQ
             @path = path
           end
 
+
           # Stops the listener.
           #
           def stop