omq 0.22.1 → 0.24.0

data/lib/omq/routing/round_robin.rb

@@ -12,7 +12,7 @@ module OMQ
     # which is strictly better than libzmq's strict per-pipe round-robin
     # for PUSH-style patterns.
     #
-    # See DESIGN.md "Per-socket HWM (not per-connection)" for the
+    # See doc/DESIGN.md "Per-socket HWM (not per-connection)" for the
     # full reasoning.
     #
     # Including classes must call `init_round_robin(engine)` from
@@ -38,18 +38,17 @@ module OMQ
       # @param engine [Engine]
       #
       def init_round_robin(engine)
-        @connections     = []
-        @send_queue      = Routing.build_queue(engine.options.send_hwm, :block)
-        @direct_pipe     = nil
-        @conn_send_tasks = {}  # conn => send pump task
-        @in_flight       = 0   # messages dequeued but not yet written
+        @connections = []
+        @send_queue  = Routing.build_queue(engine.options.send_hwm, :block)
+        @direct_pipe = nil
+        @in_flight   = 0   # messages dequeued but not yet written
       end
 
 
       # Registers a connection and starts its send pump.
       # Call from #connection_added.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       #
       def add_round_robin_send_connection(conn)
         @connections << conn
@@ -58,23 +57,23 @@ module OMQ
       end
 
 
-      # Removes the connection and stops its send pump. Any message
-      # the pump had already dequeued but not yet written is dropped --
-      # matching libzmq's behavior on `pipe_terminated`. PUSH has no
-      # cross-peer ordering guarantee, so this is safe.
+      # Removes the connection. Any message the pump had already
+      # dequeued but not yet written is dropped — matching libzmq's
+      # behavior on `pipe_terminated`. PUSH has no cross-peer ordering
+      # guarantee, so this is safe. The pump itself is torn down by
+      # the per-connection lifecycle barrier.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       #
       def remove_round_robin_send_connection(conn)
         update_direct_pipe
-        @conn_send_tasks.delete(conn)
       end
 
 
       # Updates the direct-pipe shortcut for inproc single-peer bypass.
       #
       def update_direct_pipe
-        if @connections.size == 1 && @connections.first.is_a?(Transport::Inproc::DirectPipe)
+        if @connections.size == 1 && @connections.first.is_a?(Transport::Inproc::Pipe)
           @direct_pipe = @connections.first
         else
           @direct_pipe = nil
@@ -129,10 +128,10 @@ module OMQ
       # run. The yield is effectively free when the scheduler has no
       # other work.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       #
       def start_conn_send_pump(conn)
-        task = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
+        @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           batch = []
 
           loop do
@@ -153,9 +152,6 @@ module OMQ
             Async::Task.current.yield
           end
         end
-
-        @conn_send_tasks[conn] = task
-        @tasks << task
       end
 
 

data/lib/omq/routing/router.rb

@@ -23,9 +23,7 @@ module OMQ
         @recv_queue              = Routing.build_queue(engine.options.recv_hwm, :block)
         @connections_by_identity = {}
         @identity_by_connection  = {}
-        @conn_queues             = {}  # connection => per-connection send queue
-        @conn_send_tasks         = {}  # connection => send pump task
-        @tasks                   = []
+        @conn_queues             = {}
       end
 
 
@@ -47,7 +45,7 @@ module OMQ
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_added(connection)
         identity = connection.peer_identity
@@ -55,22 +53,20 @@ module OMQ
         @connections_by_identity[identity] = connection
         @identity_by_connection[connection] = identity
 
-        task = @engine.start_recv_pump(connection, @recv_queue) { |msg| [identity, *msg] }
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue) { |msg| [identity, *msg] }
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
         @conn_queues[connection] = q
-        @conn_send_tasks[connection] = ConnSendPump.start(@engine, connection, q, @tasks)
+        ConnSendPump.start(@engine, connection, q)
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_removed(connection)
         identity = @identity_by_connection.delete(connection)
         @connections_by_identity.delete(identity) if identity
         @conn_queues.delete(connection)
-        @conn_send_tasks.delete(connection)&.stop
       end
 
 
@@ -91,16 +87,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?

data/lib/omq/routing/scatter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # SCATTER socket routing: round-robin send to GATHER peers.
+    #
+    class Scatter
+      include RoundRobin
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine = engine
+        init_round_robin(engine)
+      end
+
+
+      # SCATTER is write-only.
+      #
+      def recv_queue
+        raise "SCATTER sockets cannot receive"
+      end
+
+
+      def dequeue_recv
+        raise "SCATTER sockets cannot receive"
+      end
+
+
+      # No-op; SCATTER has no recv queue to unblock.
+      #
+      def unblock_recv
+      end
+
+
+      # @param connection [Protocol::ZMTP::Connection]
+      #
+      def connection_added(connection)
+        add_round_robin_send_connection(connection)
+        start_reaper(connection)
+      end
+
+
+      # @param connection [Protocol::ZMTP::Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        remove_round_robin_send_connection(connection)
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      end
+
+
+      private
+
+
+      # Detects peer disconnection on write-only sockets by
+      # blocking on a receive that only returns on disconnect.
+      #
+      # @param conn [Protocol::ZMTP::Connection]
+      #
+      def start_reaper(conn)
+        return if conn.is_a?(Transport::Inproc::Pipe)
+        @engine.spawn_conn_pump_task(conn, annotation: "reaper") do
+          conn.receive_message # blocks until peer disconnects; then exits
+        end
+      end
+
+    end
+  end
+end

data/lib/omq/routing/server.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OMQ
+  module Routing
+    # SERVER socket routing: identity-based routing with auto-generated
+    # 4-byte routing IDs.
+    #
+    # Prepends routing ID on receive. Strips routing ID on send and
+    # routes to the identified connection.
+    #
+    class Server
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine                     = engine
+        @recv_queue                 = Routing.build_queue(engine.options.recv_hwm, :block)
+        @connections_by_routing_id  = {}
+        @routing_id_by_connection   = {}
+        @conn_queues                = {}
+      end
+
+
+      # Dequeues the next received message. Blocks until one is available.
+      #
+      # @return [Array<String>, nil]
+      #
+      def dequeue_recv
+        @recv_queue.dequeue
+      end
+
+
+      # Wakes a blocked {#dequeue_recv} with a nil sentinel.
+      #
+      # @return [void]
+      #
+      def unblock_recv
+        @recv_queue.enqueue(nil)
+      end
+
+
+      # @param connection [Protocol::ZMTP::Connection]
+      #
+      def connection_added(connection)
+        routing_id = SecureRandom.bytes(4)
+        @connections_by_routing_id[routing_id] = connection
+        @routing_id_by_connection[connection]  = routing_id
+
+        @engine.start_recv_pump(connection, @recv_queue) { |msg| [routing_id, *msg] }
+
+        q = Routing.build_queue(@engine.options.send_hwm, :block)
+        @conn_queues[connection] = q
+        ConnSendPump.start(@engine, connection, q)
+      end
+
+
+      # @param connection [Protocol::ZMTP::Connection]
+      #
+      def connection_removed(connection)
+        routing_id = @routing_id_by_connection.delete(connection)
+        @connections_by_routing_id.delete(routing_id) if routing_id
+        @conn_queues.delete(connection)
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        routing_id = parts.first
+        conn = @connections_by_routing_id[routing_id]
+        return unless conn
+        @conn_queues[conn]&.enqueue(parts[1..])
+      end
+
+
+      # True when all per-connection send queues are empty.
+      #
+      def send_queues_drained?
+        @conn_queues.values.all?(&:empty?)
+      end
+
+    end
+  end
+end

data/lib/omq/routing/sub.rb

@@ -20,7 +20,6 @@ module OMQ
         @connections   = Set.new
         @recv_queue    = Routing.build_queue(engine.options.recv_hwm, :block)
         @subscriptions = Set.new
-        @tasks         = []
       end
 
 
@@ -42,7 +41,7 @@ module OMQ
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_added(connection)
         @connections << connection
@@ -51,12 +50,11 @@ module OMQ
           send_subscribe(connection, prefix)
         end
 
-        task = @engine.start_recv_pump(connection, @recv_queue)
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue)
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_removed(connection)
         @connections.delete(connection)
@@ -90,16 +88,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       private
 
 

data/lib/omq/routing/xpub.rb

@@ -24,7 +24,6 @@ module OMQ
       def initialize(engine)
         @engine     = engine
         @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
-        @tasks      = []
 
         init_fan_out(engine)
       end
@@ -42,7 +41,7 @@ module OMQ
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_added(connection)
         @connections << connection
@@ -52,7 +51,7 @@ module OMQ
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_removed(connection)
         @connections.delete(connection)
@@ -68,16 +67,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       private
 
 

data/lib/omq/routing/xsub.rb

@@ -18,12 +18,10 @@ module OMQ
       # @param engine [Engine]
       #
       def initialize(engine)
-        @engine          = engine
-        @connections     = Set.new
-        @recv_queue      = Routing.build_queue(engine.options.recv_hwm, :block)
-        @conn_queues     = {}  # connection => per-connection send queue
-        @conn_send_tasks = {}  # connection => send pump task
-        @tasks           = []
+        @engine      = engine
+        @connections = Set.new
+        @recv_queue  = Routing.build_queue(engine.options.recv_hwm, :block)
+        @conn_queues = {}
       end
 
 
@@ -45,13 +43,12 @@ module OMQ
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_added(connection)
         @connections << connection
 
-        task = @engine.start_recv_pump(connection, @recv_queue)
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue)
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
         @conn_queues[connection] = q
@@ -59,12 +56,11 @@ module OMQ
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_removed(connection)
         @connections.delete(connection)
         @conn_queues.delete(connection)
-        @conn_send_tasks.delete(connection)&.stop
       end
 
 
@@ -79,16 +75,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?
@@ -100,7 +86,7 @@ module OMQ
 
 
       def start_conn_send_pump(conn, q)
-        task = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
+        @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             parts = q.dequeue
             frame = parts.first&.b
@@ -128,9 +114,6 @@ module OMQ
             end
           end
         end
-
-        @conn_send_tasks[conn] = task
-        @tasks << task
       end
 
     end

data/lib/omq/scatter_gather.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# OMQ SCATTER/GATHER socket types (ZeroMQ RFC 49).
+#
+# Not loaded by +require "omq"+; opt in with:
+#
+#   require "omq/scatter_gather"
+
+require "omq"
+require_relative "routing/scatter"
+require_relative "routing/gather"
+
+module OMQ
+  # Pipeline sender socket that round-robins to GATHER peers (ZeroMQ RFC 49).
+  class SCATTER < Socket
+    include Writable
+    include SingleFrame
+
+    # Creates a new SCATTER socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to connect to
+    # @param linger [Numeric] linger period in seconds (Float::INFINITY = wait forever, 0 = drop)
+    # @param send_hwm [Integer, nil] send high-water mark
+    # @param send_timeout [Integer, nil] send timeout in seconds
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, send_hwm: nil, send_timeout: nil, backend: nil)
+      init_engine(:SCATTER, send_hwm: send_hwm, send_timeout: send_timeout, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :connect)
+    end
+  end
+
+
+  # Pipeline receiver socket that fair-queues from SCATTER peers (ZeroMQ RFC 49).
+  class GATHER < Socket
+    include Readable
+    include SingleFrame
+
+    # Creates a new GATHER socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to bind to
+    # @param linger [Numeric] linger period in seconds (Float::INFINITY = wait forever, 0 = drop)
+    # @param recv_hwm [Integer, nil] receive high-water mark
+    # @param recv_timeout [Integer, nil] receive timeout in seconds
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, recv_hwm: nil, recv_timeout: nil, backend: nil)
+      init_engine(:GATHER, recv_hwm: recv_hwm, recv_timeout: recv_timeout, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :bind)
+    end
+  end
+
+
+  Routing.register(:SCATTER, Routing::Scatter)
+  Routing.register(:GATHER,  Routing::Gather)
+end

data/lib/omq/socket.rb

@@ -35,11 +35,6 @@ module OMQ
     attr_reader :options
 
 
-    # @return [Integer, nil] last auto-selected TCP port
-    #
-    attr_reader :last_tcp_port
-
-
     # @return [Engine] the socket's engine. Exposed for peer tooling
     #   (omq-cli, omq-ffi, omq-ractor) that needs to reach into the
     #   socket's internals — not part of the stable user API.
@@ -109,14 +104,11 @@ module OMQ
     #   can coordinate teardown with their own Async tree. Only the
     #   *first* bind/connect call captures the parent — subsequent
     #   calls ignore the kwarg.
-    # @return [void]
+    # @return [URI::Generic] resolved endpoint URI (with auto-selected port for "tcp://host:0")
     #
-    def bind(endpoint, parent: nil)
+    def bind(endpoint, parent: nil, **opts)
       ensure_parent_task(parent: parent)
-      Reactor.run do
-        @engine.bind(endpoint) # TODO: use timeout?
-        @last_tcp_port = @engine.last_tcp_port
-      end
+      Reactor.run { @engine.bind(endpoint, **opts) } # TODO: use timeout?
     end
 
 
@@ -124,11 +116,11 @@ module OMQ
     #
     # @param endpoint [String]
     # @param parent [#async, nil] see {#bind}.
-    # @return [void]
+    # @return [URI::Generic] parsed endpoint URI
     #
-    def connect(endpoint, parent: nil)
+    def connect(endpoint, parent: nil, **opts)
       ensure_parent_task(parent: parent)
-      Reactor.run { @engine.connect(endpoint) } # TODO: use timeout?
+      Reactor.run { @engine.connect(endpoint, **opts) } # TODO: use timeout?
     end
 
 
@@ -152,13 +144,6 @@ module OMQ
     end
 
 
-    # @return [String, nil] last bound endpoint
-    #
-    def last_endpoint
-      @engine.last_endpoint
-    end
-
-
     # @return [Async::Promise] resolves when first peer completes handshake
     def peer_connected
       @engine.peer_connected
@@ -167,7 +152,7 @@ module OMQ
 
     # @return [Async::Promise] resolves when first subscriber joins (PUB/XPUB only)
     def subscriber_joined
-      @engine.routing.subscriber_joined
+      @engine.subscriber_joined
     end
 
 
@@ -285,7 +270,7 @@ module OMQ
     # @return [String]
     #
     def inspect
-      format("#<%s last_endpoint=%p>", self.class, last_endpoint)
+      format("#<%s bound=%p>", self.class, @engine.listeners.keys)
     end