omq 0.22.1 → 0.24.0

data/lib/omq/radio_dish.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# OMQ RADIO/DISH socket types with UDP transport (ZeroMQ RFC 48).
+#
+# Not loaded by +require "omq"+; opt in with:
+#
+#   require "omq/radio_dish"
+#
+# Loading this file also registers the +udp://+ transport.
+
+require "omq"
+require_relative "routing/radio"
+require_relative "routing/dish"
+require_relative "transport/udp"
+
+module OMQ
+  # Group-based publisher socket (ZeroMQ RFC 48).
+  #
+  # Sends messages to DISH peers that have joined the target group.
+  # Supports both TCP and UDP transports.
+  class RADIO < Socket
+    include Writable
+
+    # Creates a new RADIO 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 on_mute [Symbol] behaviour when HWM is reached (+:drop_newest+ or +:block+)
+    # @param conflate [Boolean] if true, keep only the latest message per group per peer
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, on_mute: :drop_newest, conflate: false, backend: nil)
+      init_engine(:RADIO, on_mute: on_mute, conflate: conflate, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :bind)
+    end
+
+
+    # Publishes a message to a group.
+    #
+    # @param group [String] group name
+    # @param body [String] message body
+    # @return [self]
+    #
+    def publish(group, body)
+      parts = [group, body]
+      Reactor.run timeout: @options.write_timeout do
+        @engine.enqueue_send(parts)
+      end
+      self
+    end
+
+
+    # Sends a message to a group.
+    #
+    # @param message [String] message body (requires group: kwarg)
+    # @param group [String] group name
+    # @return [self]
+    #
+    def send(message, group: nil)
+      raise ArgumentError, "RADIO requires a group (use group: kwarg, publish, or << [group, body])" unless group
+      publish(group, message)
+    end
+
+
+    # Sends a message to a group via [group, body] array.
+    #
+    # @param message [Array<String>] [group, body]
+    # @return [self]
+    #
+    def <<(message)
+      raise ArgumentError, "RADIO requires [group, body] array" unless message.is_a?(Array) && message.size == 2
+      publish(message[0], message[1])
+    end
+  end
+
+
+  # Group-based subscriber socket (ZeroMQ RFC 48).
+  #
+  # Receives messages from RADIO peers for joined groups.
+  # Supports both TCP and UDP transports.
+  class DISH < Socket
+    include Readable
+
+    # Creates a new DISH 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 group [String, nil] initial group to join
+    # @param on_mute [Symbol] behaviour when HWM is reached (+:block+ or +:drop_newest+)
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, group: nil, on_mute: :block, backend: nil)
+      init_engine(:DISH, on_mute: on_mute, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :connect)
+      join(group) if group
+    end
+
+
+    # Joins a group.
+    #
+    # @param group [String]
+    # @return [void]
+    #
+    def join(group)
+      @engine.routing.join(group)
+    end
+
+
+    # Leaves a group.
+    #
+    # @param group [String]
+    # @return [void]
+    #
+    def leave(group)
+      @engine.routing.leave(group)
+    end
+  end
+
+
+  Routing.register(:RADIO, Routing::Radio)
+  Routing.register(:DISH,  Routing::Dish)
+end

data/lib/omq/reactor.rb

@@ -25,6 +25,11 @@ module OMQ
 
 
     class << self
+      # @return [Hash{Numeric => Integer}] linger value → active socket count
+      #
+      attr_reader :lingers
+
+
       # Returns the root Async task inside the shared IO thread.
       # Starts the thread exactly once (double-checked lock).
       #
@@ -69,7 +74,7 @@ module OMQ
         else
           result = Async::Promise.new
           root_task # ensure started
-          @work_queue.push([block, result, timeout])
+          @work_queue << [block, result, timeout]
           result.wait
         end
       end
@@ -89,9 +94,12 @@ module OMQ
       # @param seconds [Numeric, nil] linger value
       #
       def untrack_linger(seconds)
-        key = seconds || 0
+        key            = seconds || 0
         @lingers[key] -= 1
-        @lingers.delete(key) if @lingers[key] <= 0
+
+        if @lingers[key] <= 0
+          @lingers.delete(key)
+        end
       end
 
 
@@ -103,13 +111,14 @@ module OMQ
         return unless @thread&.alive?
 
         max_linger = @lingers.empty? ? 0 : @lingers.keys.max
-        @work_queue&.push(nil)
+
+        @work_queue << nil if @work_queue
         @thread&.join(max_linger + 1)
 
         @thread     = nil
         @root_task  = nil
         @work_queue = nil
-        @lingers    = Hash.new(0)
+        @lingers.clear
       end
 
 

data/lib/omq/readable.rb

@@ -14,7 +14,11 @@ module OMQ
     # @raise [IO::TimeoutError] if read_timeout exceeded
     #
     def receive
-      Reactor.run timeout: @options.read_timeout do |task|
+      if @engine.on_io_thread?
+        Reactor.run(timeout: @options.read_timeout) { @engine.dequeue_recv }
+      elsif (timeout = @options.read_timeout)
+        Async::Task.current.with_timeout(timeout, IO::TimeoutError) { @engine.dequeue_recv }
+      else
         @engine.dequeue_recv
       end
     end

data/lib/omq/routing/channel.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # CHANNEL socket routing: exclusive 1-to-1 bidirectional.
+    #
+    class Channel
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine        = engine
+        @connection    = nil
+        @recv_queue    = Routing.build_queue(engine.options.recv_hwm, :block)
+        @send_queue    = nil
+        @staging_queue = Routing.build_queue(engine.options.send_hwm, :block)
+      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]
+      # @raise [RuntimeError] if a connection already exists
+      #
+      def connection_added(connection)
+        raise "CHANNEL allows only one peer" if @connection
+        @connection = connection
+
+        @engine.start_recv_pump(connection, @recv_queue)
+
+        unless connection.is_a?(Transport::Inproc::Pipe)
+          @send_queue = Routing.build_queue(@engine.options.send_hwm, :block)
+          while (msg = @staging_queue.dequeue(timeout: 0))
+            @send_queue.enqueue(msg)
+          end
+          start_send_pump(connection)
+        end
+      end
+
+
+      # @param connection [Protocol::ZMTP::Connection]
+      #
+      def connection_removed(connection)
+        if @connection == connection
+          @connection = nil
+          @send_queue = nil
+        end
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        conn = @connection
+        if conn.is_a?(Transport::Inproc::Pipe) && conn.direct_recv_queue
+          conn.send_message(parts)
+        elsif @send_queue
+          @send_queue.enqueue(parts)
+        else
+          @staging_queue.enqueue(parts)
+        end
+      end
+
+
+      # True when the staging and send queues are empty.
+      #
+      def send_queues_drained?
+        @staging_queue.empty? && (@send_queue.nil? || @send_queue.empty?)
+      end
+
+
+      private
+
+
+      def start_send_pump(conn)
+        @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
+          batch = []
+
+          loop do
+            Routing.dequeue_batch(@send_queue, batch)
+            batch.each { |parts| conn.write_message(parts) }
+            conn.flush
+            batch.clear
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/omq/routing/client.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # CLIENT socket routing: round-robin send, fair-queue receive.
+    #
+    # Same as DEALER — no envelope manipulation.
+    #
+    class Client
+      include RoundRobin
+
+
+      # @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)
+        init_round_robin(engine)
+      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)
+        @connections << connection
+        @engine.start_recv_pump(connection, @recv_queue)
+        add_round_robin_send_connection(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
+
+    end
+  end
+end

data/lib/omq/routing/conn_send_pump.rb

@@ -8,16 +8,16 @@ module OMQ
     # include the RoundRobin mixin.
     #
     module ConnSendPump
-      # Spawns the pump task and registers it in +tasks+.
+      # Spawns the pump task on the connection's lifecycle barrier so it
+      # is torn down with the rest of the connection's pumps.
       #
       # @param engine [Engine]
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       # @param q [Async::LimitedQueue]
-      # @param tasks [Array]
       # @return [Async::Task]
       #
-      def self.start(engine, conn, q, tasks)
-        task = engine.spawn_conn_pump_task(conn, annotation: "send pump") do
+      def self.start(engine, conn, q)
+        engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           batch = []
 
           loop do
@@ -38,9 +38,6 @@ module OMQ
             batch.clear
           end
         end
-
-        tasks << task
-        task
       end
 
     end

data/lib/omq/routing/dealer.rb

@@ -20,7 +20,6 @@ module OMQ
       def initialize(engine)
         @engine     = engine
         @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
-        @tasks      = []
         init_round_robin(engine)
       end
 
@@ -43,16 +42,15 @@ module OMQ
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_added(connection)
-        task = @engine.start_recv_pump(connection, @recv_queue)
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue)
         add_round_robin_send_connection(connection)
       end
 
 
-      # @param connection [Connection]
+      # @param connection [Protocol::ZMTP::Connection]
       #
       def connection_removed(connection)
         @connections.delete(connection)
@@ -66,16 +64,6 @@ module OMQ
         enqueue_round_robin(parts)
       end
 
-
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
     end
   end
 end

data/lib/omq/routing/dish.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # DISH socket routing: group-based receive from RADIO peers.
+    #
+    # Sends JOIN/LEAVE commands to connected RADIO peers.
+    # Receives two-frame messages (group + body) from RADIO.
+    #
+    class Dish
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine      = engine
+        @connections = []
+        @recv_queue  = Routing.build_queue(engine.options.recv_hwm, :block)
+        @groups      = Set.new
+      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)
+        @connections << connection
+        @groups.each do |group|
+          connection.send_command(Protocol::ZMTP::Codec::Command.join(group))
+        end
+        @engine.start_recv_pump(connection, @recv_queue)
+      end
+
+
+      # @param connection [Protocol::ZMTP::Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+      end
+
+
+      # DISH is read-only.
+      #
+      def enqueue(_parts)
+        raise "DISH sockets cannot send"
+      end
+
+
+      # Joins a group.
+      #
+      # @param group [String]
+      #
+      def join(group)
+        @groups << group
+        @connections.each do |conn|
+          conn.send_command(Protocol::ZMTP::Codec::Command.join(group))
+        end
+      end
+
+
+      # Leaves a group.
+      #
+      # @param group [String]
+      #
+      def leave(group)
+        @groups.delete(group)
+        @connections.each do |conn|
+          conn.send_command(Protocol::ZMTP::Codec::Command.leave(group))
+        end
+      end
+
+    end
+  end
+end

data/lib/omq/routing/fan_out.rb

@@ -41,7 +41,6 @@ module OMQ
         @subscriptions      = {} # connection => Set of prefixes
         @subscribe_all      = Set.new # connections subscribed to "" (match-all fast path)
         @conn_queues        = {} # connection => per-connection send queue
-        @conn_send_tasks    = {} # connection => send pump task
         @conflate           = engine.options.conflate
         @subscriber_joined  = Async::Promise.new
         @latest             = {} if @conflate
@@ -62,7 +61,7 @@ module OMQ
       # Override in subclasses to expose subscriptions to the
       # application (e.g. XPUB enqueues to recv_queue).
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       # @param prefix [String]
       #
       def on_subscribe(conn, prefix)
@@ -75,7 +74,7 @@ module OMQ
       # Called when a cancel command is received from a peer.
       # Override in subclasses (e.g. XPUB enqueues to recv_queue).
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       # @param prefix [String]
       #
       def on_cancel(conn, prefix)
@@ -87,7 +86,7 @@ module OMQ
       # Creates a per-connection send queue and starts its send pump.
       # Call from #connection_added.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       #
       def add_fan_out_send_connection(conn)
         q = Routing.build_queue(@engine.options.send_hwm, @engine.options.on_mute)
@@ -96,15 +95,15 @@ module OMQ
       end
 
 
-      # Stops the per-connection send pump and removes the queue.
+      # Removes the per-connection send queue. The pump itself is torn
+      # down by the per-connection lifecycle barrier.
       # Call from #connection_removed.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       #
       def remove_fan_out_send_connection(conn)
         @subscribe_all.delete(conn)
         @conn_queues.delete(conn)
-        @conn_send_tasks.delete(conn)&.stop
       end
 
 
@@ -130,7 +129,7 @@ module OMQ
 
 
       def start_subscription_listener(conn)
-        @tasks << @engine.spawn_conn_pump_task(conn, annotation: "subscription listener") do
+        @engine.spawn_conn_pump_task(conn, annotation: "subscription listener") do
           loop do
             frame = conn.read_frame
 
@@ -153,27 +152,24 @@ module OMQ
       # In conflate mode, drains the batch and keeps only the latest
       # message per topic before writing.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       # @param q [Async::LimitedQueue, DropQueue]
       #
       def start_conn_send_pump(conn, q)
         use_wire = conn.respond_to?(:write_wire) && !conn.encrypted?
 
         if @conflate
-          task = start_conn_send_pump_conflate(conn, q)
+          start_conn_send_pump_conflate(conn, q)
         else
-          task = start_conn_send_pump_normal(conn, q, use_wire)
+          start_conn_send_pump_normal(conn, q, use_wire)
         end
-
-        @conn_send_tasks[conn] = task
-        @tasks << task
       end
 
 
       # Send pump variant for non-conflate fan-out: dequeues, batch-drains,
       # writes each subscribed message, then flushes once.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       # @param q [Async::LimitedQueue, DropQueue]
       # @param use_wire [Boolean] true iff the encoded wire bytes can
       #   be shared across peers (unencrypted ZMTP)
@@ -223,7 +219,7 @@ module OMQ
       # Send pump variant for conflate mode: keeps only the latest
       # subscribed message per batch. Stale duplicates are dropped.
       #
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       # @param q [Async::LimitedQueue, DropQueue]
       # @return [Async::Task]
       #

data/lib/omq/routing/gather.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # GATHER socket routing: fair-queue receive from SCATTER peers.
+    #
+    class Gather
+      # @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)
+      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)
+        @engine.start_recv_pump(connection, @recv_queue)
+      end
+
+
+      # @param connection [Protocol::ZMTP::Connection]
+      #
+      def connection_removed(connection)
+      end
+
+
+      # GATHER is read-only.
+      #
+      def enqueue(_parts)
+        raise "GATHER sockets cannot send"
+      end
+
+    end
+  end
+end