omq 0.17.9 → 0.18.0

data/lib/omq/router_dealer.rb

@@ -12,8 +12,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, backend: nil)
-      _init_engine(:DEALER, linger: linger, backend: backend)
-      _attach(endpoints, default: :connect)
+      init_engine(:DEALER, linger: linger, backend: backend)
+      attach_endpoints(endpoints, default: :connect)
     end
   end
 
@@ -29,8 +29,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, backend: nil)
-      _init_engine(:ROUTER, linger: linger, backend: backend)
-      _attach(endpoints, default: :bind)
+      init_engine(:ROUTER, linger: linger, backend: backend)
+      attach_endpoints(endpoints, default: :bind)
     end
 
 

data/lib/omq/routing/conn_send_pump.rb

@@ -21,15 +21,21 @@ module OMQ
           loop do
             batch = [q.dequeue]
             Routing.drain_send_queue(q, batch)
+
             if batch.size == 1
-              conn.write_message(batch[0])
+              conn.write_message batch.first
             else
-              conn.write_messages(batch)
+              conn.write_messages batch
             end
+
             conn.flush
-            batch.each { |parts| engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
+
+            batch.each do |parts|
+              engine.emit_verbose_monitor_event :message_sent, parts: parts
+            end
           end
         end
+
         tasks << task
         task
       end

data/lib/omq/routing/dealer.rb

@@ -10,6 +10,7 @@ module OMQ
       include RoundRobin
       include FairRecv
 
+
       # @param engine [Engine]
       #
       def initialize(engine)
@@ -24,6 +25,7 @@ module OMQ
       #
       attr_reader :recv_queue
 
+
       # @param connection [Connection]
       #
       def connection_added(connection)

data/lib/omq/routing/fair_queue.rb

@@ -104,8 +104,10 @@ module OMQ
         @drain.empty? && @queues.all?(&:empty?)
       end
 
+
       private
 
+
       # Drains orphaned queues first (preserves FIFO for disconnected
       # peers), then tries each active queue once in round-robin order.
       #
@@ -162,16 +164,25 @@ module OMQ
       # @param timeout [Numeric, nil] dequeue timeout
       # @return [Array<String>, nil]
       #
-      def dequeue(timeout: nil) = @inner.dequeue(timeout: timeout)
+      def dequeue(timeout: nil)
+        @inner.dequeue(timeout: timeout)
+      end
+
 
       # @return [Boolean]
       #
-      def empty?                = @inner.empty?
+      def empty?
+        @inner.empty?
+      end
+
 
       # @param item [Object, nil]
       # @return [void]
       #
-      def push(item)            = @inner.push(item)
+      def push(item)
+        @inner.push(item)
+      end
+
     end
   end
 end

data/lib/omq/routing/fan_out.rb

@@ -17,18 +17,25 @@ module OMQ
     # their #initialize.
     #
     module FanOut
+      # Shared frozen empty binary string to avoid repeated allocations.
+      EMPTY_BINARY = ::Protocol::ZMTP::Codec::EMPTY_BINARY
+
+
       # @return [Async::Promise] resolves when the first subscriber joins
       #
       attr_reader :subscriber_joined
 
+
       # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?
         @conn_queues.values.all?(&:empty?)
       end
 
+
       private
 
+
       def init_fan_out(engine)
         @connections        = Set.new
         @subscriptions      = {} # connection => Set of prefixes
@@ -156,6 +163,15 @@ module OMQ
       end
 
 
+      # Send pump variant for non-conflate fan-out: dequeues, batch-drains,
+      # writes each subscribed message, then flushes once.
+      #
+      # @param conn [Connection]
+      # @param q [Async::LimitedQueue, DropQueue]
+      # @param use_wire [Boolean] true iff the encoded wire bytes can
+      #   be shared across peers (unencrypted ZMTP)
+      # @return [Async::Task]
+      #
       def start_conn_send_pump_normal(conn, q, use_wire)
         @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
@@ -170,31 +186,52 @@ module OMQ
       end
 
 
+      # Writes every batch entry whose topic matches a subscription on
+      # +conn+ to +conn+'s write buffer. Does not flush.
+      #
+      # @return [Boolean] true iff at least one message was written
+      #
       def write_matching_batch(conn, batch, use_wire)
         sent = false
         batch.each do |parts|
           next unless subscribed?(conn, parts.first || EMPTY_BINARY)
-          use_wire ? conn.write_wire(Protocol::ZMTP::Codec::Frame.encode_message(parts)) : conn.write_message(parts)
+          if use_wire
+            conn.write_wire(Protocol::ZMTP::Codec::Frame.encode_message(parts))
+          else
+            conn.write_message(parts)
+          end
           sent = true
         end
         sent
       end
 
 
+      # Send pump variant for conflate mode: keeps only the latest
+      # subscribed message per batch. Stale duplicates are dropped.
+      #
+      # @param conn [Connection]
+      # @param q [Async::LimitedQueue, DropQueue]
+      # @return [Async::Task]
+      #
       def start_conn_send_pump_conflate(conn, q)
         @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             batch = [q.dequeue]
             Routing.drain_send_queue(q, batch)
+
             # Keep only the latest message that matches the subscription.
-            latest = batch.reverse.find { |parts| subscribed?(conn, parts.first || EMPTY_BINARY) }
+            latest = batch.reverse.find do |parts|
+              subscribed?(conn, parts.first || EMPTY_BINARY)
+            end
             next unless latest
+
             conn.write_message(latest)
             conn.flush
             @engine.emit_verbose_monitor_event(:message_sent, parts: latest)
           end
         end
       end
+
     end
   end
 end

data/lib/omq/routing/req.rb

@@ -10,6 +10,10 @@ module OMQ
       include RoundRobin
       include FairRecv
 
+      # Shared frozen empty binary string to avoid repeated allocations.
+      EMPTY_BINARY = ::Protocol::ZMTP::Codec::EMPTY_BINARY
+
+
       # @param engine [Engine]
       #
       def initialize(engine)
@@ -64,11 +68,16 @@ module OMQ
         @tasks.clear
       end
 
+
       private
 
+
       # REQ prepends empty delimiter frame on the wire.
       #
-      def transform_send(parts) = [EMPTY_BINARY, *parts]
+      def transform_send(parts)
+        [EMPTY_BINARY, *parts]
+      end
+
     end
   end
 end

data/lib/omq/routing.rb

@@ -15,16 +15,17 @@ module OMQ
   # the socket's send/recv queues.
   #
   module Routing
-    # Shared frozen empty binary string to avoid repeated allocations.
-    EMPTY_BINARY = "".b.freeze
-
-
     # Plugin registry for socket types not built into omq.
     # Populated by sister gems via +Routing.register+.
     #
     @registry = {}
 
+
     class << self
+      # @return [Hash{Symbol => Class}] plugin registry
+      attr_reader :registry
+
+
       # Registers a routing strategy class for a socket type.
       # Called by omq-draft (and other plugins) at require time.
       #

data/lib/omq/socket.rb

@@ -88,7 +88,7 @@ module OMQ
     def bind(endpoint, parent: nil)
       ensure_parent_task(parent: parent)
       Reactor.run do
-        @engine.bind(endpoint)
+        @engine.bind(endpoint) # TODO: use timeout?
         @last_tcp_port = @engine.last_tcp_port
       end
     end
@@ -102,7 +102,7 @@ module OMQ
     #
     def connect(endpoint, parent: nil)
       ensure_parent_task(parent: parent)
-      Reactor.run { @engine.connect(endpoint) }
+      Reactor.run { @engine.connect(endpoint) } # TODO: use timeout?
     end
 
 
@@ -112,7 +112,7 @@ module OMQ
     # @return [void]
     #
     def disconnect(endpoint)
-      Reactor.run { @engine.disconnect(endpoint) }
+      Reactor.run { @engine.disconnect(endpoint) } # TODO: use timeout?
     end
 
 
@@ -122,7 +122,7 @@ module OMQ
     # @return [void]
     #
     def unbind(endpoint)
-      Reactor.run { @engine.unbind(endpoint) }
+      Reactor.run { @engine.unbind(endpoint) } # TODO: use timeout?
     end
 
 
@@ -183,9 +183,11 @@ module OMQ
     #
     def monitor(verbose: false, &block)
       ensure_parent_task
-      queue = Async::LimitedQueue.new(64)
-      @engine.monitor_queue = queue
+
+      queue                   = Async::LimitedQueue.new(64)
+      @engine.monitor_queue   = queue
       @engine.verbose_monitor = verbose
+
       Reactor.run do
         @engine.parent_task.async(transient: true, annotation: "monitor") do
           while (event = queue.dequeue)
@@ -218,7 +220,7 @@ module OMQ
     # @return [nil]
     #
     def close
-      Reactor.run { @engine.close }
+      Reactor.run { @engine.close } # TODO: use timeout?
       nil
     end
 
@@ -230,7 +232,7 @@ module OMQ
     # @return [nil]
     #
     def stop
-      Reactor.run { @engine.stop }
+      Reactor.run { @engine.stop } # TODO: use timeout?
       nil
     end
 
@@ -253,42 +255,13 @@ module OMQ
     end
 
 
-    private
-
-
-    # Runs a block with a timeout. Uses Async's with_timeout if inside
-    # a reactor, otherwise falls back to Timeout.timeout.
-    #
-    # @param seconds [Numeric]
-    # @raise [IO::TimeoutError]
-    #
-    def with_timeout(seconds, &block)
-      return yield if seconds.nil?
-      if Async::Task.current?
-        Async::Task.current.with_timeout(seconds, &block)
-      else
-        Timeout.timeout(seconds, &block)
-      end
-    rescue Async::TimeoutError, Timeout::Error
-      raise IO::TimeoutError, "timed out"
-    end
-
-
-    # Sets the engine's parent task before the first bind or connect.
-    # Must be called OUTSIDE Reactor.run so that non-Async callers
-    # get the IO thread's root task, not an ephemeral work task.
-    #
-    def ensure_parent_task(parent: nil)
-      @engine.capture_parent_task(parent: parent)
-    end
-
-
-    # Connects or binds based on endpoint prefix convention.
+    # Connects or binds based on endpoint prefix convention. Called
+    # from subclass initializers (including out-of-tree socket types).
     #
     # @param endpoints [String, nil]
     # @param default [Symbol] :connect or :bind
     #
-    def _attach(endpoints, default:)
+    def attach_endpoints(endpoints, default:)
       return unless endpoints
       case endpoints
       when /\A@(.+)\z/
@@ -301,29 +274,42 @@ module OMQ
     end
 
 
-    # Initializes engine and options for a socket type.
+    # Initializes engine and options for a socket type. Called from
+    # subclass initializers (including out-of-tree socket types).
     #
     # @param socket_type [Symbol]
     # @param linger [Integer]
     #
-    def _init_engine(socket_type, linger:, send_hwm: nil, recv_hwm: nil,
-                     send_timeout: nil, recv_timeout: nil, conflate: false,
-                     on_mute: nil, backend: nil)
+    def init_engine(socket_type, linger:, send_hwm: nil, recv_hwm: nil,
+                    send_timeout: nil, recv_timeout: nil, conflate: false,
+                    on_mute: nil, backend: nil)
       @options = Options.new(linger: linger)
-      @options.send_hwm      = send_hwm     if send_hwm
-      @options.recv_hwm      = recv_hwm     if recv_hwm
-      @options.send_timeout   = send_timeout if send_timeout
-      @options.recv_timeout   = recv_timeout if recv_timeout
-      @options.conflate       = conflate
-      @options.on_mute        = on_mute      if on_mute
-      @engine                 = case backend
-                     when nil, :ruby
-                       Engine.new(socket_type, @options)
-                     when :ffi
-                       FFI::Engine.new(socket_type, @options)
-                     else
-                       raise ArgumentError, "unknown backend: #{backend}"
-                     end
+      @options.send_hwm     = send_hwm     if send_hwm
+      @options.recv_hwm     = recv_hwm     if recv_hwm
+      @options.send_timeout = send_timeout if send_timeout
+      @options.recv_timeout = recv_timeout if recv_timeout
+      @options.conflate     = conflate
+      @options.on_mute      = on_mute      if on_mute
+      @engine = case backend
+      when nil, :ruby
+        Engine.new(socket_type, @options)
+      when :ffi
+        FFI::Engine.new(socket_type, @options)
+      else
+        raise ArgumentError, "unknown backend: #{backend}"
+      end
+    end
+
+
+    private
+
+
+    # Sets the engine's parent task before the first bind or connect.
+    # Must be called OUTSIDE Reactor.run so that non-Async callers
+    # get the IO thread's root task, not an ephemeral work task.
+    #
+    def ensure_parent_task(parent: nil)
+      @engine.capture_parent_task(parent: parent)
     end
   end
 end

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

@@ -112,6 +112,7 @@ module OMQ
         #
         def encrypted? = false
 
+
         # No-op — inproc has no IO buffer to flush.
         #
         # @return [nil]
@@ -127,11 +128,16 @@ module OMQ
         def receive_message
           loop do
             item = @receive_queue.dequeue
+
             raise EOFError, "connection closed" if item.nil?
+
             if item.is_a?(Array) && item.first == :command
-              yield Protocol::ZMTP::Codec::Frame.new(item[1].to_body, command: true) if block_given?
+              if block_given?
+                yield Protocol::ZMTP::Codec::Frame.new(item[1].to_body, command: true)
+              end
               next
             end
+
             return item
           end
         end
@@ -157,6 +163,7 @@ module OMQ
           loop do
             item = @receive_queue.dequeue
             raise EOFError, "connection closed" if item.nil?
+
             if item.is_a?(Array) && item.first == :command
               return Protocol::ZMTP::Codec::Frame.new(item[1].to_body, command: true)
             end
@@ -174,11 +181,18 @@ module OMQ
           @send_queue&.enqueue(nil) # close sentinel
         end
 
+
         private
 
+
         def apply_transform(parts)
-          @direct_recv_transform ? @direct_recv_transform.call(parts).freeze : parts
+          if @direct_recv_transform
+            @direct_recv_transform.call(parts).freeze
+          else
+            parts
+          end
         end
+
       end
     end
   end

data/lib/omq/transport/inproc.rb

@@ -37,7 +37,10 @@ module OMQ
         #
         def bind(endpoint, engine)
           @mutex.synchronize do
-            raise ArgumentError, "endpoint already bound: #{endpoint}" if @registry.key?(endpoint)
+            if @registry.key?(endpoint)
+              raise ArgumentError, "endpoint already bound: #{endpoint}"
+            end
+
             @registry[endpoint] = engine
 
             # Wake any pending connects
@@ -96,34 +99,55 @@ module OMQ
         def establish_link(client_engine, server_engine, endpoint)
           client_type = client_engine.socket_type
           server_type = server_engine.socket_type
+
           unless Protocol::ZMTP::VALID_PEERS[client_type]&.include?(server_type)
             raise Protocol::ZMTP::Error,
                   "incompatible socket types: #{client_type} cannot connect to #{server_type}"
           end
+
           needs_cmds = needs_commands?(client_engine, server_engine, client_type, server_type)
-          client_pipe, server_pipe = make_pipe_pair(client_engine, server_engine, client_type, server_type, needs_cmds)
+          client_pipe, server_pipe = make_pipe_pair client_engine, server_engine,
+                                                    client_type, server_type, needs_cmds
+
           client_engine.connection_ready(client_pipe, endpoint: endpoint)
           server_engine.connection_ready(server_pipe, endpoint: endpoint)
         end
 
 
+        # Decides whether a DirectPipe pair needs command queues.
+        # DirectPipe's fast path skips queues entirely; command queues
+        # are only needed for socket types that exchange ZMTP commands
+        # (e.g. ROUTER/DEALER identity, PUB/SUB subscriptions) or when
+        # either side enables QoS ≥ 1.
+        #
+        # @return [Boolean]
+        #
         def needs_commands?(ce, se, ct, st)
-          COMMAND_TYPES.include?(ct) || COMMAND_TYPES.include?(st) ||
-            ce.options.qos >= 1 || se.options.qos >= 1
+          return true if COMMAND_TYPES.include?(ct) || COMMAND_TYPES.include?(st)
+          return true if ce.options.qos >= 1 || se.options.qos >= 1
+          false
         end
 
 
+        # Builds a bidirectional {DirectPipe} pair for client + server.
+        # When +needs_cmds+ is false the pipes have no command queues
+        # (fast path — all traffic bypasses Async::Queue entirely).
+        #
+        # @return [Array(DirectPipe, DirectPipe)] client, server
+        #
         def make_pipe_pair(ce, se, ct, st, needs_cmds)
           if needs_cmds
             a_to_b = Async::Queue.new
             b_to_a = Async::Queue.new
           end
+
           client = DirectPipe.new(send_queue: needs_cmds ? a_to_b : nil,
                                   receive_queue: needs_cmds ? b_to_a : nil,
                                   peer_identity: se.options.identity, peer_type: st.to_s)
           server = DirectPipe.new(send_queue: needs_cmds ? b_to_a : nil,
                                   receive_queue: needs_cmds ? a_to_b : nil,
                                   peer_identity: ce.options.identity, peer_type: ct.to_s)
+
           client.peer = server
           server.peer = client
           [client, server]
@@ -136,11 +160,20 @@ module OMQ
           ri      = engine.options.reconnect_interval
           timeout = ri.is_a?(Range) ? ri.begin : ri
           promise = Async::Promise.new
-          @mutex.synchronize { @waiters[endpoint] << promise }
+
+          @mutex.synchronize do
+            @waiters[endpoint] << promise
+          end
+
           if promise.wait?(timeout: timeout)
-            @mutex.synchronize { @registry[endpoint] }
+            @mutex.synchronize do
+              @registry[endpoint]
+            end
           else
-            @mutex.synchronize { @waiters[endpoint].delete(promise) }
+            @mutex.synchronize do
+              @waiters[endpoint].delete(promise)
+            end
+
             start_connect_retry(endpoint, engine)
             nil
           end
@@ -158,6 +191,7 @@ module OMQ
             loop do
               sleep ivl
               bound_engine = @mutex.synchronize { @registry[endpoint] }
+
               if bound_engine
                 establish_link(engine, bound_engine, endpoint)
                 break

data/lib/omq/transport/ipc.rb

@@ -19,7 +19,7 @@ module OMQ
         # @return [Listener]
         #
         def bind(endpoint, engine)
-          path = parse_path(endpoint)
+          path      = parse_path(endpoint)
           sock_path = to_socket_path(path)
 
           # Remove stale socket file for file-based paths
@@ -45,17 +45,31 @@ module OMQ
           engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
         end
 
+
+        # Applies SO_SNDBUF / SO_RCVBUF to +sock+ from the socket's
+        # {Options}. No-op when both are nil (OS default).
+        #
+        # @param sock [UNIXSocket, UNIXServer]
+        # @param options [Options]
+        #
         def apply_buffer_sizes(sock, options)
-          sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF, options.sndbuf) if options.sndbuf
-          sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF, options.rcvbuf) if options.rcvbuf
+          if options.sndbuf
+            sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF, options.sndbuf)
+          end
+
+          if options.rcvbuf
+            sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF, options.rcvbuf)
+          end
         end
 
+
         private
 
+
         # Extracts path from "ipc://path".
         #
         def parse_path(endpoint)
-          endpoint.sub(%r{\Aipc://}, "")
+          endpoint.delete_prefix("ipc://")
         end
 
 
@@ -65,7 +79,7 @@ module OMQ
           if abstract?(path)
             "\0#{path[1..]}"
           else
-            path
+            path # TODO: return Pathname
           end
         end
 
@@ -92,7 +106,7 @@ module OMQ
 
         # @param endpoint [String] the IPC endpoint URI
         # @param server [UNIXServer]
-        # @param path [String] filesystem or abstract namespace path
+        # @param path [String] filesystem or abstract namespace path # TODO: Pathname
         # @param engine [Engine]
         #
         def initialize(endpoint, server, path, engine)
@@ -111,11 +125,15 @@ module OMQ
         # @yieldparam io [IO::Stream::Buffered]
         #
         def start_accept_loops(parent_task, &on_accepted)
-          @task = parent_task.async(transient: true, annotation: "ipc accept #{@endpoint}") do
+          annotation = "ipc accept #{@endpoint}"
+          @task = parent_task.async(transient: true, annotation:) do
             loop do
               client = @server.accept
               IPC.apply_buffer_sizes(client, @engine.options)
-              Async::Task.current.defer_stop { on_accepted.call(IO::Stream::Buffered.wrap(client)) }
+              Async::Task.current.defer_stop do
+                # TODO use yield
+                on_accepted.call(IO::Stream::Buffered.wrap(client))
+              end
             end
           rescue Async::Stop
           rescue IOError
@@ -135,11 +153,13 @@ module OMQ
         def stop
           @task&.stop
           @server.close rescue nil
+
           # Clean up socket file for file-based paths
-          unless @path.start_with?("@")
+          unless @path.start_with?("@") # TODO: check if it's a Pathname instead
             File.delete(@path) rescue nil
           end
         end
+
       end
     end
   end