omq 0.9.0 → 0.11.0

data/lib/omq/options.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Pure Ruby socket options.
+  #
+  # All timeouts are in seconds (Numeric) or nil (no timeout).
+  # HWM values are integers.
+  #
+  class Options
+    DEFAULT_HWM = 1000
+
+    # @param linger [Integer] linger period in seconds (default 0)
+    #
+    def initialize(linger: 0)
+      @send_hwm              = DEFAULT_HWM
+      @recv_hwm              = DEFAULT_HWM
+      @linger                = linger
+      @identity              = "".b
+      @router_mandatory      = false
+      @read_timeout          = nil   # seconds, nil = no timeout
+      @write_timeout         = nil
+      @reconnect_interval    = 0.1   # seconds, or Range for backoff (e.g. 0.1..5.0)
+      @heartbeat_interval    = nil   # seconds, nil = disabled
+      @heartbeat_ttl         = nil   # seconds, nil = use heartbeat_interval
+      @heartbeat_timeout     = nil   # seconds, nil = use heartbeat_interval
+      @max_message_size      = nil  # bytes, nil = unlimited
+      @conflate              = false
+      @mechanism             = Protocol::ZMTP::Mechanism::Null.new
+      @tls_context           = nil  # OpenSSL::SSL::SSLContext for tls+tcp://
+    end
+
+    attr_accessor :send_hwm,  :recv_hwm,
+                  :linger,    :identity,
+                  :router_mandatory,  :conflate,
+                  :read_timeout,          :write_timeout,
+                  :reconnect_interval,
+                  :heartbeat_interval,    :heartbeat_ttl,    :heartbeat_timeout,
+                  :max_message_size,
+                  :mechanism,
+                  :tls_context
+
+    alias_method :router_mandatory?, :router_mandatory
+    alias_method :recv_timeout,      :read_timeout
+    alias_method :recv_timeout=,     :read_timeout=
+    alias_method :send_timeout,      :write_timeout
+    alias_method :send_timeout=,     :write_timeout=
+  end
+end

data/lib/omq/pair.rb

@@ -2,11 +2,11 @@
 
 module OMQ
   class PAIR < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
+    include Readable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:PAIR, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:PAIR, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end

data/lib/omq/peer.rb

@@ -2,12 +2,12 @@
 
 module OMQ
   class PEER < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
-    include ZMTP::SingleFrame
+    include Readable
+    include Writable
+    include SingleFrame
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:PEER, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:PEER, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
 

data/lib/omq/pub_sub.rb

@@ -2,10 +2,10 @@
 
 module OMQ
   class PUB < Socket
-    include ZMTP::Writable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0, conflate: false)
-      _init_engine(:PUB, linger: linger, conflate: conflate)
+    def initialize(endpoints = nil, linger: 0, conflate: false, backend: nil)
+      _init_engine(:PUB, linger: linger, conflate: conflate, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end
@@ -13,7 +13,7 @@ module OMQ
   # SUB socket.
   #
   class SUB < Socket
-    include ZMTP::Readable
+    include Readable
 
     # @return [String] subscription prefix to subscribe to everything
     #
@@ -21,13 +21,13 @@ module OMQ
 
     # @param endpoints [String, nil]
     # @param linger [Integer]
-    # @param prefix [String, nil] subscription prefix; +nil+ (default)
+    # @param subscribe [String, nil] subscription prefix; +nil+ (default)
     #   means no subscription — call {#subscribe} explicitly.
     #
-    def initialize(endpoints = nil, linger: 0, prefix: nil)
-      _init_engine(:SUB, linger: linger)
+    def initialize(endpoints = nil, linger: 0, subscribe: nil, backend: nil)
+      _init_engine(:SUB, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
-      subscribe(prefix) unless prefix.nil?
+      self.subscribe(subscribe) unless subscribe.nil?
     end
 
     # Subscribes to a topic prefix.
@@ -50,28 +50,28 @@ module OMQ
   end
 
   class XPUB < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
+    include Readable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:XPUB, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:XPUB, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end
 
   class XSUB < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
+    include Readable
+    include Writable
 
     # @param endpoints [String, nil]
     # @param linger [Integer]
-    # @param prefix [String, nil] subscription prefix; +nil+ (default)
+    # @param subscribe [String, nil] subscription prefix; +nil+ (default)
     #   means no subscription — send a subscribe frame explicitly.
     #
-    def initialize(endpoints = nil, linger: 0, prefix: nil)
-      _init_engine(:XSUB, linger: linger)
+    def initialize(endpoints = nil, linger: 0, subscribe: nil, backend: nil)
+      _init_engine(:XSUB, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
-      send("\x01#{prefix}".b) unless prefix.nil?
+      send("\x01#{subscribe}".b) unless subscribe.nil?
     end
   end
 end

data/lib/omq/push_pull.rb

@@ -2,19 +2,19 @@
 
 module OMQ
   class PUSH < Socket
-    include ZMTP::Writable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0, send_hwm: nil, send_timeout: nil)
-      _init_engine(:PUSH, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout)
+    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
 
   class PULL < Socket
-    include ZMTP::Readable
+    include Readable
 
-    def initialize(endpoints = nil, linger: 0, recv_hwm: nil, recv_timeout: nil)
-      _init_engine(:PULL, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout)
+    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)
     end
   end

data/lib/omq/queue_interface.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Async::Queue-compatible read interface.
+  #
+  # Automatically included by {Readable}. Provides #dequeue, #pop,
+  # #wait, and #each so sockets can be used where an Async::Queue
+  # is expected.
+  #
+  module QueueReadable
+    # Dequeues the next message.
+    #
+    # @param timeout [Numeric, nil] timeout in seconds (overrides
+    #   the socket's +read_timeout+ for this call)
+    # @return [Array<String>] message parts
+    # @raise [IO::TimeoutError] if timeout exceeded
+    #
+    def dequeue(timeout: @options.read_timeout)
+      msg = @recv_mutex.synchronize { @recv_buffer.shift }
+      return msg if msg
+
+      batch = Reactor.run { with_timeout(timeout) { @engine.dequeue_recv_batch(Readable::RECV_BATCH_SIZE) } }
+      msg = batch.shift
+      @recv_mutex.synchronize { @recv_buffer.concat(batch) } unless batch.empty?
+      msg
+    end
+
+    alias_method :pop, :dequeue
+
+    # Waits for the next message indefinitely (ignores read_timeout).
+    #
+    # @return [Array<String>] message parts
+    #
+    def wait
+      dequeue(timeout: nil)
+    end
+
+    # Yields each received message until the socket is closed or
+    # a receive timeout expires.
+    #
+    # @yield [Array<String>] message parts
+    # @return [void]
+    #
+    def each
+      while (msg = receive)
+        yield msg
+      end
+    rescue IO::TimeoutError
+      nil
+    end
+  end
+
+
+  # Async::Queue-compatible write interface.
+  #
+  # Automatically included by {Writable}. Provides #enqueue, #push,
+  # and #signal so sockets can be used where an Async::Queue is
+  # expected.
+  #
+  module QueueWritable
+    # Enqueues one or more messages for sending.
+    #
+    # @param messages [String, Array<String>]
+    # @return [self]
+    #
+    def enqueue(*messages)
+      messages.each { |msg| send(msg) }
+      self
+    end
+
+    alias_method :push, :enqueue
+  end
+end

data/lib/omq/radio_dish.rb

@@ -2,10 +2,10 @@
 
 module OMQ
   class RADIO < Socket
-    include ZMTP::Writable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0, conflate: false)
-      _init_engine(:RADIO, linger: linger, conflate: conflate)
+    def initialize(endpoints = nil, linger: 0, conflate: false, backend: nil)
+      _init_engine(:RADIO, linger: linger, conflate: conflate, backend: backend)
       _attach(endpoints, default: :bind)
     end
 
@@ -45,10 +45,10 @@ module OMQ
   end
 
   class DISH < Socket
-    include ZMTP::Readable
+    include Readable
 
-    def initialize(endpoints = nil, linger: 0, group: nil)
-      _init_engine(:DISH, linger: linger)
+    def initialize(endpoints = nil, linger: 0, group: nil, backend: nil)
+      _init_engine(:DISH, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
       join(group) if group
     end

data/lib/omq/reactor.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "async"
+
+module OMQ
+  # Shared IO reactor for the Ruby backend.
+  #
+  # When user code runs inside an Async reactor, engine tasks are
+  # spawned directly under the caller's Async task. When no reactor
+  # is available (e.g. bare Thread.new), a single shared IO thread
+  # hosts all engine tasks — mirroring libzmq's IO thread.
+  #
+  # Engines obtain the IO thread's root task via {.root_task} and
+  # use it as their @parent_task. Blocking operations from the main
+  # thread are dispatched to the IO thread via {.run}.
+  #
+  module Reactor
+    @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).
+      #
+      # @return [Async::Task]
+      #
+      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
+          at_exit { stop! }
+        end
+        @root_task
+      end
+
+
+      # Runs a block inside the Async reactor.
+      #
+      # Inside an Async reactor: runs directly.
+      # Outside: dispatches to the shared IO thread and blocks
+      # the calling thread until the result is available.
+      #
+      # @return [Object] the block's return value
+      #
+      def run(&block)
+        if Async::Task.current?
+          yield
+        else
+          result = Thread::Queue.new
+          root_task # ensure started
+          @work_queue.push([block, result])
+          status, value = result.pop
+          raise value if status == :error
+          value
+        end
+      end
+
+
+      # Registers a socket's linger value.
+      #
+      # @param seconds [Numeric, nil] linger value
+      #
+      def track_linger(seconds)
+        @lingers[seconds || 0] += 1
+      end
+
+
+      # Unregisters a socket's linger value.
+      #
+      # @param seconds [Numeric, nil] linger value
+      #
+      def untrack_linger(seconds)
+        key = seconds || 0
+        @lingers[key] -= 1
+        @lingers.delete(key) if @lingers[key] <= 0
+      end
+
+
+      # Stops the shared IO thread.
+      #
+      # @return [void]
+      #
+      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
+      # tasks (accept loops, pumps, etc.) run as transient children.
+      #
+      # @param ready [Thread::Queue] receives the root task once started
+      #
+      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])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/readable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module OMQ
+  # Pure Ruby Readable mixin. Dequeues messages from the engine's recv queue.
+  #
+  module Readable
+    include QueueReadable
+
+    # 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
+    # synchronized dequeue.
+    #
+    # @return [Array<String>] message parts
+    # @raise [IO::TimeoutError] if read_timeout exceeded
+    #
+    def receive
+      @recv_mutex.synchronize { @recv_buffer.shift } || fill_recv_buffer
+    end
+
+    # Waits until the socket is readable.
+    #
+    # @param timeout [Numeric, nil] timeout in seconds
+    # @return [true]
+    #
+    def wait_readable(timeout = @options.read_timeout)
+      true
+    end
+
+    private
+
+    def fill_recv_buffer
+      batch = Reactor.run { with_timeout(@options.read_timeout) { @engine.dequeue_recv_batch(RECV_BATCH_SIZE) } }
+      msg = batch.shift
+      @recv_mutex.synchronize { @recv_buffer.concat(batch) } unless batch.empty?
+      msg
+    end
+  end
+end

data/lib/omq/req_rep.rb

@@ -2,21 +2,21 @@
 
 module OMQ
   class REQ < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
+    include Readable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:REQ, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:REQ, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
 
   class REP < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
+    include Readable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:REP, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:REP, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end

data/lib/omq/router_dealer.rb

@@ -2,11 +2,11 @@
 
 module OMQ
   class DEALER < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
+    include Readable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:DEALER, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:DEALER, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
@@ -14,11 +14,11 @@ module OMQ
   # ROUTER socket.
   #
   class ROUTER < Socket
-    include ZMTP::Readable
-    include ZMTP::Writable
+    include Readable
+    include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:ROUTER, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:ROUTER, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)
     end
 

data/lib/omq/routing/channel.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # CHANNEL socket routing: exclusive 1-to-1 bidirectional.
+    #
+    class Channel
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine     = engine
+        @connection = nil
+        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @send_queue = Async::LimitedQueue.new(engine.options.send_hwm)
+        @tasks          = []
+        @send_pump_idle = true
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue, :send_queue
+
+      # @param connection [Connection]
+      # @raise [RuntimeError] if a connection already exists
+      #
+      def connection_added(connection)
+        raise "CHANNEL allows only one peer" if @connection
+        @connection = connection
+        task = @engine.start_recv_pump(connection, @recv_queue)
+        @tasks << task if task
+        start_send_pump(connection) unless connection.is_a?(Transport::Inproc::DirectPipe)
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        if @connection == connection
+          @connection = nil
+          @send_pump&.stop
+          @send_pump = nil
+        end
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        conn = @connection
+        if conn.is_a?(Transport::Inproc::DirectPipe) && conn.direct_recv_queue
+          conn.send_message(parts)
+        else
+          @send_queue.enqueue(parts)
+        end
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      def send_pump_idle? = @send_pump_idle
+
+      private
+
+      def start_send_pump(conn)
+        @send_pump = @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+            batch.each { |parts| conn.write_message(parts) }
+            conn.flush
+          end
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+        @tasks << @send_pump
+      end
+    end
+  end
+end

data/lib/omq/routing/client.rb

@@ -0,0 +1,56 @@
+# 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
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @tasks      = []
+        init_round_robin(engine)
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue, :send_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
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        update_direct_pipe
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+    end
+  end
+end