omq 0.12.0 → 0.14.0

data/lib/omq/routing.rb

@@ -4,6 +4,9 @@ require "async"
 require "async/queue"
 require "async/limited_queue"
 require_relative "drop_queue"
+require_relative "routing/fair_queue"
+require_relative "routing/fair_recv"
+require_relative "routing/conn_send_pump"
 
 module OMQ
   # Routing strategies for each ZMQ socket type.
@@ -15,6 +18,7 @@ module OMQ
     # 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+.
     #
@@ -32,6 +36,7 @@ module OMQ
       end
     end
 
+
     # Builds a send or recv queue based on the mute strategy.
     #
     # @param hwm [Integer] high water mark
@@ -51,6 +56,7 @@ module OMQ
       end
     end
 
+
     # Drains all available messages from +queue+ into +batch+ without
     # blocking. Call after the initial blocking dequeue.
     #
@@ -70,6 +76,7 @@ module OMQ
       end
     end
 
+
     # Returns the routing strategy class for a socket type.
     #
     # @param socket_type [Symbol] e.g. :PAIR, :REQ
@@ -77,17 +84,28 @@ module OMQ
     #
     def self.for(socket_type)
       case socket_type
-      when :PAIR   then Pair
-      when :REQ    then Req
-      when :REP    then Rep
-      when :DEALER then Dealer
-      when :ROUTER then Router
-      when :PUB    then Pub
-      when :SUB    then Sub
-      when :XPUB   then XPub
-      when :XSUB   then XSub
-      when :PUSH   then Push
-      when :PULL   then Pull
+      when :PAIR
+        Pair
+      when :REQ
+        Req
+      when :REP
+        Rep
+      when :DEALER
+        Dealer
+      when :ROUTER
+        Router
+      when :PUB
+        Pub
+      when :SUB
+        Sub
+      when :XPUB
+        XPub
+      when :XSUB
+        XSub
+      when :PUSH
+        Push
+      when :PULL
+        Pull
       else
         @registry[socket_type] or raise ArgumentError, "unknown socket type: #{socket_type.inspect}"
       end

data/lib/omq/socket.rb

@@ -47,7 +47,7 @@ module OMQ
     # @return [Socket]
     #
     def self.bind(endpoint, **opts)
-      new(nil, **opts).tap { |s| s.bind(endpoint) }
+      new("@#{endpoint}", **opts)
     end
 
 
@@ -58,11 +58,16 @@ module OMQ
     # @return [Socket]
     #
     def self.connect(endpoint, **opts)
-      new(nil, **opts).tap { |s| s.connect(endpoint) }
+      new(">#{endpoint}", **opts)
     end
 
 
-    def initialize(endpoints = nil, linger: 0); end
+    # @param endpoints [String, nil] optional endpoint with prefix convention
+    #   (+@+ for bind, +>+ for connect, plain uses subclass default)
+    # @param linger [Integer] linger period in seconds (default 0)
+    #
+    def initialize(endpoints = nil, linger: 0)
+    end
 
 
     # Binds to an endpoint.
@@ -136,6 +141,8 @@ module OMQ
     # Signals end-of-stream on the receive side. A subsequent
     # +#receive+ call that would otherwise block returns +nil+.
     #
+    # @return [void]
+    #
     def close_read
       @engine.dequeue_recv_sentinel
     end
@@ -182,12 +189,18 @@ module OMQ
 
 
     # Disable auto-reconnect for connected endpoints.
+    #
+    # @param val [Boolean]
+    # @return [void]
+    #
     def reconnect_enabled=(val)
       @engine.reconnect_enabled = val
     end
 
 
-    # Closes the socket.
+    # Closes the socket and releases all resources.
+    #
+    # @return [nil]
     #
     def close
       Reactor.run { @engine.close }
@@ -197,6 +210,8 @@ module OMQ
 
     # Set socket to use unbounded pipes (HWM=0).
     #
+    # @return [nil]
+    #
     def set_unbounded
       @options.send_hwm = 0
       @options.recv_hwm = 0
@@ -277,9 +292,12 @@ module OMQ
       @recv_buffer = []
       @recv_mutex  = Mutex.new
       @engine      = case backend
-                     when nil, :ruby then Engine.new(socket_type, @options)
-                     when :ffi       then FFI::Engine.new(socket_type, @options)
-                     else raise ArgumentError, "unknown backend: #{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
   end

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

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Transport
+    module Inproc
+      # A direct in-process pipe that transfers Ruby arrays through queues.
+      #
+      # Implements the same interface as Connection so routing strategies
+      # can use it transparently.
+      #
+      # When a routing strategy sets {#direct_recv_queue} on a pipe,
+      # {#send_message} enqueues directly into the peer's recv queue,
+      # 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
+        # @param peer_identity [String]
+        # @param peer_type [String]
+        #
+        def initialize(send_queue: nil, receive_queue: nil, peer_identity:, peer_type:)
+          @send_queue            = send_queue
+          @receive_queue         = receive_queue
+          @peer_identity         = peer_identity || "".b
+          @peer_socket_type      = peer_type
+          @closed                = false
+          @peer                  = nil
+          @direct_recv_queue     = nil
+          @direct_recv_transform = nil
+          @pending_direct        = nil
+        end
+
+
+        # Sets the direct recv queue. Drains any messages that were
+        # buffered before the queue was available.
+        #
+        # @param queue [Async::LimitedQueue, nil]
+        # @return [void]
+        #
+        def direct_recv_queue=(queue)
+          @direct_recv_queue = queue
+          if queue && @pending_direct
+            @pending_direct.each { |msg| queue.enqueue(msg) }
+            @pending_direct = nil
+          end
+        end
+
+
+        # Sends a multi-frame message.
+        #
+        # @param parts [Array<String>]
+        # @return [void]
+        #
+        def send_message(parts)
+          raise IOError, "closed" if @closed
+          if @direct_recv_queue
+            @direct_recv_queue.enqueue(apply_transform(parts))
+          elsif @send_queue
+            @send_queue.enqueue(parts)
+          else
+            (@pending_direct ||= []) << apply_transform(parts)
+          end
+        end
+
+
+        alias write_message send_message
+
+
+        # @return [Boolean] always false; inproc pipes are never encrypted
+        #
+        def encrypted? = false
+
+        # No-op — inproc has no IO buffer to flush.
+        #
+        # @return [nil]
+        #
+        def flush = nil
+
+
+        # Receives a multi-frame message.
+        #
+        # @return [Array<String>]
+        # @raise [EOFError] if closed
+        #
+        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?
+              next
+            end
+            return item
+          end
+        end
+
+
+        # Sends a command via the internal command queue.
+        # Only available for PUB/SUB-family pipes.
+        #
+        # @param command [Protocol::ZMTP::Codec::Command]
+        #
+        def send_command(command)
+          raise IOError, "closed" if @closed
+          @send_queue.enqueue([:command, command])
+        end
+
+
+        # Reads one command frame from the internal command queue.
+        # Used by PUB/XPUB subscription listeners.
+        #
+        # @return [Protocol::ZMTP::Codec::Frame]
+        #
+        def read_frame
+          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
+          end
+        end
+
+
+        # Closes this pipe end and sends a nil sentinel to the peer.
+        #
+        # @return [void]
+        #
+        def close
+          return if @closed
+          @closed = true
+          @send_queue&.enqueue(nil) # close sentinel
+        end
+
+        private
+
+        def apply_transform(parts)
+          @direct_recv_transform ? @direct_recv_transform.call(parts).freeze : parts
+        end
+      end
+    end
+  end
+end

data/lib/omq/transport/inproc.rb

@@ -2,6 +2,7 @@
 
 require "async"
 require "async/queue"
+require_relative "inproc/direct_pipe"
 
 module OMQ
   module Transport
@@ -18,6 +19,7 @@ module OMQ
       #
       COMMAND_TYPES = %i[PUB SUB XPUB XSUB RADIO DISH].freeze
 
+
       # Global registry of bound inproc endpoints.
       #
       @registry = {}
@@ -54,25 +56,7 @@ module OMQ
         #
         def connect(endpoint, engine)
           bound_engine = @mutex.synchronize { @registry[endpoint] }
-
-          unless bound_engine
-            # Endpoint not bound yet. Wait with timeout derived from
-            # reconnect_interval. If it doesn't appear, silently return —
-            # matching ZMQ 4.x behavior where inproc connect to an
-            # unbound endpoint succeeds but messages go nowhere.
-            # A background task retries periodically.
-            ri      = engine.options.reconnect_interval
-            timeout = ri.is_a?(Range) ? ri.begin : ri
-            promise = Async::Promise.new
-            @mutex.synchronize { @waiters[endpoint] << promise }
-            unless promise.wait?(timeout: timeout)
-              @mutex.synchronize { @waiters[endpoint].delete(promise) }
-              start_connect_retry(endpoint, engine)
-              return
-            end
-            bound_engine = @mutex.synchronize { @registry[endpoint] }
-          end
-
+          bound_engine ||= await_bind(endpoint, engine) or return
           establish_link(engine, bound_engine, endpoint)
         end
 
@@ -112,42 +96,54 @@ 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_engine.connection_ready(client_pipe, endpoint: endpoint)
+          server_engine.connection_ready(server_pipe, endpoint: endpoint)
+        end
+
+
+        def needs_commands?(ce, se, ct, st)
+          COMMAND_TYPES.include?(ct) || COMMAND_TYPES.include?(st) ||
+            ce.options.qos >= 1 || se.options.qos >= 1
+        end
 
-          # PUB/SUB-family types exchange commands (SUBSCRIBE/CANCEL)
-          # over inproc. QoS >= 1 needs command queues for ACK/NACK.
-          needs_commands = COMMAND_TYPES.include?(client_type) ||
-                           COMMAND_TYPES.include?(server_type) ||
-                           client_engine.options.qos >= 1 ||
-                           server_engine.options.qos >= 1
 
-          if needs_commands
+        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]
+        end
 
-          client_pipe = DirectPipe.new(
-            send_queue:    needs_commands ? a_to_b : nil,
-            receive_queue: needs_commands ? b_to_a : nil,
-            peer_identity: server_engine.options.identity,
-            peer_type:     server_type.to_s,
-          )
-          server_pipe = DirectPipe.new(
-            send_queue:    needs_commands ? b_to_a : nil,
-            receive_queue: needs_commands ? a_to_b : nil,
-            peer_identity: client_engine.options.identity,
-            peer_type:     client_type.to_s,
-          )
-
-          client_pipe.peer = server_pipe
-          server_pipe.peer = client_pipe
 
-          client_engine.connection_ready(client_pipe, endpoint: endpoint)
-          server_engine.connection_ready(server_pipe, endpoint: endpoint)
+        def await_bind(endpoint, engine)
+          # Endpoint not bound yet — wait briefly then start background retry.
+          # Matches ZMQ 4.x: connect to unbound inproc succeeds silently.
+          ri      = engine.options.reconnect_interval
+          timeout = ri.is_a?(Range) ? ri.begin : ri
+          promise = Async::Promise.new
+          @mutex.synchronize { @waiters[endpoint] << promise }
+          if promise.wait?(timeout: timeout)
+            @mutex.synchronize { @registry[endpoint] }
+          else
+            @mutex.synchronize { @waiters[endpoint].delete(promise) }
+            start_connect_retry(endpoint, engine)
+            nil
+          end
         end
 
 
@@ -171,6 +167,7 @@ module OMQ
         end
       end
 
+
       # A bound inproc endpoint handle.
       #
       class Listener
@@ -195,179 +192,6 @@ module OMQ
         end
       end
 
-      # A direct in-process pipe that transfers Ruby arrays through queues.
-      #
-      # Implements the same interface as Connection so routing strategies
-      # can use it transparently.
-      #
-      # When a routing strategy sets {#direct_recv_queue} on a pipe,
-      # {#send_message} enqueues directly into the peer's recv queue,
-      # 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
-        # @param peer_identity [String]
-        # @param peer_type [String]
-        #
-        def initialize(send_queue: nil, receive_queue: nil, peer_identity:, peer_type:)
-          @send_queue            = send_queue
-          @receive_queue         = receive_queue
-          @peer_identity         = peer_identity || "".b
-          @peer_socket_type      = peer_type
-          @closed                = false
-          @peer                  = nil
-          @direct_recv_queue     = nil
-          @direct_recv_transform = nil
-          @pending_direct        = nil
-        end
-
-
-        # Sets the direct recv queue. Drains any messages that were
-        # buffered before the queue was available.
-        #
-        def direct_recv_queue=(queue)
-          @direct_recv_queue = queue
-          if queue && @pending_direct
-            @pending_direct.each do |msg|
-              queue.enqueue(msg)
-            end
-            @pending_direct = nil
-          end
-        end
-
-
-        # Sends a multi-frame message.
-        #
-        # When {#direct_recv_queue} is set (inproc fast path), the
-        # message is delivered directly to the peer's recv queue,
-        # skipping the internal pipe queues and the recv pump.
-        #
-        # @param parts [Array<String>]
-        # @return [void]
-        #
-        def send_message(parts)
-          raise IOError, "closed" if @closed
-          if @direct_recv_queue
-            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).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.
-        #
-        # When a block is given, command items ([:command, cmd]) are
-        # yielded as command frames — matching the Protocol::ZMTP::Connection
-        # interface. Without a block, commands are silently skipped if
-        # the pipe has command queues.
-        #
-        # @return [Array<String>]
-        # @raise [EOFError] if closed
-        #
-        def receive_message
-          loop do
-            item = @receive_queue.dequeue
-            raise EOFError, "connection closed" if item.nil?
-
-            if item.is_a?(Array) && item.first == :command
-              if block_given?
-                cmd   = item[1]
-                frame = Protocol::ZMTP::Codec::Frame.new(cmd.to_body, command: true)
-                yield frame
-              end
-              next
-            end
-
-            return item
-          end
-        end
-
-
-        # Sends a command via the internal command queue.
-        # Only available for PUB/SUB-family pipes.
-        #
-        # @param command [Protocol::ZMTP::Codec::Command]
-        # @return [void]
-        #
-        def send_command(command)
-          raise IOError, "closed" if @closed
-          @send_queue.enqueue([:command, command])
-        end
-
-
-        # Reads one command frame from the internal command queue.
-        # Used by PUB/XPUB subscription listeners.
-        #
-        # @return [Protocol::ZMTP::Codec::Frame]
-        #
-        def read_frame
-          loop do
-            item = @receive_queue.dequeue
-            raise EOFError, "connection closed" if item.nil?
-            if item.is_a?(Array) && item.first == :command
-              cmd = item[1]
-              return Protocol::ZMTP::Codec::Frame.new(cmd.to_body, command: true)
-            end
-          end
-        end
-
-
-        # Closes this pipe end.
-        #
-        # @return [void]
-        #
-        def close
-          return if @closed
-          @closed = true
-          @send_queue&.enqueue(nil) # close sentinel
-        end
-      end
     end
   end
 end

data/lib/omq/transport/ipc.rb

@@ -30,6 +30,7 @@ module OMQ
           Listener.new(endpoint, server, path)
         end
 
+
         # Connects to an IPC endpoint.
         #
         # @param endpoint [String]
@@ -51,6 +52,7 @@ module OMQ
           endpoint.sub(%r{\Aipc://}, "")
         end
 
+
         # Converts @ prefix to \0 for abstract namespace.
         #
         def to_socket_path(path)
@@ -61,6 +63,7 @@ module OMQ
           end
         end
 
+
         # @return [Boolean] true if abstract namespace path
         #
         def abstract?(path)
@@ -68,6 +71,7 @@ module OMQ
         end
       end
 
+
       # A bound IPC listener.
       #
       class Listener
@@ -113,7 +117,9 @@ module OMQ
         end
 
 
-        # Stops the listener.
+        # Stops the listener and removes the socket file.
+        #
+        # @return [void]
         #
         def stop
           @task&.stop