omq 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6800afbb9c1e8dd9f7a973f7105ff94a13bf99bc4f6a5c302fc3ff7c2ee3220a
-  data.tar.gz: a166c7b6d54596565574b24183d64c649b8a58c8d826bf3074eb800cb9f0f52f
+  metadata.gz: f24ac91fe456168b4d369f63506cf1d3d2b48488637ce767363aa17bb542d2b3
+  data.tar.gz: ca1b98ab4083ad90f7f483bc9df937656ae9862c9fd07800fc46315543e5fe75
 SHA512:
-  metadata.gz: 50c173ee88a276291a82864adadeb11500265d3df24164de183407af0b1586498105b4a837a75027f2762b5a91a9f70ad6dbf0a718f9dc179e920ba3a238e266
-  data.tar.gz: da22b101249f108c9dc59763f1589fb1cd350b73bdbd62a3f59424079db68cb892bc1a93052cab603ae0f62eefb35fee1ff3a10743f500ed68dab622d3a3a027
+  metadata.gz: 16f20fa600ebd66228589da4e03efc809a616d6a74fbe3460a8ced6811349fb86903e43a440708e1e78f102af711d6f9ea3ebf9cbc0e7fb4aef9591db5061e39
+  data.tar.gz: 89ff3da1bb5caa2223d1e323a389cacc4f270fed719902dbd0721c56da8ff5c0a1cbf1e6eebc59c8386f470c433c69dfb20462d46f84c9a2fa848b3e1364dfd0

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.21.0 — 2026-04-15
+
+### Changed
+
+- **Recv path: shared queue, no more `FairQueue`.** Every fair-queue
+  routing strategy (Pull, Pair, Rep, Dealer, Router, Req, Sub, XSub)
+  now owns a single `Async::LimitedQueue` sized to `recv_hwm`. Each
+  connection's recv pump writes directly into it. `FairQueue`,
+  `SignalingQueue`, and the `FairRecv` mixin are deleted. Cross-peer
+  fairness comes entirely from the pump yield limit; per-connection
+  ordering is preserved; cross-connection ordering was never a
+  guarantee. Symmetric with the send side, which already uses one
+  work-stealing queue per socket. Sister gems (channel, clientserver,
+  p2p, radiodish, scattergather, qos) updated to match.
+- **Recv pump fairness bumped to 256 msgs / 512 KiB** (was 64 / 1 MiB),
+  symmetric with `RoundRobin::BATCH_MSG_CAP` / `BATCH_BYTE_CAP` on the
+  send side.
+
+### Added
+
+- **`Socket#attach_endpoints` accepts arrays.** Constructors passed an
+  array of endpoint strings now bind/connect each one in order, so
+  `OMQ::SUB.new(["inproc://a", "inproc://b"])` works.
+- **PUB/SUB regression test** for a SUB with sequential post-hoc
+  `#connect` calls to multiple bound PUBs, mirroring the SCATTER/GATHER
+  post-hoc-connect coverage.
+- **DESIGN.md: "Libzmq quirks OMQ avoids"** — per-pipe HWM (actual
+  buffering is `send_hwm × N_peers`, forces strict RR, slow-worker
+  stall footgun) and the edge-triggered `ZMQ_FD` that fires spuriously
+  and misses edges, requiring the `ZMQ_EVENTS` / `ZMQ_DONTWAIT` dance.
+  README "Socket Types" condensed to a pointer at DESIGN.md.
+
 ## 0.20.0 — 2026-04-14
 
 ### Changed

data/README.md

@@ -5,29 +5,45 @@
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
 
-> **932k msg/s** inproc | **328k msg/s** ipc | **329k msg/s** tcp
+> **1.23M msg/s** inproc | **361k msg/s** ipc | **358k msg/s** tcp
 >
-> **11.5 µs** inproc latency | **54 µs** ipc | **69 µs** tcp
+> **9.1 µs** inproc latency | **49 µs** ipc | **64 µs** tcp
 >
 > Ruby 4.0 + YJIT on a Linux VM — see [`bench/`](bench/) for full results
 
-`gem install omq` and you're done. No libzmq, no compiler, no system packages — just Ruby talking to every other ZeroMQ peer out there.
+`gem install omq` and you're done. No libzmq, no compiler, no system packages —
+just Ruby talking to every other ZeroMQ peer out there.
 
-ØMQ gives your Ruby processes a way to talk to each other — and to anything else speaking ZeroMQ — without a broker in the middle. Same API whether they live in the same process, on the same machine, or across the network. Reconnects, queuing, and back-pressure are handled for you; you write the interesting part.
+ØMQ gives your Ruby processes a way to talk to each other — and to anything
+else speaking ZeroMQ — without a broker in the middle. Same API whether they
+live in the same process, on the same machine, or across the network.
+Reconnects, queuing, and back-pressure are handled for you; you write the
+interesting part.
 
-New to ZeroMQ? Start with [GETTING_STARTED.md](GETTING_STARTED.md) — a ~30 min walkthrough of every major pattern with working code.
+New to ZeroMQ? Start with [GETTING_STARTED.md](GETTING_STARTED.md) — a ~30 min
+walkthrough of every major pattern with working code.
 
 ## Highlights
 
-- **Zero dependencies on C** — no extensions, no FFI, no libzmq. `gem install` just works everywhere
-- **Fast** — YJIT-optimized hot paths, batched sends, GC-tuned allocations, buffered I/O via [io-stream](https://github.com/socketry/io-stream), direct-pipe inproc bypass
-- **[`omq` CLI](https://github.com/paddor/omq-cli)** — a powerful swiss army knife for ØMQ. `gem install omq-cli`
-- **Every socket pattern** — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair, and all draft types
-- **Every transport** — tcp, ipc (Unix domain sockets), inproc (in-process queues)
+- **Zero dependencies on C** — no extensions, no FFI, no libzmq. `gem install`
+  just works everywhere
+- **Fast** — YJIT-optimized hot paths, batched sends, GC-tuned allocations,
+  buffered I/O via [io-stream](https://github.com/socketry/io-stream),
+  direct-pipe inproc bypass
+- **[`omq` CLI](https://github.com/paddor/omq-cli)** — a powerful swiss army
+  knife for ØMQ. `gem install omq-cli`
+- **Every socket pattern** — req/rep, pub/sub, push/pull, dealer/router,
+  xpub/xsub, pair, and all draft types
+- **Every transport** — tcp, ipc (Unix domain sockets), inproc (in-process
+  queues)
 - **Async-native** — built on fibers, non-blocking from the ground up
-- **Works outside Async too** — a shared IO thread handles sockets for callers that aren't inside a reactor, so simple scripts just work
-- **Wire-compatible** — interoperates with libzmq, pyzmq, CZMQ, zmq.rs over tcp and ipc
-- **Bind/connect order doesn't matter** — connect before bind, bind before connect, peers come and go. ZeroMQ reconnects automatically and queued messages drain when peers arrive
+- **Works outside Async too** — a shared IO thread handles sockets for callers
+  that aren't inside a reactor, so simple scripts just work
+- **Wire-compatible** — interoperates with libzmq, pyzmq, CZMQ, zmq.rs over tcp
+  and ipc
+- **Bind/connect order doesn't matter** — connect before bind, bind before
+  connect, peers come and go. ZeroMQ reconnects automatically and queued
+  messages drain when peers arrive
 
 For architecture internals, see [DESIGN.md](DESIGN.md).
 
@@ -99,7 +115,8 @@ end
 
 ### Without Async (IO thread)
 
-OMQ spawns a shared `omq-io` thread when used outside an Async reactor — no boilerplate needed:
+OMQ spawns a shared `omq-io` thread when used outside an Async reactor — no
+boilerplate needed:
 
 ```ruby
 require 'omq'
@@ -114,7 +131,8 @@ push.close
 pull.close
 ```
 
-The IO thread runs all pumps, reconnection, and heartbeating in the background. When you're inside an `Async` block, OMQ uses the existing reactor instead.
+The IO thread runs all pumps, reconnection, and heartbeating in the background.
+When you're inside an `Async` block, OMQ uses the existing reactor instead.
 
 ### Queue Interface
 
@@ -138,7 +156,11 @@ end
 
 ## Socket Types
 
-All sockets are thread-safe. Default HWM is 1000 messages per socket. `max_message_size` defaults to **`nil` (unlimited)** — set `socket.max_message_size = N` to cap inbound frames at `N` bytes; oversized frames cause the connection to be dropped before the body is read from the wire. Classes live under `OMQ::` (alias: `ØMQ`).
+All sockets are thread-safe. Default HWM is 1000 messages per socket.
+`max_message_size` defaults to **`nil` (unlimited)** — set
+`socket.max_message_size = N` to cap inbound frames at `N` bytes; oversized
+frames cause the connection to be dropped before the body is read from the
+wire. Classes live under `OMQ::` (alias: `ØMQ`).
 
 #### Standard (multipart messages)
 
@@ -151,7 +173,11 @@ All sockets are thread-safe. Default HWM is 1000 messages per socket. `max_messa
 | **XPUB** / **XSUB** | Fan-out (subscription events) | Fair-queue | Drop |
 | **PAIR** | Exclusive 1-to-1 | Exclusive 1-to-1 | Block |
 
-> **Work-stealing vs. round-robin.** libzmq uses strict per-pipe round-robin for outbound load balancing — message N goes to peer N mod K regardless of whether that peer is busy. OMQ uses **work-stealing**: one shared send queue per socket and N pump fibers that race to drain it. Whichever pump is ready next picks up the next batch, so a slow peer can't stall the pipeline. The trade-off: distribution is not strict round-robin under bursts. If a producer enqueues a large burst before any pump fiber gets scheduled, the first pump to wake will dequeue up to one whole batch (256 messages or 512 KB, whichever hits first) in a single non-blocking drain — so a tight `n.times { sock << msg }` loop on a small `n` may dump everything on one peer. Slow or steady producers don't see this: each pump dequeues one message, writes, re-parks, and the FIFO wait queue gives every pump a fair turn. Burst distribution also evens out once the burst exceeds one pump's batch cap. See [DESIGN.md](DESIGN.md#per-socket-hwm-not-per-connection) for the full reasoning.
+> **Work-stealing, not round-robin.** Outbound load balancing uses one shared
+> send queue per socket drained by N racing pump fibers, so a slow peer can't
+> stall the pipeline. Under tight bursts on small `n`, distribution isn't
+> strict RR. See [DESIGN.md](DESIGN.md#per-socket-hwm-not-per-connection) and
+> [Libzmq quirks](DESIGN.md#libzmq-quirks-omq-avoids) for the reasoning.
 
 #### Draft (single-frame only)
 
@@ -167,7 +193,8 @@ Each draft pattern lives in its own gem — install only the ones you use.
 
 ## CLI
 
-Install [omq-cli](https://github.com/paddor/omq-cli) for a command-line tool that sends, receives, pipes, and transforms ZeroMQ messages from the terminal:
+Install [omq-cli](https://github.com/paddor/omq-cli) for a command-line tool
+that sends, receives, pipes, and transforms ZeroMQ messages from the terminal:
 
 ```sh
 gem install omq-cli
@@ -180,14 +207,21 @@ See the [omq-cli README](https://github.com/paddor/omq-cli) for full documentati
 
 ## Companion Gems
 
-- **[omq-ffi](https://github.com/paddor/omq-ffi)** — libzmq FFI backend. Same OMQ socket API, but backed by libzmq instead of the pure Ruby ZMTP stack. Useful for interop testing and when you need libzmq-specific features. Requires libzmq installed.
-- **[omq-ractor](https://github.com/paddor/omq-ractor)** — bridge OMQ sockets into Ruby Ractors for true parallel processing across cores. I/O stays on the main Ractor, worker Ractors do pure computation.
+- **[omq-ffi](https://github.com/paddor/omq-ffi)** — libzmq FFI backend. Same
+  OMQ socket API, but backed by libzmq instead of the pure Ruby ZMTP stack.
+  Useful for interop testing and when you need libzmq-specific features.
+  Requires libzmq installed.
+- **[omq-ractor](https://github.com/paddor/omq-ractor)** — bridge OMQ sockets
+  into Ruby Ractors for true parallel processing across cores. I/O stays on the
+  main Ractor, worker Ractors do pure computation.
 
 ### Protocol extensions (RFCs)
 
-Optional plug-ins that extend the ZMTP wire protocol. Each is a separate gem; load the ones you need.
+Optional plug-ins that extend the ZMTP wire protocol. Each is a separate gem;
+load the ones you need.
 
-- **[omq-rfc-zstd](https://github.com/paddor/omq-rfc-zstd)** — transparent Zstandard compression on the wire, negotiated per peer via READY properties.
+- **[omq-rfc-zstd](https://github.com/paddor/omq-rfc-zstd)** — transparent
+  Zstandard compression on the wire, negotiated per peer via READY properties.
 
 ## Development
 

data/lib/omq/engine/recv_pump.rb

@@ -15,22 +15,22 @@ module OMQ
     class RecvPump
       # Max messages read from one connection before yielding to the
       # scheduler. Prevents a busy peer from starving its siblings in
-      # fair-queue recv sockets.
-      FAIRNESS_MESSAGES = 64
+      # fair-queue recv sockets. Symmetric with RoundRobin send batching.
+      FAIRNESS_MESSAGES = 256
 
 
       # Max bytes read from one connection before yielding. Only counted
       # for ZMTP connections (inproc skips the check). Complements
       # {FAIRNESS_MESSAGES}: small-message floods are bounded by count,
-      # large-message floods by bytes.
-      FAIRNESS_BYTES    = 1 << 20 # 1 MB
+      # large-message floods by bytes. Symmetric with RoundRobin send batching.
+      FAIRNESS_BYTES    = 512 * 1024
 
 
       # Public entry point — callers use the class method.
       #
       # @param parent [Async::Task, Async::Barrier] parent to spawn under
       # @param conn [Connection, Transport::Inproc::DirectPipe]
-      # @param recv_queue [SignalingQueue]
+      # @param recv_queue [Async::LimitedQueue]
       # @param engine [Engine]
       # @param transform [Proc, nil]
       # @return [Async::Task, nil]
@@ -41,7 +41,7 @@ module OMQ
 
 
       # @param conn [Connection, Transport::Inproc::DirectPipe]
-      # @param recv_queue [Routing::SignalingQueue]
+      # @param recv_queue [Async::LimitedQueue]
       # @param engine [Engine]
       #
       def initialize(conn, recv_queue, engine)

data/lib/omq/engine.rb

@@ -273,7 +273,7 @@ module OMQ
     # Starts a recv pump for a connection, or wires the inproc fast path.
     #
     # @param conn [Connection, Transport::Inproc::DirectPipe]
-    # @param recv_queue [SignalingQueue]
+    # @param recv_queue [Async::LimitedQueue]
     # @yield [msg] optional per-message transform
     # @return [Async::Task, nil]
     #

data/lib/omq/routing/dealer.rb

@@ -8,10 +8,9 @@ module OMQ
     #
     class Dealer
       include RoundRobin
-      include FairRecv
 
 
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
@@ -20,16 +19,35 @@ module OMQ
       #
       def initialize(engine)
         @engine     = engine
-        @recv_queue = FairQueue.new
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
         @tasks      = []
         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 [Connection]
       #
       def connection_added(connection)
-        add_fair_recv_connection(connection)
+        task = @engine.start_recv_pump(connection, @recv_queue)
+        @tasks << task if task
         add_round_robin_send_connection(connection)
       end
 
@@ -38,7 +56,6 @@ module OMQ
       #
       def connection_removed(connection)
         @connections.delete(connection)
-        @recv_queue.remove_queue(connection)
         remove_round_robin_send_connection(connection)
       end
 

data/lib/omq/routing/pair.rb

@@ -10,10 +10,7 @@ module OMQ
     # the in-flight batch is dropped (matching libzmq).
     #
     class Pair
-      include FairRecv
-
-
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
@@ -23,13 +20,31 @@ module OMQ
       def initialize(engine)
         @engine     = engine
         @connection = nil
-        @recv_queue = FairQueue.new
-        @send_queue = Routing.build_queue(@engine.options.send_hwm, :block)
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
+        @send_queue = Routing.build_queue(engine.options.send_hwm, :block)
         @send_pump  = nil
         @tasks      = []
       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 [Connection]
       # @raise [RuntimeError] if a connection already exists
       #
@@ -37,7 +52,8 @@ module OMQ
         raise "PAIR allows only one peer" if @connection
         @connection = connection
 
-        add_fair_recv_connection(connection)
+        task = @engine.start_recv_pump(connection, @recv_queue)
+        @tasks << task if task
 
         unless connection.is_a?(Transport::Inproc::DirectPipe)
           start_send_pump(connection)
@@ -50,7 +66,6 @@ module OMQ
       def connection_removed(connection)
         if @connection == connection
           @connection = nil
-          @recv_queue.remove_queue(connection)
           @send_pump&.stop
           @send_pump = nil
         end

data/lib/omq/routing/pull.rb

@@ -5,35 +5,52 @@ module OMQ
     # PULL socket routing: fair-queue receive from PUSH peers.
     #
     class Pull
-      include FairRecv
-
-
       # @param engine [Engine]
       #
       def initialize(engine)
         @engine     = engine
-        @recv_queue = FairQueue.new
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
         @tasks      = []
       end
 
 
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
 
+      # Dequeues the next received message. Blocks until one is available.
+      # Engine-facing contract — Engine must not touch @recv_queue directly.
+      #
+      # @return [Array<String>, nil]
+      #
+      def dequeue_recv
+        @recv_queue.dequeue
+      end
+
+
+      # Wakes a blocked {#dequeue_recv} with a nil sentinel. Called by
+      # Engine on close or fatal-error propagation.
+      #
+      # @return [void]
+      #
+      def unblock_recv
+        @recv_queue.enqueue(nil)
+      end
+
+
       # @param connection [Connection]
       #
       def connection_added(connection)
-        add_fair_recv_connection(connection)
+        task = @engine.start_recv_pump(connection, @recv_queue)
+        @tasks << task if task
       end
 
 
       # @param connection [Connection]
       #
       def connection_removed(connection)
-        @recv_queue.remove_queue(connection)
-        # recv pump stops on EOFError
+        # recv pump stops on EOFError via its connection barrier
       end
 
 

data/lib/omq/routing/rep.rb

@@ -9,12 +9,10 @@ module OMQ
     # on send.
     #
     class Rep
-      include FairRecv
-
       EMPTY_FRAME = "".b.freeze
 
 
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
@@ -23,7 +21,7 @@ module OMQ
       #
       def initialize(engine)
         @engine          = engine
-        @recv_queue      = FairQueue.new
+        @recv_queue      = Routing.build_queue(engine.options.recv_hwm, :block)
         @pending_replies = []
         @conn_queues     = {}  # connection => per-connection send queue
         @conn_send_tasks = {}  # connection => send pump task
@@ -31,10 +29,28 @@ module OMQ
       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 [Connection]
       #
       def connection_added(connection)
-        add_fair_recv_connection(connection) do |msg|
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
           delimiter = msg.index { |p| p.empty? } || msg.size
           envelope  = msg[0, delimiter]
           body      = msg[(delimiter + 1)..] || []
@@ -42,6 +58,7 @@ module OMQ
           @pending_replies << { conn: connection, envelope: envelope }
           body
         end
+        @tasks << task if task
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
         @conn_queues[connection] = q
@@ -53,7 +70,6 @@ module OMQ
       #
       def connection_removed(connection)
         @pending_replies.reject! { |r| r[:conn] == connection }
-        @recv_queue.remove_queue(connection)
         @conn_queues.delete(connection)
         @conn_send_tasks.delete(connection)&.stop
       end

data/lib/omq/routing/req.rb

@@ -8,13 +8,12 @@ module OMQ
     #
     class Req
       include RoundRobin
-      include FairRecv
 
       # Shared frozen empty binary string to avoid repeated allocations.
       EMPTY_BINARY = ::Protocol::ZMTP::Codec::EMPTY_BINARY
 
 
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
@@ -23,20 +22,40 @@ module OMQ
       #
       def initialize(engine)
         @engine          = engine
-        @recv_queue      = FairQueue.new
+        @recv_queue      = Routing.build_queue(engine.options.recv_hwm, :block)
         @tasks           = []
         @state           = :ready        # :ready or :waiting_reply
         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 [Connection]
       #
       def connection_added(connection)
-        add_fair_recv_connection(connection) do |msg|
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
           @state = :ready
           msg.first&.empty? ? msg[1..] : msg
         end
+
+        @tasks << task if task
         add_round_robin_send_connection(connection)
       end
 
@@ -45,7 +64,6 @@ module OMQ
       #
       def connection_removed(connection)
         @connections.delete(connection)
-        @recv_queue.remove_queue(connection)
         remove_round_robin_send_connection(connection)
       end
 

data/lib/omq/routing/round_robin.rb

@@ -159,6 +159,7 @@ module OMQ
 
       def drain_send_queue_capped(batch)
         bytes = batch_bytes(batch.first)
+
         while batch.size < BATCH_MSG_CAP && bytes < BATCH_BYTE_CAP
           msg = @send_queue.dequeue(timeout: 0)
           break unless msg

data/lib/omq/routing/router.rb

@@ -11,10 +11,7 @@ module OMQ
     # routing identity on send.
     #
     class Router
-      include FairRecv
-
-
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
@@ -23,7 +20,7 @@ module OMQ
       #
       def initialize(engine)
         @engine                  = engine
-        @recv_queue              = FairQueue.new
+        @recv_queue              = Routing.build_queue(engine.options.recv_hwm, :block)
         @connections_by_identity = {}
         @identity_by_connection  = {}
         @conn_queues             = {}  # connection => per-connection send queue
@@ -32,6 +29,24 @@ module OMQ
       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 [Connection]
       #
       def connection_added(connection)
@@ -40,7 +55,8 @@ module OMQ
         @connections_by_identity[identity] = connection
         @identity_by_connection[connection] = identity
 
-        add_fair_recv_connection(connection) { |msg| [identity, *msg] }
+        task = @engine.start_recv_pump(connection, @recv_queue) { |msg| [identity, *msg] }
+        @tasks << task if task
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
         @conn_queues[connection] = q
@@ -53,7 +69,6 @@ module OMQ
       def connection_removed(connection)
         identity = @identity_by_connection.delete(connection)
         @connections_by_identity.delete(identity) if identity
-        @recv_queue.remove_queue(connection)
         @conn_queues.delete(connection)
         @conn_send_tasks.delete(connection)&.stop
       end

data/lib/omq/routing/sub.rb

@@ -8,7 +8,7 @@ module OMQ
     #
     class Sub
 
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
@@ -18,21 +18,27 @@ module OMQ
       def initialize(engine)
         @engine        = engine
         @connections   = Set.new
-        @recv_queue    = FairQueue.new
+        @recv_queue    = Routing.build_queue(engine.options.recv_hwm, :block)
         @subscriptions = Set.new
         @tasks         = []
       end
 
 
-      # Engine-facing recv contract. Delegates to the FairQueue.
+      # 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.push(nil)
+        @recv_queue.enqueue(nil)
       end
 
 
@@ -40,13 +46,12 @@ module OMQ
       #
       def connection_added(connection)
         @connections << connection
+
         @subscriptions.each do |prefix|
           connection.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
         end
-        conn_q    = Routing.build_queue(@engine.options.recv_hwm, @engine.options.on_mute)
-        signaling = SignalingQueue.new(conn_q, @recv_queue)
-        @recv_queue.add_queue(connection, conn_q)
-        task = @engine.start_recv_pump(connection, signaling)
+
+        task = @engine.start_recv_pump(connection, @recv_queue)
         @tasks << task if task
       end
 
@@ -55,7 +60,6 @@ module OMQ
       #
       def connection_removed(connection)
         @connections.delete(connection)
-        @recv_queue.remove_queue(connection)
       end
 
 

data/lib/omq/routing/xpub.rb

@@ -8,8 +8,8 @@ module OMQ
     # the application as data frames: \x01 + prefix for subscribe,
     # \x00 + prefix for unsubscribe.
     #
-    # The recv_queue is a simple bounded queue (not a FairQueue) because
-    # messages come from subscription commands, not from peer data pumps.
+    # The recv_queue is a simple bounded queue because messages come from
+    # subscription commands, not from peer data pumps.
     #
     class XPub
       include FanOut
@@ -25,6 +25,7 @@ module OMQ
         @engine     = engine
         @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
         @tasks      = []
+
         init_fan_out(engine)
       end
 

data/lib/omq/routing/xsub.rb

@@ -10,7 +10,7 @@ module OMQ
     #
     class XSub
 
-      # @return [FairQueue]
+      # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
 
@@ -20,22 +20,28 @@ module OMQ
       def initialize(engine)
         @engine          = engine
         @connections     = Set.new
-        @recv_queue      = FairQueue.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           = []
       end
 
 
-      # Engine-facing recv contract. Delegates to the FairQueue.
+      # 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.push(nil)
+        @recv_queue.enqueue(nil)
       end
 
 
@@ -44,10 +50,7 @@ module OMQ
       def connection_added(connection)
         @connections << connection
 
-        conn_q    = Routing.build_queue(@engine.options.recv_hwm, @engine.options.on_mute)
-        signaling = SignalingQueue.new(conn_q, @recv_queue)
-        @recv_queue.add_queue(connection, conn_q)
-        task = @engine.start_recv_pump(connection, signaling)
+        task = @engine.start_recv_pump(connection, @recv_queue)
         @tasks << task if task
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
@@ -60,7 +63,6 @@ module OMQ
       #
       def connection_removed(connection)
         @connections.delete(connection)
-        @recv_queue.remove_queue(connection)
         @conn_queues.delete(connection)
         @conn_send_tasks.delete(connection)&.stop
       end

data/lib/omq/routing.rb

@@ -4,8 +4,6 @@ require "async"
 require "async/queue"
 require "async/limited_queue"
 require_relative "drop_queue"
-require_relative "routing/fair_queue"
-require_relative "routing/fair_recv"
 require_relative "routing/conn_send_pump"
 
 module OMQ

data/lib/omq/socket.rb

@@ -298,6 +298,11 @@ module OMQ
     def attach_endpoints(endpoints, default:)
       return unless endpoints
 
+      if endpoints.is_a?(Array)
+        endpoints.each { |ep| attach_endpoints(ep, default: default) }
+        return
+      end
+
       case endpoints
       when /\A@(.+)\z/
         bind($1)

data/lib/omq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OMQ
-  VERSION = "0.20.0"
+  VERSION = "0.21.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -86,8 +86,6 @@ files:
 - lib/omq/routing.rb
 - lib/omq/routing/conn_send_pump.rb
 - lib/omq/routing/dealer.rb
-- lib/omq/routing/fair_queue.rb
-- lib/omq/routing/fair_recv.rb
 - lib/omq/routing/fan_out.rb
 - lib/omq/routing/pair.rb
 - lib/omq/routing/pub.rb

data/lib/omq/routing/fair_queue.rb

@@ -1,197 +0,0 @@
-# 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
-        @drain     = []              # orphaned queues, drained before active 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 still has pending messages it moves to the
-      # priority drain list so those messages are consumed before
-      # any active connection's messages — preserving FIFO for
-      # sequential connections.
-      #
-      # @param conn [Connection]
-      #
-      def remove_queue(conn)
-        q = @mapping.delete(conn)
-        return unless q
-        @queues.delete(q)
-        @drain << q unless q.empty?
-      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
-          if @closed && @drain.empty? && @queues.all? { |q| q.empty? }
-            return nil
-          end
-
-          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?
-        @drain.empty? && @queues.all? { |q| q.empty? }
-      end
-
-
-      private
-
-
-      # Drains orphaned queues first (preserves FIFO for disconnected
-      # peers), then tries each active queue once in round-robin order.
-      #
-      def try_dequeue
-        # Priority: drain orphaned queues before serving active ones
-        until @drain.empty?
-          msg = @drain.first.dequeue(timeout: 0)
-          if msg
-            return msg
-          else
-            @drain.shift
-          end
-        end
-
-        # Single-connection fast path: skip Enumerator#next entirely.
-        # The vast majority of sockets have exactly one peer.
-        if @queues.size == 1
-          return @queues.first.dequeue(timeout: 0)
-        end
-
-        @queues.size.times do
-          q = begin
-                @cycle.next
-              rescue StopIteration
-                @cycle = @queues.cycle
-                break
-              end
-          msg = q.dequeue(timeout: 0)
-          return msg if msg
-        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)
-      end
-
-
-      # @return [Boolean]
-      #
-      def empty?
-        @inner.empty?
-      end
-
-
-      # @param item [Object, nil]
-      # @return [void]
-      #
-      def push(item)
-        @inner.push(item)
-      end
-
-    end
-  end
-end

data/lib/omq/routing/fair_recv.rb

@@ -1,53 +0,0 @@
-# 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
-      # Dequeues the next received message. Blocks until one is available.
-      # Engine-facing contract — Engine must not touch @recv_queue directly.
-      #
-      # @return [Array<String>, nil]
-      #
-      def dequeue_recv
-        @recv_queue.dequeue
-      end
-
-
-      # Wakes a blocked {#dequeue_recv} with a nil sentinel. Called by
-      # Engine on close (close_read) or fatal-error propagation.
-      #
-      # @return [void]
-      #
-      def unblock_recv
-        @recv_queue.push(nil)
-      end
-
-
-      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)
-
-        if task
-          @tasks << task
-        end
-      end
-
-    end
-  end
-end