omq 0.17.9 → 0.19.0

data/lib/omq/reactor.rb

@@ -15,12 +15,15 @@ module OMQ
   # thread are dispatched to the IO thread via {.run}.
   #
   module Reactor
+    THREAD_NAME = 'omq-io'
+
     @mutex      = Mutex.new
     @thread     = nil
     @root_task  = nil
     @work_queue = nil
     @lingers    = Hash.new(0) # linger value → count of active sockets
 
+
     class << self
       # Returns the root Async task inside the shared IO thread.
       # Starts the thread exactly once (double-checked lock).
@@ -29,15 +32,19 @@ module OMQ
       #
       def root_task
         return @root_task if @root_task
+
         @mutex.synchronize do
           return @root_task if @root_task
-          ready       = Thread::Queue.new
-          @work_queue = Async::Queue.new
-          @thread     = Thread.new { run_reactor(ready) }
-          @thread.name = "omq-io"
-          @root_task = ready.pop
+
+          ready        = Thread::Queue.new
+          @work_queue  = Async::Queue.new
+          @thread      = Thread.new { run_reactor(ready) }
+          @thread.name = THREAD_NAME
+          @root_task   = ready.pop
+
           at_exit { stop! }
         end
+
         @root_task
       end
 
@@ -50,16 +57,20 @@ module OMQ
       #
       # @return [Object] the block's return value
       #
-      def run(&block)
-        if Async::Task.current?
-          yield
+      def run(timeout: nil, &block)
+        task = Async::Task.current?
+
+        if task
+          if timeout
+            task.with_timeout(timeout, IO::TimeoutError) { yield }
+          else
+            yield
+          end
         else
-          result = Thread::Queue.new
+          result = Async::Promise.new
           root_task # ensure started
-          @work_queue.push([block, result])
-          status, value = result.pop
-          raise value if status == :error
-          value
+          @work_queue.push([block, result, timeout])
+          result.wait
         end
       end
 
@@ -90,17 +101,21 @@ module OMQ
       #
       def stop!
         return unless @thread&.alive?
+
         max_linger = @lingers.empty? ? 0 : @lingers.keys.max
         @work_queue&.push(nil)
         @thread&.join(max_linger + 1)
+
         @thread     = nil
         @root_task  = nil
         @work_queue = nil
         @lingers    = Hash.new(0)
       end
 
+
       private
 
+
       # Runs the shared Async reactor.
       #
       # Processes work items dispatched via {.run} while engine
@@ -111,18 +126,24 @@ module OMQ
       def run_reactor(ready)
         Async do |task|
           ready.push(task)
+
           loop do
-            item = @work_queue.dequeue
-            break if item.nil?
-            block, result = item
-            task.async do
-              result.push([:ok, block.call])
-            rescue => e
-              result.push([:error, e])
+            item = @work_queue.dequeue or break
+            block, result, timeout = item
+
+            task.async do |t|
+              if timeout
+                result.fulfill do
+                  t.with_timeout(timeout, IO::TimeoutError) { block.call }
+                end
+              else
+                result.fulfill { block.call }
+              end
             end
           end
         end
       end
+
     end
   end
 end

data/lib/omq/readable.rb

@@ -14,7 +14,9 @@ module OMQ
     # @raise [IO::TimeoutError] if read_timeout exceeded
     #
     def receive
-      Reactor.run { with_timeout(@options.read_timeout) { @engine.dequeue_recv } }
+      Reactor.run timeout: @options.read_timeout do |task|
+        @engine.dequeue_recv
+      end
     end
 
 

data/lib/omq/req_rep.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(:REQ, linger: linger, backend: backend)
-      _attach(endpoints, default: :connect)
+      init_engine(:REQ, 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(:REP, linger: linger, backend: backend)
-      _attach(endpoints, default: :bind)
+      init_engine(:REP, linger: linger, backend: backend)
+      attach_endpoints(endpoints, default: :bind)
     end
   end
 end

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,19 @@ 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 { |parts| engine.emit_verbose_msg_sent(conn, parts) }
           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
@@ -163,38 +179,59 @@ module OMQ
             Routing.drain_send_queue(q, batch)
             if write_matching_batch(conn, batch, use_wire)
               conn.flush
-              batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
+              batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
             end
           end
         end
       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)
+            @engine.emit_verbose_msg_sent(conn, latest)
           end
         end
       end
+
     end
   end
 end

data/lib/omq/routing/pair.rb

@@ -96,7 +96,7 @@ module OMQ
               conn.write_messages(batch)
             end
             conn.flush
-            batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
+            batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
           end
         end
         @tasks << @send_pump

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/round_robin.rb

@@ -134,7 +134,7 @@ module OMQ
             ensure
               @in_flight -= batch.size
             end
-            batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
+            batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
             Async::Task.current.yield
           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