omq 0.16.2 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 856ca133b440ec0812ec17c9a470ce25d69a405f0d3fdbedb04194a4ac60527e
-  data.tar.gz: 8b01aceb4098b436ad0c69f0c62930d6fafe8372bf6cbc77004cb4569936c6be
+  metadata.gz: ec5d4d1943efe37da6ad5493f80591b9578467e0c470fd4e2a577968580609cd
+  data.tar.gz: 8476b90cc637629874c94388cd91ae7a6f3ce3aaac410af1aa77c3fbd6470412
 SHA512:
-  metadata.gz: 7b08a46d592cc3ba300991aaab8b99cbb22c377520b10bee9a8e67537d714474707113b15e8202a3f3b5bf277d8796b8ff0670f63e6cb850721d4a18374aac2b
-  data.tar.gz: 7cb4caa364be3a387f4aaa531b4019fa075d434b2d243507892cc7ae6dbe13f0b9b2c201564f703ff4fc5ed42b27f714753ae870c4fcd9af47ab102afdcb3bf3
+  metadata.gz: 67b62142c8786b9594efdf5f62f0aef8b5329498a04faafec760305cb73d3de354b6f4dd7f5db3e416f4e69e683b1c60ad7920a879fb72c7942d602af2088715
+  data.tar.gz: 2731913ad5262a1d0038af1887b3c2bb167df719b650dd99d3d59812573180adb0e528eeaafba021823f12d7e8a38dbad92b8df07a9d6bac98a4534b71ae3cfc

data/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.17.0 — 2026-04-10
+
+### Changed
+
+- **`Readable#receive` no longer prefetches a batch.** Each `#receive`
+  call dequeues exactly one message from the engine recv queue. The
+  per-socket prefetch buffer (`@recv_buffer` + `@recv_mutex`) and
+  `dequeue_recv_batch` are gone, along with `Readable::RECV_BATCH_SIZE`.
+  Simpler code; ~5–10% inproc microbench regression accepted (tcp/ipc
+  unchanged — wire I/O dominates dispatch overhead).
+
+### Added
+
+- **Socket-level `Async::Barrier` and cascading teardown.**
+  `SocketLifecycle` now owns an `Async::Barrier` that tracks every
+  socket-scoped task — connection supervisors, pumps, accept loops,
+  reconnect loops, heartbeat, maintenance. `Engine#close` and the new
+  `Engine#stop` stop this single barrier and every descendant unwinds
+  in one call, so the ordering of `:disconnected` / `all_peers_gone` /
+  `maybe_reconnect` side effects no longer depends on which pump
+  happens to observe the disconnect first.
+
+- **`Socket#stop`** — immediate hard stop that skips the linger drain
+  and goes straight to the barrier cascade. Complements `#close` for
+  crash-path cleanup.
+
+- **`parent:` kwarg on `Socket#bind` / `Socket#connect`.** Accepts any
+  object responding to `#async` (`Async::Task`, `Async::Barrier`,
+  `Async::Semaphore`). The socket-level barrier is constructed with
+  the caller's parent, so every task spawned under the socket lives
+  under the caller's Async tree — standard Async idiom for letting
+  callers coordinate teardown of internal tasks with their own work.
+
+### Fixed
+
+- **macOS: PUSH fails to reconnect after peer rebinds** (and analogous
+  races on any platform where the send pump observes the disconnect
+  before the recv pump does). The send pump's `rescue EPIPE` called
+  `connection_lost(conn)` → `tear_down!` → `routing.connection_removed`
+  → `.stop` on `@conn_send_tasks[conn]` — which **was** the currently-
+  running send pump. `Task#stop` on self raises `Async::Cancel`
+  synchronously and unwinds through `tear_down!` mid-sequence, before
+  `:disconnected` emission and `maybe_reconnect`, leaving the socket
+  stuck with no reconnect scheduled. Root-caused from a `ruby -d`
+  trace showing `EPIPE` at `buffered.rb:112` immediately followed by
+  `Async::Cancel` at `task.rb:358` "Cancelling current task!".
+
+  Fix: introduce a per-connection `Async::Barrier` and a supervisor
+  task placed on the *socket* barrier (not the per-conn one) that
+  blocks on `@barrier.wait { |t| t.wait; break }` and runs `lost!`
+  in its `ensure`. Pumps now just exit on `EPIPE` / `EOFError` /
+  ZMTP errors — they never initiate teardown from inside themselves,
+  so `Task#stop`-on-self is structurally impossible. All three
+  shutdown paths (peer disconnect, `#close`, `#stop`) converge on the
+  same ordered `tear_down!` sequence.
+
+- **`DESIGN.md` synced with post-barrier-refactor reality.** Rewrote
+  the Task tree and Engine lifecycle sections to reflect the socket-
+  level `Async::Barrier`, per-connection nested barrier, supervisor
+  pattern, `Socket#stop`, and user-provided `parent:` kwarg. Added a
+  new Cancellation safety subsection documenting that wire writes in
+  protocol-zmtp are wrapped in `Async::Task#defer_cancel` so cascade
+  teardown during a mid-frame write can't desync the peer's framer.
+
+- **IPC connect to an existing `SOCK_DGRAM` socket file** now surfaces
+  as a connect-time failure with backoff retry instead of crashing
+  the pump. `Errno::EPROTOTYPE` added to `CONNECTION_FAILED` (not
+  `CONNECTION_LOST` — it's a connect() error, not an established-
+  connection drop). Consistent with how `ECONNREFUSED` is treated for
+  TCP: the endpoint is misconfigured or not ready, the socket keeps
+  trying, and the user sees `:connect_retried` monitor events.
+
 ## 0.16.2 — 2026-04-09
 
 ### Fixed

data/lib/omq/engine/connection_lifecycle.rb

@@ -40,6 +40,13 @@ module OMQ
       # @return [Symbol] current state
       attr_reader :state
 
+      # @return [Async::Barrier] holds all per-connection pump tasks
+      #   (send pump, recv pump, reaper, heartbeat). When the connection
+      #   is torn down, {#tear_down!} calls `@barrier.stop` to take down
+      #   every sibling task atomically — so the first pump to see a
+      #   disconnect takes down all the others.
+      attr_reader :barrier
+
 
       # @param engine [Engine]
       # @param endpoint [String, nil]
@@ -51,6 +58,11 @@ module OMQ
         @done     = done
         @state    = :new
         @conn     = nil
+        # Nest the per-connection barrier under the socket-level barrier
+        # so every pump spawned via +@barrier.async+ is also tracked by
+        # the socket barrier — {Engine#stop}/{Engine#close} cascade
+        # through in one call.
+        @barrier  = Async::Barrier.new(parent: engine.barrier)
       end
 
 
@@ -71,7 +83,7 @@ module OMQ
           max_message_size: @engine.options.max_message_size,
         )
         conn.handshake!
-        Heartbeat.start(Async::Task.current, conn, @engine.options, @engine.tasks)
+        Heartbeat.start(@barrier, conn, @engine.options, @engine.tasks)
         ready!(conn)
         @conn
       rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
@@ -120,6 +132,39 @@ module OMQ
         @engine.routing.connection_added(@conn)
         @engine.peer_connected.resolve(@conn)
         transition!(:ready)
+        # No supervisor if nothing to supervise: inproc DirectPipes
+        # wire the recv/send paths synchronously (no task-based pumps),
+        # and isolated unit tests use a FakeEngine without pumps at all.
+        # Waiting on an empty barrier returns immediately and would
+        # tear the connection down right after registering.
+        start_supervisor unless @barrier.empty?
+      end
+
+
+      # Spawns a supervisor task on the *socket-level* barrier (not the
+      # per-connection barrier) that blocks on the first pump to finish
+      # and then triggers teardown.
+      #
+      # Keeping the supervisor out of the per-connection barrier avoids
+      # the self-stop problem: stopping the current task raises
+      # Async::Cancel synchronously and unwinds before side effects can
+      # run. Placing it on the socket barrier means {Engine#stop} /
+      # {Engine#close} cascade-cancels the supervisor, whose +ensure+
+      # runs the ordered disconnect side effects once.
+      #
+      def start_supervisor
+        @supervisor = @engine.barrier.async(transient: true, annotation: "conn supervisor") do
+          @barrier.wait do |task|
+            task.wait
+            break
+          end
+        rescue Async::Stop, Async::Cancel
+          # socket or supervisor cancelled externally (socket closing)
+        rescue Protocol::ZMTP::Error, *CONNECTION_LOST
+          # expected pump exit on disconnect
+        ensure
+          lost!
+        end
       end
 
 
@@ -133,6 +178,10 @@ module OMQ
         @done&.resolve(true)
         @engine.resolve_all_peers_gone_if_empty
         @engine.maybe_reconnect(@endpoint) if reconnect
+        # Cancel every sibling pump of this connection. The caller is
+        # the supervisor task, which is NOT in the barrier — so there
+        # is no self-stop risk.
+        @barrier.stop
       end
 
 

data/lib/omq/engine/heartbeat.rb

@@ -8,12 +8,12 @@ module OMQ
     # if no traffic is seen within +timeout+ seconds.
     #
     module Heartbeat
-      # @param parent_task [Async::Task]
+      # @param parent [Async::Task, Async::Barrier] parent to spawn under
       # @param conn [Connection]
       # @param options [Options]
       # @param tasks [Array]
       #
-      def self.start(parent_task, conn, options, tasks)
+      def self.start(parent, conn, options, tasks)
         interval = options.heartbeat_interval
         return unless interval
 
@@ -21,7 +21,7 @@ module OMQ
         timeout = options.heartbeat_timeout || interval
         conn.touch_heartbeat
 
-        tasks << parent_task.async(transient: true, annotation: "heartbeat") do
+        tasks << parent.async(transient: true, annotation: "heartbeat") do
           loop do
             sleep interval
             conn.send_command(Protocol::ZMTP::Codec::Command.ping(ttl: ttl, context: "".b))
@@ -30,7 +30,7 @@ module OMQ
               break
             end
           end
-        rescue Async::Stop
+        rescue Async::Stop, Async::Cancel
         rescue *CONNECTION_LOST
           # connection closed
         end

data/lib/omq/engine/recv_pump.rb

@@ -19,15 +19,15 @@ module OMQ
 
       # Public entry point — callers use the class method.
       #
-      # @param parent_task [Async::Task]
+      # @param parent [Async::Task, Async::Barrier] parent to spawn under
       # @param conn [Connection, Transport::Inproc::DirectPipe]
       # @param recv_queue [SignalingQueue]
       # @param engine [Engine]
       # @param transform [Proc, nil]
       # @return [Async::Task, nil]
       #
-      def self.start(parent_task, conn, recv_queue, engine, transform)
-        new(conn, recv_queue, engine).start(parent_task, transform)
+      def self.start(parent, conn, recv_queue, engine, transform)
+        new(conn, recv_queue, engine).start(parent, transform)
       end
 
 
@@ -67,10 +67,10 @@ module OMQ
       private
 
 
-      def start_with_transform(parent_task, transform)
+      def start_with_transform(parent, transform)
         conn, recv_queue, engine, count_bytes = @conn, @recv_queue, @engine, @count_bytes
 
-        parent_task.async(transient: true, annotation: "recv pump") do |task|
+        parent.async(transient: true, annotation: "recv pump") do |task|
           loop do
             count = 0
             bytes = 0
@@ -84,19 +84,19 @@ module OMQ
             end
             task.yield
           end
-        rescue Async::Stop
+        rescue Async::Stop, Async::Cancel
         rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-          @engine.connection_lost(conn)
+          # expected disconnect — supervisor will trigger teardown
         rescue => error
           @engine.signal_fatal_error(error)
         end
       end
 
 
-      def start_direct(parent_task)
+      def start_direct(parent)
         conn, recv_queue, engine, count_bytes = @conn, @recv_queue, @engine, @count_bytes
 
-        parent_task.async(transient: true, annotation: "recv pump") do |task|
+        parent.async(transient: true, annotation: "recv pump") do |task|
           loop do
             count = 0
             bytes = 0
@@ -109,9 +109,9 @@ module OMQ
             end
             task.yield
           end
-        rescue Async::Stop
+        rescue Async::Stop, Async::Cancel
         rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-          @engine.connection_lost(conn)
+          # expected disconnect — supervisor will trigger teardown
         rescue => error
           @engine.signal_fatal_error(error)
         end

data/lib/omq/engine/socket_lifecycle.rb

@@ -34,12 +34,21 @@ module OMQ
       # @return [Async::Promise] resolves once all peers are gone (after having had peers)
       attr_reader :all_peers_gone
 
-      # @return [Async::Task, nil] root of the socket's task tree
+      # @return [Async::Task, Async::Barrier, Async::Semaphore, nil] root of
+      #   the socket's task tree (may be user-provided via +parent:+ on
+      #   {Socket#bind} / {Socket#connect}; falls back to the current
+      #   Async task or the shared Reactor root)
       attr_reader :parent_task
 
       # @return [Boolean] true if parent_task is the shared Reactor thread
       attr_reader :on_io_thread
 
+      # @return [Async::Barrier] holds every socket-scoped task (connection
+      #   supervisors, reconnect loops, heartbeat, monitor, accept loops).
+      #   {Engine#stop} and {Engine#close} call +barrier.stop+ to cascade
+      #   teardown through every per-connection barrier in one shot.
+      attr_reader :barrier
+
       # @return [Boolean] whether auto-reconnect is enabled
       attr_accessor :reconnect_enabled
 
@@ -51,6 +60,7 @@ module OMQ
         @reconnect_enabled = true
         @parent_task       = nil
         @on_io_thread      = false
+        @barrier           = nil
       end
 
 
@@ -60,22 +70,36 @@ module OMQ
       def alive?     = @state == :new || @state == :open
 
 
-      # Captures the current Async task (or the shared Reactor root) as
-      # this socket's task tree root. Transitions `:new → :open`.
+      # Captures the socket's task tree root. Transitions `:new → :open`.
+      #
+      # When +parent+ is provided (any Async task/barrier/semaphore — any
+      # object that responds to +#async+), it is used as the root; this is
+      # the common Async idiom for letting callers place internal tasks
+      # under a caller-managed parent so teardown can be coordinated with
+      # other work. Otherwise falls back to the current Async task or the
+      # shared Reactor root for non-Async callers.
+      #
+      # The socket-level {#barrier} is constructed with the captured root
+      # as its parent so every task spawned via +barrier.async+ lives
+      # under the caller's tree.
       #
+      # @param parent [#async, nil] optional Async parent
       # @param linger [Numeric, nil] used to register the Reactor linger slot
       #   when falling back to the IO thread
       # @return [Boolean] true on first-time capture, false if already captured
       #
-      def capture_parent_task(linger:)
+      def capture_parent_task(parent: nil, linger:)
         return false if @parent_task
-        if Async::Task.current?
+        if parent
+          @parent_task  = parent
+        elsif Async::Task.current?
           @parent_task = Async::Task.current
         else
           @parent_task  = Reactor.root_task
           @on_io_thread = true
           Reactor.track_linger(linger)
         end
+        @barrier = Async::Barrier.new(parent: @parent_task)
         transition!(:open)
         true
       end

data/lib/omq/engine.rb

@@ -90,6 +90,7 @@ module OMQ
     def peer_connected    = @lifecycle.peer_connected
     def all_peers_gone    = @lifecycle.all_peers_gone
     def parent_task       = @lifecycle.parent_task
+    def barrier           = @lifecycle.barrier
     def closed?           = @lifecycle.closed?
     def reconnect_enabled=(value)
       @lifecycle.reconnect_enabled = value
@@ -109,9 +110,9 @@ module OMQ
     def spawn_inproc_retry(endpoint)
       ri  = @options.reconnect_interval
       ivl = ri.is_a?(Range) ? ri.begin : ri
-      @tasks << @lifecycle.parent_task.async(transient: true, annotation: "inproc reconnect #{endpoint}") do
+      @tasks << @lifecycle.barrier.async(transient: true, annotation: "inproc reconnect #{endpoint}") do
         yield ivl
-      rescue Async::Stop
+      rescue Async::Stop, Async::Cancel
       end
     end
 
@@ -122,8 +123,9 @@ module OMQ
     # @return [void]
     # @raise [ArgumentError] on unsupported transport
     #
-    def bind(endpoint)
+    def bind(endpoint, parent: nil)
       OMQ.freeze_for_ractors!
+      capture_parent_task(parent: parent)
       transport = transport_for(endpoint)
       listener  = transport.bind(endpoint, self)
       start_accept_loops(listener)
@@ -142,8 +144,9 @@ module OMQ
     # @param endpoint [String]
     # @return [void]
     #
-    def connect(endpoint)
+    def connect(endpoint, parent: nil)
       OMQ.freeze_for_ractors!
+      capture_parent_task(parent: parent)
       validate_endpoint!(endpoint)
       @dialed.add(endpoint)
       if endpoint.start_with?("inproc://")
@@ -232,30 +235,6 @@ module OMQ
     end
 
 
-    # Dequeues up to +max+ messages or +max_bytes+ total. Blocks
-    # on the first, then drains non-blocking.
-    #
-    # @param max [Integer] message count limit
-    # @param max_bytes [Integer] byte size limit
-    # @return [Array<Array<String>>]
-    #
-    def dequeue_recv_batch(max, max_bytes: 1 << 20)
-      raise @fatal_error if @fatal_error
-      queue = routing.recv_queue
-      msg   = queue.dequeue
-      raise @fatal_error if msg.nil? && @fatal_error
-      batch = [msg]
-      bytes = msg.sum(&:bytesize)
-      while batch.size < max && bytes < max_bytes
-        msg = queue.dequeue(timeout: 0)
-        break unless msg
-        batch << msg
-        bytes += msg.sum(&:bytesize)
-      end
-      batch
-    end
-
-
     # Pushes a nil sentinel into the recv queue, unblocking a
     # pending {#dequeue_recv} with a nil return value.
     #
@@ -284,7 +263,11 @@ module OMQ
     # @return [Async::Task, nil]
     #
     def start_recv_pump(conn, recv_queue, &transform)
-      task = RecvPump.start(Async::Task.current, conn, recv_queue, self, transform)
+      # Spawn on the connection's lifecycle barrier so the recv pump is
+      # torn down together with the rest of its sibling per-connection
+      # pumps when the connection is lost.
+      parent = @connections[conn]&.barrier || @lifecycle.barrier
+      task   = RecvPump.start(parent, conn, recv_queue, self, transform)
       @tasks << task if task
       task
     end
@@ -318,7 +301,10 @@ module OMQ
     end
 
 
-    # Closes all connections and listeners.
+    # Closes all connections and listeners gracefully. Drains pending
+    # sends up to +linger+ seconds, then cascades teardown through the
+    # socket-level {SocketLifecycle#barrier} — every per-connection
+    # barrier is stopped as a side effect, cancelling every pump.
     #
     # @return [void]
     #
@@ -330,8 +316,27 @@ module OMQ
       @lifecycle.finish_closing!
       Reactor.untrack_linger(@options.linger) if @lifecycle.on_io_thread
       stop_listeners
-      close_connections
-      stop_tasks
+      tear_down_barrier
+      routing.stop rescue nil
+      emit_monitor_event(:closed)
+      close_monitor_queue
+    end
+
+
+    # Immediate hard stop: skips the linger drain and cascades teardown
+    # through the socket-level barrier. Intended for crash-path cleanup
+    # where {#close}'s drain is either unsafe or undesired.
+    #
+    # @return [void]
+    #
+    def stop
+      return unless @lifecycle.alive?
+      @lifecycle.start_closing! if @lifecycle.open?
+      @lifecycle.finish_closing!
+      Reactor.untrack_linger(@options.linger) if @lifecycle.on_io_thread
+      stop_listeners
+      tear_down_barrier
+      routing.stop rescue nil
       emit_monitor_event(:closed)
       close_monitor_queue
     end
@@ -350,7 +355,7 @@ module OMQ
     def spawn_pump_task(annotation:, &block)
       Async::Task.current.async(transient: true, annotation: annotation) do
         yield
-      rescue Async::Stop, Protocol::ZMTP::Error, *CONNECTION_LOST
+      rescue Async::Stop, Async::Cancel, Protocol::ZMTP::Error, *CONNECTION_LOST
         # normal shutdown / expected disconnect
       rescue => error
         signal_fatal_error(error)
@@ -358,6 +363,31 @@ module OMQ
     end
 
 
+    # Spawns a per-connection pump task on the connection's own
+    # lifecycle barrier. When any pump on the barrier exits (e.g. the
+    # send pump sees EPIPE and calls {#connection_lost}), {ConnectionLifecycle#tear_down!}
+    # calls `barrier.stop` which cancels every sibling pump for that
+    # connection — so a dead peer can no longer leave orphan send
+    # pumps blocked on `dequeue` waiting for messages that will never
+    # be written.
+    #
+    # @param conn [Connection, Transport::Inproc::DirectPipe]
+    # @param annotation [String]
+    #
+    def spawn_conn_pump_task(conn, annotation:, &block)
+      lifecycle = @connections[conn]
+      return spawn_pump_task(annotation: annotation, &block) unless lifecycle
+
+      lifecycle.barrier.async(transient: true, annotation: annotation) do
+        yield
+      rescue Async::Stop, Async::Cancel, Protocol::ZMTP::Error, *CONNECTION_LOST
+        # normal shutdown / expected disconnect / sibling tore us down
+      rescue => error
+        signal_fatal_error(error)
+      end
+    end
+
+
     # Wraps an unexpected pump error as {OMQ::SocketDeadError} and
     # unblocks any callers waiting on the recv queue.
     #
@@ -378,14 +408,22 @@ module OMQ
     end
 
 
-    # Saves the current Async task so connection subtrees can be
-    # spawned under the caller's task tree. Called by Socket before
-    # the first bind/connect — outside Reactor.run so non-Async
-    # callers get the IO thread's root task, not an ephemeral work task.
+    # Captures the socket's task tree root and starts the socket-level
+    # maintenance task. If +parent+ is given, it is used as the parent
+    # for every task spawned under this socket (connection supervisors,
+    # reconnect loops, maintenance, monitor). Otherwise the current
+    # Async task (or the shared Reactor root, for non-Async callers)
+    # is captured automatically.
+    #
+    # Idempotent: first call wins. Subsequent calls (including from
+    # later bind/connect invocations) with a different +parent+ are
+    # silently ignored.
     #
-    def capture_parent_task
-      return unless @lifecycle.capture_parent_task(linger: @options.linger)
-      Maintenance.start(@lifecycle.parent_task, @options.mechanism, @tasks)
+    # @param parent [#async, nil] optional Async parent
+    #
+    def capture_parent_task(parent: nil)
+      return unless @lifecycle.capture_parent_task(parent: parent, linger: @options.linger)
+      Maintenance.start(@lifecycle.barrier, @options.mechanism, @tasks)
     end
 
 
@@ -432,11 +470,13 @@ module OMQ
     private
 
     def spawn_connection(io, as_server:, endpoint: nil)
-      task = @lifecycle.parent_task&.async(transient: true, annotation: "conn #{endpoint}") do
+      task = @lifecycle.barrier&.async(transient: true, annotation: "conn #{endpoint}") do
         done      = Async::Promise.new
         lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint, done: done)
         lifecycle.handshake!(io, as_server: as_server)
         done.wait
+      rescue Async::Stop, Async::Cancel
+        # socket barrier stopped — cascade teardown
       rescue Async::Queue::ClosedError
         # connection dropped during drain — message re-staged
       rescue Protocol::ZMTP::Error, *CONNECTION_LOST
@@ -471,7 +511,7 @@ module OMQ
 
     def start_accept_loops(listener)
       return unless listener.respond_to?(:start_accept_loops)
-      listener.start_accept_loops(@lifecycle.parent_task) do |io|
+      listener.start_accept_loops(@lifecycle.barrier) do |io|
         handle_accepted(io, endpoint: listener.endpoint)
       end
     end
@@ -483,19 +523,19 @@ module OMQ
     end
 
 
-    def close_connections
-      @connections.values.each(&:close!)
-    end
-
-
     def close_connections_at(endpoint)
       @connections.values.select { |lc| lc.endpoint == endpoint }.each(&:close!)
     end
 
 
-    def stop_tasks
-      routing.stop rescue nil
-      @tasks.each { |t| t.stop rescue nil }
+    # Cascades teardown through the socket-level barrier. Stopping the
+    # barrier cancels every tracked task: connection supervisors (whose
+    # `ensure lost!` runs the ordered disconnect side effects), accept
+    # loops, reconnect loops, heartbeat, maintenance. After the cascade,
+    # clears the legacy +@tasks+ list.
+    #
+    def tear_down_barrier
+      @lifecycle.barrier&.stop
       @tasks.clear
     end
 

data/lib/omq/queue_interface.rb

@@ -16,13 +16,7 @@ module OMQ
     # @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
+      Reactor.run { with_timeout(timeout) { @engine.dequeue_recv } }
     end
 
     alias_method :pop, :dequeue

data/lib/omq/readable.rb

@@ -8,20 +8,13 @@ module OMQ
   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.
+    # Receives the next message directly from the engine recv queue.
     #
     # @return [Array<String>] message parts
     # @raise [IO::TimeoutError] if read_timeout exceeded
     #
     def receive
-      @recv_mutex.synchronize { @recv_buffer.shift } || fill_recv_buffer
+      Reactor.run { with_timeout(@options.read_timeout) { @engine.dequeue_recv } }
     end
 
 
@@ -33,14 +26,5 @@ module OMQ
     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/routing/conn_send_pump.rb

@@ -17,7 +17,7 @@ module OMQ
       # @return [Async::Task]
       #
       def self.start(engine, conn, q, tasks)
-        task = engine.spawn_pump_task(annotation: "send pump") do
+        task = engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             batch = [q.dequeue]
             Routing.drain_send_queue(q, batch)
@@ -28,9 +28,6 @@ module OMQ
             end
             conn.flush
             batch.each { |parts| engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
-          rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-            engine.connection_lost(conn)
-            break
           end
         end
         tasks << task

data/lib/omq/routing/fan_out.rb

@@ -123,7 +123,7 @@ module OMQ
 
 
       def start_subscription_listener(conn)
-        @tasks << @engine.spawn_pump_task(annotation: "subscription listener") do
+        @tasks << @engine.spawn_conn_pump_task(conn, annotation: "subscription listener") do
           loop do
             frame = conn.read_frame
             next unless frame.command?
@@ -135,8 +135,6 @@ module OMQ
               on_cancel(conn, cmd.data)
             end
           end
-        rescue *CONNECTION_LOST
-          @engine.connection_lost(conn)
         end
       end
 
@@ -159,7 +157,7 @@ module OMQ
 
 
       def start_conn_send_pump_normal(conn, q, use_wire)
-        @engine.spawn_pump_task(annotation: "send pump") do
+        @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             batch = [q.dequeue]
             Routing.drain_send_queue(q, batch)
@@ -167,9 +165,6 @@ module OMQ
               conn.flush
               batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
             end
-          rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-            @engine.connection_lost(conn)
-            break
           end
         end
       end
@@ -187,21 +182,16 @@ module OMQ
 
 
       def start_conn_send_pump_conflate(conn, q)
-        @engine.spawn_pump_task(annotation: "send pump") do
+        @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) }
             next unless latest
-            begin
-              conn.write_message(latest)
-              conn.flush
-              @engine.emit_verbose_monitor_event(:message_sent, parts: latest)
-            rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-              @engine.connection_lost(conn)
-              break
-            end
+            conn.write_message(latest)
+            conn.flush
+            @engine.emit_verbose_monitor_event(:message_sent, parts: latest)
           end
         end
       end

data/lib/omq/routing/pair.rb

@@ -86,7 +86,7 @@ module OMQ
       private
 
       def start_send_pump(conn)
-        @send_pump = @engine.spawn_pump_task(annotation: "send pump") do
+        @send_pump = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             batch = [@send_queue.dequeue]
             Routing.drain_send_queue(@send_queue, batch)
@@ -97,9 +97,6 @@ module OMQ
             end
             conn.flush
             batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
-          rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-            @engine.connection_lost(conn)
-            break
           end
         end
         @tasks << @send_pump

data/lib/omq/routing/push.rb

@@ -62,10 +62,8 @@ module OMQ
       #
       def start_reaper(conn)
         return if conn.is_a?(Transport::Inproc::DirectPipe)
-        @tasks << @engine.spawn_pump_task(annotation: "reaper") do
-          conn.receive_message # blocks until peer disconnects
-        rescue *CONNECTION_LOST
-          @engine.connection_lost(conn)
+        @tasks << @engine.spawn_conn_pump_task(conn, annotation: "reaper") do
+          conn.receive_message # blocks until peer disconnects; then exits
         end
       end
     end

data/lib/omq/routing/round_robin.rb

@@ -60,7 +60,7 @@ module OMQ
       #
       def remove_round_robin_send_connection(conn)
         update_direct_pipe
-        @conn_send_tasks.delete(conn)&.stop
+        @conn_send_tasks.delete(conn)
       end
 
 
@@ -122,16 +122,13 @@ module OMQ
       # @param conn [Connection]
       #
       def start_conn_send_pump(conn)
-        task = @engine.spawn_pump_task(annotation: "send pump") do
+        task = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             batch = [@send_queue.dequeue]
             drain_send_queue_capped(batch)
             write_batch(conn, batch)
             batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
             Async::Task.current.yield
-          rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-            @engine.connection_lost(conn)
-            break
           end
         end
         @conn_send_tasks[conn] = task

data/lib/omq/routing/xsub.rb

@@ -81,23 +81,18 @@ module OMQ
       private
 
       def start_conn_send_pump(conn, q)
-        task = @engine.spawn_pump_task(annotation: "send pump") do
+        task = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             parts = q.dequeue
             frame = parts.first&.b
             next if frame.nil? || frame.empty?
             flag   = frame.getbyte(0)
             prefix = frame.byteslice(1..) || "".b
-            begin
-              case flag
-              when 0x01
-                conn.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
-              when 0x00
-                conn.send_command(Protocol::ZMTP::Codec::Command.cancel(prefix))
-              end
-            rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-              @engine.connection_lost(conn)
-              break
+            case flag
+            when 0x01
+              conn.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
+            when 0x00
+              conn.send_command(Protocol::ZMTP::Codec::Command.cancel(prefix))
             end
           end
         end

data/lib/omq/routing.rb

@@ -70,8 +70,7 @@ module OMQ
     #
     def self.drain_send_queue(queue, batch)
       loop do
-        msg = queue.dequeue(timeout: 0)
-        break unless msg
+        msg = queue.dequeue(timeout: 0) or break
         batch << msg
       end
     end

data/lib/omq/socket.rb

@@ -75,10 +75,18 @@ module OMQ
     # Binds to an endpoint.
     #
     # @param endpoint [String]
+    # @param parent [#async, nil] Async parent for the socket's task tree.
+    #   Accepts any object that responds to +#async+ — +Async::Task+,
+    #   +Async::Barrier+, +Async::Semaphore+. When given, every task
+    #   spawned under this socket (connection supervisors, reconnect
+    #   loops, heartbeat, monitor) is placed under +parent+, so callers
+    #   can coordinate teardown with their own Async tree. Only the
+    #   *first* bind/connect call captures the parent — subsequent
+    #   calls ignore the kwarg.
     # @return [void]
     #
-    def bind(endpoint)
-      ensure_parent_task
+    def bind(endpoint, parent: nil)
+      ensure_parent_task(parent: parent)
       Reactor.run do
         @engine.bind(endpoint)
         @last_tcp_port = @engine.last_tcp_port
@@ -89,10 +97,11 @@ module OMQ
     # Connects to an endpoint.
     #
     # @param endpoint [String]
+    # @param parent [#async, nil] see {#bind}.
     # @return [void]
     #
-    def connect(endpoint)
-      ensure_parent_task
+    def connect(endpoint, parent: nil)
+      ensure_parent_task(parent: parent)
       Reactor.run { @engine.connect(endpoint) }
     end
 
@@ -201,7 +210,10 @@ module OMQ
     end
 
 
-    # Closes the socket and releases all resources.
+    # Closes the socket and releases all resources. Drains pending sends
+    # up to +linger+ seconds, then cascades teardown through the
+    # socket-level Async::Barrier — every connection's per-connection
+    # barrier is stopped, cancelling every pump.
     #
     # @return [nil]
     #
@@ -211,6 +223,18 @@ module OMQ
     end
 
 
+    # Immediate hard stop. Skips the linger drain and cascades teardown
+    # through the socket-level Async::Barrier. Intended for crash-path
+    # cleanup or when the caller already knows no pending sends matter.
+    #
+    # @return [nil]
+    #
+    def stop
+      Reactor.run { @engine.stop }
+      nil
+    end
+
+
     # Set socket to use unbounded pipes (HWM=0).
     #
     # @return [nil]
@@ -254,8 +278,8 @@ module OMQ
     # 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
-      @engine.capture_parent_task
+    def ensure_parent_task(parent: nil)
+      @engine.capture_parent_task(parent: parent)
     end
 
 
@@ -292,9 +316,7 @@ module OMQ
       @options.recv_timeout   = recv_timeout if recv_timeout
       @options.conflate       = conflate
       @options.on_mute        = on_mute      if on_mute
-      @recv_buffer = []
-      @recv_mutex  = Mutex.new
-      @engine      = case backend
+      @engine                 = case backend
                      when nil, :ruby
                        Engine.new(socket_type, @options)
                      when :ffi

data/lib/omq/version.rb

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

data/lib/omq.rb

@@ -45,6 +45,7 @@ module OMQ
     Errno::ETIMEDOUT,
     Errno::EHOSTUNREACH,
     Errno::ENETUNREACH,
+    Errno::EPROTOTYPE, # IPC: existing socket file is SOCK_DGRAM, not SOCK_STREAM
     Socket::ResolutionError,
   ]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq
 version: !ruby/object:Gem::Version
-  version: 0.16.2
+  version: 0.17.0
 platform: ruby
 authors:
 - Patrik Wenger