omq 0.17.8 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 684f878ff9a1731c4820ec6a6ed52393b727fa046b3d8ff74dfbb4fd50e20e48
-  data.tar.gz: f5ffad6b1c827949a3c17088536af9a7b7e3f329231767b299cb5bd5a0f73628
+  metadata.gz: f4c49622de9b6972433ec90b148e0d20e68f69d5bb4939debd5abd5095d0396b
+  data.tar.gz: a70873e070a90ac7b804585231180926ef030e8ffeb9cf65fc44e889dc3619e2
 SHA512:
-  metadata.gz: ec98f8caf95091396b6a7f4e3ed01480700c4ba7fb14d3c85dc20572e6fd2cf3160f1f081f5390d79834d8b9db8271a6f8104c34400562c874fbf61c2763cfab
-  data.tar.gz: 15a546c0717ab0440aeb010bd9fca87f01f63bffe4eba91fa852b2a48bb99864994c366778114e116463c715dbab11e218256602c662d394dc6a17b5657e683f
+  metadata.gz: a4c994245259282909189bcd44d69ef9153b52ef1dd2675b8cf8635b8970ed9c630048b55837cdc0fa20ecb04c00edd9b3bff17e5d9ad93d70107eb8701b08a3
+  data.tar.gz: d3f88cd73a8ea21fb572518a8f9b8128244f2bb10cfcf0e43b8ac73a797158ef1c2a59fe8fe75be407eac6277f8ebd05bd7ab554f6fa3a4d1e215ccaf3c034ab

data/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.18.0 — 2026-04-12
+
+### Changed
+
+- **Renamed `Socket#_attach` → `#attach_endpoints` and `#_init_engine` →
+  `#init_engine`.** Both are now public so plugin gems can call them
+  without reaching into private API. Internal callers updated.
+
+- **Routing registry exposed via `Routing.registry`.** `omq.rb`'s
+  `freeze_for_ractors!` no longer reaches in via `instance_variable_get`.
+
+### Fixed
+
+- **Test helper deadlock.** `Kernel#Async` override in `test_helper.rb`
+  was wrapping every `Async do` block in a `with_timeout`, including
+  the reactor thread's own root task. With a 1s timeout the reactor
+  task died mid-suite and subsequent `Reactor.run` calls hung forever.
+  The override now only wraps blocks running on the main thread.
+
+- **`wait_connected` test helper uses `Async::Barrier`** for parallel
+  fork-join across all sockets instead of a sequential `Async{}` array.
+
+- **`examples/zguide/03_pipeline.rb` flake.** The example sent 20 tasks
+  to 3 PUSH workers and asserted that all three got some — but PUSH
+  work-stealing on inproc lets the first pump fiber to wake grab a
+  whole batch (256 messages) before yielding, so worker-0 always took
+  everything. Fixed by waiting on each worker's `peer_connected`
+  promise via `Async::Barrier` and bumping the burst above one
+  pump's batch cap.
+
+### Documentation
+
+- **Documented work-stealing as a deviation from libzmq.** README
+  routing tables now say "Work-stealing" instead of "Round-robin"
+  for PUSH/REQ/DEALER/SCATTER/CLIENT, with a callout explaining the
+  burst-vs-steady distribution behavior. DESIGN.md's "Per-socket HWM"
+  section gained a user-visible-consequence note covering the same.
+
+- **Lifecycle boundary docs.** `ConnectionLifecycle` and
+  `SocketLifecycle` now carry explicit class-level comments
+  delimiting their scopes (per-connection arc vs. per-socket state)
+  and referencing each other.
+
+- **API doc fill-in.** Added missing YARD comments on
+  `RecvPump::FAIRNESS_MESSAGES` / `FAIRNESS_BYTES`,
+  `RecvPump#start_with_transform` / `#start_direct`, several
+  `FanOut` send-pump methods, and the TCP/IPC `apply_buffer_sizes`
+  helpers.
+
+- **`Engine#drain_send_queues` flagged with TODO.** The 1 ms busy-poll
+  is non-trivial to fix cleanly (needs a "queue fully drained" signal
+  threaded through every routing strategy), so it's marked rather
+  than reworked here.
+
 ## 0.17.8 — 2026-04-10
 
 ### Fixed

data/README.md

@@ -153,22 +153,24 @@ All sockets are thread-safe. Default HWM is 1000 messages per socket. `max_messa
 
 | Pattern | Send | Receive | When HWM full |
 |---------|------|---------|---------------|
-| **REQ** / **REP** | Round-robin / route-back | Fair-queue | Block |
+| **REQ** / **REP** | Work-stealing / route-back | Fair-queue | Block |
 | **PUB** / **SUB** | Fan-out to subscribers | Subscription filter | Drop |
-| **PUSH** / **PULL** | Round-robin to workers | Fair-queue | Block |
-| **DEALER** / **ROUTER** | Round-robin / identity-route | Fair-queue | Block |
+| **PUSH** / **PULL** | Work-stealing to workers | Fair-queue | Block |
+| **DEALER** / **ROUTER** | Work-stealing / identity-route | Fair-queue | Block |
 | **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.
+
 #### Draft (single-frame only)
 
 These require the `omq-draft` gem.
 
 | Pattern | Send | Receive | When HWM full |
 |---------|------|---------|---------------|
-| **CLIENT** / **SERVER** | Round-robin / routing-ID | Fair-queue | Block |
+| **CLIENT** / **SERVER** | Work-stealing / routing-ID | Fair-queue | Block |
 | **RADIO** / **DISH** | Group fan-out | Group filter | Drop |
-| **SCATTER** / **GATHER** | Round-robin | Fair-queue | Block |
+| **SCATTER** / **GATHER** | Work-stealing | Fair-queue | Block |
 | **PEER** | Routing-ID | Fair-queue | Block |
 | **CHANNEL** | Exclusive 1-to-1 | Exclusive 1-to-1 | Block |
 

data/lib/omq/engine/connection_lifecycle.rb

@@ -2,7 +2,15 @@
 
 module OMQ
   class Engine
-    # Owns the full arc of one connection: handshake → ready → closed.
+    # Owns the full arc of *one* connection: handshake → ready → closed.
+    #
+    # Scope boundary: ConnectionLifecycle tracks a single peer link
+    # (one ZMTP connection or one inproc DirectPipe). SocketLifecycle
+    # owns the socket-wide state above it — first-peer/last-peer
+    # signaling, reconnect enable flag, the parent task tree, and the
+    # open → closing → closed transitions that gate close-time drain.
+    # A socket has exactly one SocketLifecycle and zero-or-more
+    # ConnectionLifecycles beneath it.
     #
     # Centralizes the ordering of side effects (monitor events, routing
     # registration, promise resolution, reconnect scheduling) so the
@@ -19,10 +27,14 @@ module OMQ
     # lost connection.
     #
     class ConnectionLifecycle
-      class InvalidTransition < RuntimeError; end
+
+      class InvalidTransition < RuntimeError
+      end
+
 
       STATES = %i[new handshaking ready closed].freeze
 
+
       TRANSITIONS = {
         new:         %i[handshaking ready closed].freeze,
         handshaking: %i[ready closed].freeze,
@@ -34,12 +46,15 @@ module OMQ
       # @return [Protocol::ZMTP::Connection, Transport::Inproc::DirectPipe, nil]
       attr_reader :conn
 
+
       # @return [String, nil]
       attr_reader :endpoint
 
+
       # @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
@@ -58,6 +73,7 @@ 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
@@ -74,21 +90,26 @@ module OMQ
       #
       def handshake!(io, as_server:)
         transition!(:handshaking)
-        conn = Protocol::ZMTP::Connection.new(
-          io,
+        conn = Protocol::ZMTP::Connection.new io,
           socket_type:      @engine.socket_type.to_s,
           identity:         @engine.options.identity,
           as_server:        as_server,
           mechanism:        @engine.options.mechanism&.dup,
-          max_message_size: @engine.options.max_message_size,
-        )
-        Async::Task.current.with_timeout(handshake_timeout) { conn.handshake! }
+          max_message_size: @engine.options.max_message_size
+
+        Async::Task.current.with_timeout(handshake_timeout) do
+          conn.handshake!
+        end
+
         Heartbeat.start(@barrier, conn, @engine.options, @engine.tasks)
         ready!(conn)
         @conn
       rescue Protocol::ZMTP::Error, *CONNECTION_LOST, Async::TimeoutError => error
-        @engine.emit_monitor_event(:handshake_failed, endpoint: @endpoint, detail: { error: error })
+        @engine.emit_monitor_event :handshake_failed,
+          endpoint: @endpoint, detail: { error: error }
+
         conn&.close
+
         # Full tear-down with reconnect: without this, spawn_connection's
         # ensure-block close! sees :closed and skips maybe_reconnect,
         # leaving the endpoint dead. Race is exposed when a peer RSTs
@@ -128,6 +149,7 @@ module OMQ
 
       private
 
+
       def ready!(conn)
         conn  = @engine.connection_wrapper.call(conn) if @engine.connection_wrapper
         @conn = conn
@@ -136,6 +158,7 @@ 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.
@@ -182,6 +205,7 @@ 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.

data/lib/omq/engine/reconnect.rb

@@ -45,6 +45,7 @@ module OMQ
         end
       end
 
+
       private
 
 
@@ -60,7 +61,8 @@ module OMQ
             break
           rescue *CONNECTION_LOST, *CONNECTION_FAILED, Protocol::ZMTP::Error
             delay = next_delay(delay, max_delay)
-            @engine.emit_monitor_event(:connect_retried, endpoint: @endpoint, detail: { interval: delay })
+            @engine.emit_monitor_event :connect_retried,
+                                       endpoint: @endpoint, detail: { interval: delay }
           end
         end
       end
@@ -106,6 +108,7 @@ module OMQ
           ri
         end
       end
+
     end
   end
 end

data/lib/omq/engine/recv_pump.rb

@@ -13,7 +13,16 @@ module OMQ
     # of a megamorphic `transform.call` dispatch inside a shared loop.
     #
     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
+
+
+      # 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
 
 
@@ -67,6 +76,14 @@ module OMQ
       private
 
 
+      # Recv loop with per-message transform (e.g. Marshal.load for
+      # cross-Ractor transport). Kept separate from {#start_direct} so
+      # YJIT sees a monomorphic transform.call site.
+      #
+      # @param parent [Async::Task, Async::Barrier]
+      # @param transform [Proc]
+      # @return [Async::Task]
+      #
       def start_with_transform(parent, transform)
         conn, recv_queue, engine, count_bytes = @conn, @recv_queue, @engine, @count_bytes
 
@@ -93,6 +110,11 @@ module OMQ
       end
 
 
+      # Recv loop without transform — the hot path for native OMQ use.
+      #
+      # @param parent [Async::Task, Async::Barrier]
+      # @return [Async::Task]
+      #
       def start_direct(parent)
         conn, recv_queue, engine, count_bytes = @conn, @recv_queue, @engine, @count_bytes
 
@@ -116,6 +138,7 @@ module OMQ
           @engine.signal_fatal_error(error)
         end
       end
+
     end
   end
 end

data/lib/omq/engine/socket_lifecycle.rb

@@ -6,6 +6,13 @@ module OMQ
     # the first-peer / last-peer signaling promises, the reconnect flag,
     # and the captured parent task for the socket's task tree.
     #
+    # Scope boundary: SocketLifecycle is per-socket and outlives every
+    # individual peer link. ConnectionLifecycle is per-connection and
+    # handles one handshake → ready → closed arc beneath it. Roughly:
+    # SocketLifecycle answers "is this socket open and do we have any
+    # peers?", ConnectionLifecycle answers "is this specific peer link
+    # ready / lost?".
+    #
     # Engine delegates state queries here and uses it to coordinate the
     # ordering of close-time side effects. This consolidates six ivars
     # (`@state`, `@peer_connected`, `@all_peers_gone`, `@reconnect_enabled`,
@@ -13,10 +20,13 @@ module OMQ
     # explicit transitions.
     #
     class SocketLifecycle
-      class InvalidTransition < RuntimeError; end
+      class InvalidTransition < RuntimeError
+      end
+
 
       STATES = %i[new open closing closed].freeze
 
+
       TRANSITIONS = {
         new:     %i[open closed].freeze,
         open:    %i[closing closed].freeze,
@@ -28,27 +38,33 @@ module OMQ
       # @return [Symbol]
       attr_reader :state
 
+
       # @return [Async::Promise] resolves with the first connected peer
       attr_reader :peer_connected
 
+
       # @return [Async::Promise] resolves once all peers are gone (after having had peers)
       attr_reader :all_peers_gone
 
+
       # @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
 
@@ -128,6 +144,7 @@ module OMQ
 
       private
 
+
       def transition!(new_state)
         allowed = TRANSITIONS[@state]
         unless allowed&.include?(new_state)
@@ -135,6 +152,7 @@ module OMQ
         end
         @state = new_state
       end
+
     end
   end
 end

data/lib/omq/engine.rb

@@ -20,6 +20,7 @@ module OMQ
     #
     @transports = {}
 
+
     class << self
       # @return [Hash{String => Module}] registered transports
       attr_reader :transports
@@ -83,6 +84,10 @@ module OMQ
     #   @param value [Async::Queue, nil] queue for monitor events
     #
     attr_writer :monitor_queue
+
+
+    # @return [Boolean] when true, every monitor event is also printed
+    #   to stderr for debugging. Set via {Socket#monitor}.
     attr_accessor :verbose_monitor
 
 
@@ -96,6 +101,7 @@ module OMQ
       @lifecycle.reconnect_enabled = value
     end
 
+
     # Optional proc that wraps new connections (e.g. for serialization).
     # Called with the raw connection; must return the (possibly wrapped) connection.
     #
@@ -399,7 +405,7 @@ module OMQ
     def signal_fatal_error(error)
       return unless @lifecycle.open?
       @fatal_error = begin
-        raise OMQ::SocketDeadError, "internal error killed #{@socket_type} socket"
+        raise SocketDeadError, "internal error killed #{@socket_type} socket"
       rescue => wrapped
         wrapped
       end
@@ -467,8 +473,10 @@ module OMQ
         raise ArgumentError, "unsupported transport: #{endpoint}"
     end
 
+
     private
 
+
     def spawn_connection(io, as_server:, endpoint: nil)
       task = @lifecycle.barrier&.async(transient: true, annotation: "conn #{endpoint}") do
         done      = Async::Promise.new
@@ -488,6 +496,11 @@ module OMQ
     end
 
 
+    # TODO: replace the 1 ms busy-poll with a promise/condition that
+    # the send pump resolves when its queue hits empty. The loop exists
+    # because there is currently no signal for "send queue fully
+    # drained"; fixing it cleanly requires plumbing a notifier through
+    # every routing strategy, so it is flagged rather than fixed here.
     def drain_send_queues(timeout)
       return unless @routing.respond_to?(:send_queues_drained?)
       deadline = timeout ? Async::Clock.now + timeout : nil

data/lib/omq/pair.rb

@@ -12,8 +12,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, backend: nil)
-      _init_engine(:PAIR, linger: linger, backend: backend)
-      _attach(endpoints, default: :connect)
+      init_engine(:PAIR, linger: linger, backend: backend)
+      attach_endpoints(endpoints, default: :connect)
     end
   end
 end

data/lib/omq/pub_sub.rb

@@ -13,8 +13,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, on_mute: :drop_newest, conflate: false, backend: nil)
-      _init_engine(:PUB, linger: linger, on_mute: on_mute, conflate: conflate, backend: backend)
-      _attach(endpoints, default: :bind)
+      init_engine(:PUB, linger: linger, on_mute: on_mute, conflate: conflate, backend: backend)
+      attach_endpoints(endpoints, default: :bind)
     end
   end
 
@@ -36,8 +36,8 @@ module OMQ
     # @param on_mute [Symbol] :block (default), :drop_newest, or :drop_oldest
     #
     def initialize(endpoints = nil, linger: 0, subscribe: nil, on_mute: :block, backend: nil)
-      _init_engine(:SUB, linger: linger, on_mute: on_mute, backend: backend)
-      _attach(endpoints, default: :connect)
+      init_engine(:SUB, linger: linger, on_mute: on_mute, backend: backend)
+      attach_endpoints(endpoints, default: :connect)
       self.subscribe(subscribe) unless subscribe.nil?
     end
 
@@ -75,8 +75,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, on_mute: :drop_newest, backend: nil)
-      _init_engine(:XPUB, linger: linger, on_mute: on_mute, backend: backend)
-      _attach(endpoints, default: :bind)
+      init_engine(:XPUB, linger: linger, on_mute: on_mute, backend: backend)
+      attach_endpoints(endpoints, default: :bind)
     end
   end
 
@@ -95,8 +95,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, subscribe: nil, on_mute: :block, backend: nil)
-      _init_engine(:XSUB, linger: linger, on_mute: on_mute, backend: backend)
-      _attach(endpoints, default: :connect)
+      init_engine(:XSUB, linger: linger, on_mute: on_mute, backend: backend)
+      attach_endpoints(endpoints, default: :connect)
       send("\x01#{subscribe}".b) unless subscribe.nil?
     end
   end

data/lib/omq/push_pull.rb

@@ -13,8 +13,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, send_hwm: nil, send_timeout: nil, backend: nil)
-      _init_engine(:PUSH, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout, backend: backend)
-      _attach(endpoints, default: :connect)
+      init_engine(:PUSH, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout, backend: backend)
+      attach_endpoints(endpoints, default: :connect)
     end
   end
 
@@ -31,8 +31,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, recv_hwm: nil, recv_timeout: nil, backend: nil)
-      _init_engine(:PULL, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout, backend: backend)
-      _attach(endpoints, default: :bind)
+      init_engine(:PULL, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout, backend: backend)
+      attach_endpoints(endpoints, default: :bind)
     end
   end
 end

data/lib/omq/queue_interface.rb

@@ -16,11 +16,13 @@ module OMQ
     # @raise [IO::TimeoutError] if timeout exceeded
     #
     def dequeue(timeout: @options.read_timeout)
-      Reactor.run { with_timeout(timeout) { @engine.dequeue_recv } }
+      Reactor.run(timeout:) { @engine.dequeue_recv }
     end
 
+
     alias_method :pop, :dequeue
 
+
     # Waits for the next message indefinitely (ignores read_timeout).
     #
     # @return [Array<String>] message parts

data/lib/omq/reactor.rb

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

data/lib/omq/readable.rb

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

data/lib/omq/req_rep.rb

@@ -12,8 +12,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, backend: nil)
-      _init_engine(:REQ, linger: linger, backend: backend)
-      _attach(endpoints, default: :connect)
+      init_engine(:REQ, linger: linger, backend: backend)
+      attach_endpoints(endpoints, default: :connect)
     end
   end
 
@@ -29,8 +29,8 @@ module OMQ
     # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, backend: nil)
-      _init_engine(:REP, linger: linger, backend: backend)
-      _attach(endpoints, default: :bind)
+      init_engine(:REP, linger: linger, backend: backend)
+      attach_endpoints(endpoints, default: :bind)
     end
   end
 end