omq 0.12.0 → 0.14.0

data/lib/omq/pub_sub.rb

@@ -1,15 +1,24 @@
 # frozen_string_literal: true
 
 module OMQ
+  # PUB socket — publish messages to all matching subscribers.
+  #
   class PUB < Socket
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param on_mute [Symbol] mute strategy for slow subscribers
+    # @param conflate [Boolean] keep only latest message per topic
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, on_mute: :drop_newest, conflate: false, backend: nil)
       _init_engine(:PUB, linger: linger, on_mute: on_mute, conflate: conflate, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end
 
+
   # SUB socket.
   #
   class SUB < Socket
@@ -19,6 +28,7 @@ module OMQ
     #
     EVERYTHING = ''
 
+
     # @param endpoints [String, nil]
     # @param linger [Integer]
     # @param subscribe [String, nil] subscription prefix; +nil+ (default)
@@ -31,6 +41,7 @@ module OMQ
       self.subscribe(subscribe) unless subscribe.nil?
     end
 
+
     # Subscribes to a topic prefix.
     #
     # @param prefix [String]
@@ -40,6 +51,7 @@ module OMQ
       @engine.routing.subscribe(prefix)
     end
 
+
     # Unsubscribes from a topic prefix.
     #
     # @param prefix [String]
@@ -50,16 +62,27 @@ module OMQ
     end
   end
 
+
+  # XPUB socket — like PUB but exposes subscription events to the application.
+  #
   class XPUB < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param on_mute [Symbol] mute strategy for slow subscribers
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, on_mute: :drop_newest, backend: nil)
       _init_engine(:XPUB, linger: linger, on_mute: on_mute, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end
 
+
+  # XSUB socket — like SUB but subscriptions are sent as data frames.
+  #
   class XSUB < Socket
     include Readable
     include Writable
@@ -68,6 +91,8 @@ module OMQ
     # @param linger [Integer]
     # @param subscribe [String, nil] subscription prefix; +nil+ (default)
     #   means no subscription — send a subscribe frame explicitly.
+    # @param on_mute [Symbol] mute strategy (:block, :drop_newest, :drop_oldest)
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, subscribe: nil, on_mute: :block, backend: nil)
       _init_engine(:XSUB, linger: linger, on_mute: on_mute, backend: backend)

data/lib/omq/push_pull.rb

@@ -1,18 +1,35 @@
 # frozen_string_literal: true
 
 module OMQ
+  # PUSH socket — push messages to connected PULL peers via round-robin.
+  #
   class PUSH < Socket
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param send_hwm [Integer, nil] send high water mark (nil uses default)
+    # @param send_timeout [Numeric, nil] send timeout in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, send_hwm: nil, send_timeout: nil, backend: nil)
       _init_engine(:PUSH, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
 
+
+  # PULL socket — receive messages from PUSH peers via fair-queue.
+  #
   class PULL < Socket
     include Readable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param recv_hwm [Integer, nil] receive high water mark (nil uses default)
+    # @param recv_timeout [Numeric, nil] receive timeout in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, recv_hwm: nil, recv_timeout: nil, backend: nil)
       _init_engine(:PULL, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout, backend: backend)
       _attach(endpoints, default: :bind)

data/lib/omq/queue_interface.rb

@@ -35,6 +35,7 @@ module OMQ
       dequeue(timeout: nil)
     end
 
+
     # Yields each received message until the socket is closed or
     # a receive timeout expires.
     #

data/lib/omq/readable.rb

@@ -11,6 +11,7 @@ module OMQ
     # Maximum messages to prefetch from the recv queue per drain.
     RECV_BATCH_SIZE = 64
 
+
     # Receives the next message. Returns from a local prefetch
     # buffer when available, otherwise drains up to
     # {RECV_BATCH_SIZE} messages from the recv queue in one
@@ -23,6 +24,7 @@ module OMQ
       @recv_mutex.synchronize { @recv_buffer.shift } || fill_recv_buffer
     end
 
+
     # Waits until the socket is readable.
     #
     # @param timeout [Numeric, nil] timeout in seconds

data/lib/omq/req_rep.rb

@@ -1,20 +1,33 @@
 # frozen_string_literal: true
 
 module OMQ
+  # REQ socket — send a request, then receive one reply (strict alternation).
+  #
   class REQ < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, backend: nil)
       _init_engine(:REQ, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
 
+
+  # REP socket — receive a request, then send one reply (strict alternation).
+  #
   class REP < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, backend: nil)
       _init_engine(:REP, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)

data/lib/omq/router_dealer.rb

@@ -1,27 +1,39 @@
 # frozen_string_literal: true
 
 module OMQ
+  # DEALER socket — asynchronous round-robin send, fair-queue receive.
+  #
   class DEALER < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @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)
     end
   end
 
+
   # ROUTER socket.
   #
   class ROUTER < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @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)
     end
 
+
     # Sends a message to a specific peer by identity.
     #
     # @param receiver [String] peer identity

data/lib/omq/routing/conn_send_pump.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # Starts a dedicated send pump for one per-connection send queue.
+    #
+    # Used by Router and Rep, which have per-connection queues but do not
+    # include the RoundRobin mixin.
+    #
+    module ConnSendPump
+      # Spawns the pump task and registers it in +tasks+.
+      #
+      # @param engine [Engine]
+      # @param conn [Connection]
+      # @param q [Async::LimitedQueue]
+      # @param tasks [Array]
+      # @return [Async::Task]
+      #
+      def self.start(engine, conn, q, tasks)
+        task = engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            batch = [q.dequeue]
+            Routing.drain_send_queue(q, batch)
+            batch.each { |parts| conn.write_message(parts) }
+            conn.flush
+          rescue Protocol::ZMTP::Error, *CONNECTION_LOST
+            engine.connection_lost(conn)
+            break
+          end
+        end
+        tasks << task
+        task
+      end
+    end
+  end
+end

data/lib/omq/routing/dealer.rb

@@ -8,50 +8,55 @@ module OMQ
     #
     class Dealer
       include RoundRobin
+      include FairRecv
 
       # @param engine [Engine]
       #
       def initialize(engine)
         @engine     = engine
-        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
+        @recv_queue = FairQueue.new
         @tasks      = []
         init_round_robin(engine)
       end
 
-      # @return [Async::LimitedQueue]
+
+      # @return [FairQueue]
       #
-      attr_reader :recv_queue, :send_queue
+      attr_reader :recv_queue
 
       # @param connection [Connection]
       #
       def connection_added(connection)
         @connections << connection
-        signal_connection_available
-        update_direct_pipe
-        task = @engine.start_recv_pump(connection, @recv_queue)
-        @tasks << task if task
-        start_send_pump unless @send_pump_started
+        add_fair_recv_connection(connection)
+        add_round_robin_send_connection(connection)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
         @connections.delete(connection)
-        update_direct_pipe
+        @recv_queue.remove_queue(connection)
+        remove_round_robin_send_connection(connection)
       end
 
+
       # @param parts [Array<String>]
       #
       def enqueue(parts)
         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/fair_queue.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # Per-connection recv queue aggregator.
+    #
+    # Maintains one bounded queue per connected peer. #dequeue
+    # returns the next available message from any peer in fair
+    # round-robin order, blocking until one arrives.
+    #
+    # Recv pumps do not enqueue directly — they write through a
+    # SignalingQueue wrapper, which also wakes a blocked #dequeue.
+    #
+    class FairQueue
+      # Creates an empty fair queue with no per-connection queues.
+      #
+      def initialize
+        @queues    = []              # ordered list of per-connection inner queues
+        @mapping   = {}              # connection => inner queue
+        @cycle     = @queues.cycle  # live reference — sees adds/removes
+        @condition = Async::Condition.new
+        @pending   = 0              # signals received before #dequeue waits
+        @closed    = false
+      end
+
+
+      # Registers a per-connection queue. Called when a connection is added.
+      #
+      # @param conn [Connection]
+      # @param q [Async::LimitedQueue]
+      #
+      def add_queue(conn, q)
+        @mapping[conn] = q
+        @queues << q
+      end
+
+
+      # Removes the per-connection queue for a disconnected peer.
+      #
+      # If the queue is empty it is removed immediately. If it still has
+      # pending messages it is kept in @queues so the application can drain
+      # them via #dequeue; it will be cleaned up lazily by try_dequeue once
+      # it is empty.
+      #
+      # @param conn [Connection]
+      #
+      def remove_queue(conn)
+        q = @mapping.delete(conn)
+        return unless q
+        @queues.delete(q) if q.empty?
+        # Non-empty orphaned queues stay in @queues until drained
+      end
+
+
+      # Wakes a blocked #dequeue. Called by SignalingQueue after each enqueue.
+      #
+      def signal
+        @pending += 1
+        @condition.signal
+      end
+
+
+      # Returns the next message from any per-connection queue, in fair
+      # round-robin order. Blocks until a message is available.
+      #
+      # Pass +timeout: 0+ for a non-blocking poll (returns nil immediately
+      # if no messages are available).
+      #
+      # @param timeout [Numeric, nil] 0 = non-blocking, nil = block forever
+      # @return [Array<String>, nil]
+      #
+      def dequeue(timeout: nil)
+        return try_dequeue if timeout == 0
+
+        loop do
+          return nil if @closed && @queues.all?(&:empty?)
+
+          msg = try_dequeue
+          return msg if msg
+
+          if @pending > 0
+            @pending -= 1
+            next
+          end
+
+          @condition.wait
+        end
+      end
+
+
+      # Injects a nil sentinel to unblock a waiting #dequeue.
+      # Called by Engine on close or fatal error.
+      #
+      def push(nil_sentinel)
+        @closed = true
+        @condition.signal
+      end
+
+
+      # @return [Boolean]
+      #
+      def empty?
+        @queues.all?(&:empty?)
+      end
+
+      private
+
+      # Tries each per-connection queue once in round-robin order.
+      # Returns the first message found, or nil if all are empty.
+      # Lazily removes empty orphaned queues (disconnected peers that have
+      # been fully drained).
+      #
+      def try_dequeue
+        @queues.size.times do
+          q = begin
+                @cycle.next
+              rescue StopIteration
+                @cycle = @queues.cycle
+                break
+              end
+          msg = q.dequeue(timeout: 0)
+          return msg if msg
+          if q.empty? && !@mapping.value?(q)
+            @queues.delete(q)
+            break
+          end
+        end
+        nil
+      end
+    end
+
+
+    # Wraps a per-connection bounded queue so that each #enqueue also
+    # signals the FairQueue to wake a blocked #dequeue.
+    #
+    class SignalingQueue
+      # @param inner [Async::LimitedQueue] the per-connection bounded queue
+      # @param fair_queue [FairQueue] the parent fair queue to signal on enqueue
+      #
+      def initialize(inner, fair_queue)
+        @inner = inner
+        @fair  = fair_queue
+      end
+
+
+      # Enqueues a message and signals the fair queue.
+      #
+      # @param msg [Array<String>]
+      # @return [void]
+      #
+      def enqueue(msg)
+        @inner.enqueue(msg)
+        @fair.signal
+      end
+
+
+      # @param timeout [Numeric, nil] dequeue timeout
+      # @return [Array<String>, nil]
+      #
+      def dequeue(timeout: nil) = @inner.dequeue(timeout: timeout)
+
+      # @return [Boolean]
+      #
+      def empty?                = @inner.empty?
+
+      # @param item [Object, nil]
+      # @return [void]
+      #
+      def push(item)            = @inner.push(item)
+    end
+  end
+end

data/lib/omq/routing/fair_recv.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # Mixin that adds per-connection recv queue setup for fair-queued sockets.
+    #
+    # Including classes must have @engine, @recv_queue (FairQueue), and @tasks.
+    #
+    module FairRecv
+      private
+
+      # Creates a per-connection recv queue, registers it with @recv_queue,
+      # and starts a recv pump for the connection. Called from #connection_added.
+      #
+      # @param conn [Connection]
+      # @yield [msg] optional per-message transform
+      #
+      def add_fair_recv_connection(conn, &transform)
+        conn_q    = Routing.build_queue(@engine.options.recv_hwm, :block)
+        signaling = SignalingQueue.new(conn_q, @recv_queue)
+        @recv_queue.add_queue(conn, conn_q)
+        task      = @engine.start_recv_pump(conn, signaling, &transform)
+        @tasks << task if task
+      end
+    end
+  end
+end