cztop 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c9e575b8a9eb164ac1dfa55ed1cf586f9f37238f1c8b2e46a9063ef897ff3b5
-  data.tar.gz: 829ed1baf3e3c0ec4816ff021c866bd40aaa8134f8332b8f9f56635d27d22730
+  metadata.gz: f3e5938035e1b344dafa25665293cddc9017c5b9c47280bacc9fc4b9ff97fc2e
+  data.tar.gz: 16b1a7896a2f118cfd2fcfa2829acbeb5e3d021472c34aa6dfd190ed8bb1a5bf
 SHA512:
-  metadata.gz: 3f0fb0eb3c60d9d792d6122cf61c60b7e705f6252d6bc760363a1490a7354f628dd3d3f982858bea435ebc928c60752197727f6f522fe894b77bdbb755773f98
-  data.tar.gz: 9fa64c0c8e5896146e5cd2b2034ffd6e663416f4c6bcfe8ffcf4260f683524fc83a773f8da31b2284fb858284ca18c2897a8114c11b26d893150ffda775a40d8
+  metadata.gz: 5e6058194cbb28727e78f92a431c203ee45f5363a89e4fbaa3026553d3b3b8610240947b7336f5625218458acd77388038734b00a966c8f6fa3ac7c45d9616a0
+  data.tar.gz: b549f127a5031b643807702ee279a0dc4565f252c3489b10da5f6191617162f618946518175e3bb4de4c3c7b1628fb355ad5c063f31c2b05c34bf93c07d15f2c

data/CHANGES.md

@@ -1,3 +1,22 @@
+## [Unreleased]
+
+2.0.3
+-----
+
+* Port specs to named `Minitest::Spec` subclasses with ordinary Ruby helpers
+* Add regression coverage for native library loading and fallback
+* Raise native send/receive errors immediately instead of waiting for readiness
+* Raise `IO::EAGAINWaitReadable`/`IO::EAGAINWaitWritable` when nonblocking I/O
+  would block
+* Convert all multipart message parts before sending the first frame
+* Avoid an extra array allocation for scalar sends without modifying caller arrays
+* Free native identity strings and messages retained after failed sends
+* Reject endpoint and subscription operations on closed sockets, and receive
+  operations on closed monitors
+* Close the CURVE authentication socket in its responder thread during shutdown
+* Fix linger documentation to use seconds
+* Clean up benchmark socket lifetimes and refresh measurements and README
+
 2.0.2
 -----
 

data/README.md

@@ -5,17 +5,17 @@
 [![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)
 
-Ruby FFI binding for [CZMQ](http://czmq.zeromq.org/) / [ZeroMQ](https://zeromq.org/) — high-performance asynchronous messaging for distributed systems.
+Ruby FFI binding for [CZMQ](https://github.com/zeromq/czmq) and [ZeroMQ](https://zeromq.org/), with support for threads, Fiber Scheduler, and CURVE encryption.
 
-> **353k msg/s** inproc throughput | **49 µs** fiber roundtrip latency | nonblock fast path
+> **310k msg/s** inproc throughput (64 B) | **61 µs** Async roundtrip latency
 
 ---
 
 ## Highlights
 
-- **All socket types** — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair, stream
-- **Async-first** — first-class [async](https://github.com/socketry/async) fiber support, also works with plain threads
-- **Ruby-idiomatic API** — messages as `Array<String>`, errors as exceptions, timeouts as `IO::TimeoutError`
+- **Socket types:** REQ/REP, PUB/SUB, PUSH/PULL, DEALER/ROUTER, XPUB/XSUB, PAIR, STREAM
+- **Fibers and threads:** works with [async](https://github.com/socketry/async) and plain threads
+- **Ruby API:** messages as `Array<String>`, errors as exceptions, timeouts as `IO::TimeoutError`
 
 ## Install
 
@@ -33,17 +33,21 @@ Then add the gem:
 
 ```sh
 gem install cztop
-# or in Gemfile
+```
+
+Or add it to your Gemfile:
+
+```ruby
 gem 'cztop'
 ```
 
 ## Learning ZeroMQ
 
-New to ZeroMQ? See [ZGUIDE_SUMMARY.md](ZGUIDE_SUMMARY.md) — a ~30 min read covering all major patterns with working CZTop code examples.
+New to ZeroMQ? See [ZGUIDE_SUMMARY.md](ZGUIDE_SUMMARY.md) for messaging patterns and working CZTop examples.
 
 ## Quick Start
 
-### Request / Reply
+### REQ / REP
 
 ```ruby
 require 'cztop'
@@ -63,7 +67,7 @@ Async do |task|
 end
 ```
 
-### Pub / Sub
+### PUB / SUB
 
 ```ruby
 Async do |task|
@@ -78,7 +82,7 @@ Async do |task|
 end
 ```
 
-### Push / Pull (Pipeline)
+### PUSH / PULL (Pipeline)
 
 ```ruby
 Async do
@@ -95,7 +99,8 @@ end
 | Pattern | Classes | Direction |
 |---------|---------|-----------|
 | Request/Reply | `REQ`, `REP` | bidirectional |
-| Publish/Subscribe | `PUB`, `SUB`, `XPUB`, `XSUB` | unidirectional |
+| Publish/Subscribe | `PUB`, `SUB` | unidirectional |
+| Subscription forwarding | `XPUB`, `XSUB` | bidirectional |
 | Pipeline | `PUSH`, `PULL` | unidirectional |
 | Routing | `DEALER`, `ROUTER` | bidirectional |
 | Exclusive pair | `PAIR` | bidirectional |
@@ -105,23 +110,23 @@ All classes live under `CZTop::Socket::`.
 
 ## Performance
 
-Benchmarked with benchmark-ips on Linux x86_64 (CZMQ 4.2.1, ZMQ 4.3.5, Ruby 4.0.1 +YJIT):
+Benchmarked with benchmark-ips on Linux x86_64 (CZMQ 4.2.1, ZMQ 4.3.5, Ruby 4.0.6 +YJIT):
 
-#### Throughput (push/pull)
+#### Throughput (PUSH/PULL, 64 B messages)
 
 | | inproc | ipc | tcp |
 |---|--------|-----|-----|
-| **Async** | 284k/s | 17k/s | 14k/s |
-| **Threads** | 353k/s | 25k/s | 21k/s |
+| **Async** | 278k/s | 18.3k/s | 15.8k/s |
+| **Threads** | 310k/s | 18.3k/s | 16.2k/s |
 
-#### Latency (req/rep roundtrip)
+#### Latency (REQ/REP roundtrip)
 
 | | inproc | ipc | tcp |
 |---|--------|-----|-----|
-| **Async** | 49 µs | 100 µs | 107 µs |
-| **Threads** | 113 µs | 154 µs | 168 µs |
+| **Async** | 60.7 µs | 112.6 µs | 127.8 µs |
+| **Threads** | 74.9 µs | 109.2 µs | 119.6 µs |
 
-Async fibers deliver 2.3x lower inproc latency thanks to cheap context switching. See [`bench/`](bench/) for full results and scripts.
+See [bench/README.md](bench/README.md) for full results, measurement details, and scripts.
 
 ## API Reference
 

data/lib/cztop/curve/auth.rb

@@ -29,7 +29,9 @@ module CZTop
         @allow_any = allow_any
         @zap = CZTop::Socket::REP.new
         @zap.linger = 0
+        @zap.recv_timeout = 0.1
         @zap.bind('inproc://zeromq.zap.01')
+        @stopping = false
         @thread = Thread.new { run }
         ObjectSpace.define_finalizer(self, self.class._poststop(@thread))
       end
@@ -60,8 +62,9 @@ module CZTop
       #
       def stop
         ObjectSpace.undefine_finalizer(self)
-        @zap.close
-        @thread.join(1)
+        @stopping = true
+        @thread.join
+        nil
       end
 
       # @api private
@@ -75,8 +78,12 @@ module CZTop
       private
 
       def run
-        loop do
-          msg = @zap.receive
+        until @stopping
+          begin
+            msg = @zap.receive
+          rescue IO::TimeoutError
+            next
+          end
           # ZAP request: [version, request_id, domain, address, identity, mechanism, credential]
           version    = msg[0]
           request_id = msg[1]
@@ -90,8 +97,8 @@ module CZTop
 
           @zap.__send__(:send, [version, request_id, status, '', '', ''])
         end
-      rescue
-        # Socket closed or thread interrupted → exit gracefully
+      ensure
+        @zap.close
       end
 
     end

data/lib/cztop/curve.rb

@@ -6,7 +6,7 @@ module CZTop
   #
   # Provides keypair generation, key derivation, and Z85 encoding/decoding.
   # CURVE options are applied to sockets via the +curve:+ keyword argument
-  # in socket constructors — there are no public CURVE methods on Socket.
+  # in socket constructors; there are no public CURVE methods on Socket.
   #
   module CURVE
 

data/lib/cztop/ffi.rb

@@ -6,6 +6,8 @@ module CZMQ
   module FFI
     extend ::FFI::Library
 
+    # Runtime packages may only include versioned sonames. Keep each library's
+    # alternatives in one array so FFI can fall back to platform-specific names.
     ffi_lib ['libzmq.so.5', 'libzmq'], ['libczmq.so.4', 'libczmq']
 
     # -----------------------------------------------------------------
@@ -122,6 +124,7 @@ module CZMQ
     # -----------------------------------------------------------------
     attach_function :zstr_send,  [:pointer, :string], :int, **opts
     attach_function :zstr_sendm, [:pointer, :string], :int, **opts
+    attach_function :zstr_free,  [:pointer], :void
 
     # -----------------------------------------------------------------
     # zsock_wait (used for zactor START synchronization)
@@ -296,23 +299,23 @@ module CZMQ
 
       # Instance methods
       def endpoint
-        CZMQ::FFI.zsock_endpoint(@ptr)
+        CZMQ::FFI.zsock_endpoint(to_ptr)
       end
 
       def connect(format, *args)
-        CZMQ::FFI.zsock_connect(@ptr, format, *args)
+        CZMQ::FFI.zsock_connect(to_ptr, format, *args)
       end
 
       def disconnect(format, *args)
-        CZMQ::FFI.zsock_disconnect(@ptr, format, *args)
+        CZMQ::FFI.zsock_disconnect(to_ptr, format, *args)
       end
 
       def bind(format, *args)
-        CZMQ::FFI.zsock_bind(@ptr, format, *args)
+        CZMQ::FFI.zsock_bind(to_ptr, format, *args)
       end
 
       def unbind(format, *args)
-        CZMQ::FFI.zsock_unbind(@ptr, format, *args)
+        CZMQ::FFI.zsock_unbind(to_ptr, format, *args)
       end
 
       def destroy
@@ -325,11 +328,11 @@ module CZMQ
       end
 
       def set_subscribe(prefix)
-        CZMQ::FFI.zsock_set_subscribe(@ptr, prefix)
+        CZMQ::FFI.zsock_set_subscribe(to_ptr, prefix)
       end
 
       def set_unsubscribe(prefix)
-        CZMQ::FFI.zsock_set_unsubscribe(@ptr, prefix)
+        CZMQ::FFI.zsock_set_unsubscribe(to_ptr, prefix)
       end
 
       # Class methods that take a zsock pointer (or wrapper with to_ptr)
@@ -423,9 +426,15 @@ module CZMQ
       # Override Object#send: int zmsg_send(zmsg_t **self_p, void *dest)
       # Called as: Zmsg.send(zmsg_wrapper_or_ptr, destination)
       def self.send(msg, dest)
-        msg_ptr = msg.respond_to?(:__ptr_give_ref) ? msg.__ptr_give_ref : msg
         dest_ptr = dest.respond_to?(:to_ptr) ? dest.to_ptr : dest
-        CZMQ::FFI.zmsg_send(msg_ptr, dest_ptr)
+        msg_ptr = msg.respond_to?(:__ptr_give_ref) ? msg.__ptr_give_ref : msg
+        rc = CZMQ::FFI.zmsg_send(msg_ptr, dest_ptr)
+        unless rc.zero?
+          errno = CZMQ::FFI::Errors.errno
+          CZMQ::FFI.zmsg_destroy(msg_ptr) if msg.respond_to?(:__ptr_give_ref)
+          CZTop::HasFFIDelegate.raise_zmq_err(errno: errno)
+        end
+        rc
       end
 
       def self.recv(source)
@@ -437,17 +446,17 @@ module CZMQ
       # Appends a Ruby string directly without intermediate MemoryPointer copy.
       # Uses :buffer_in to pass the string's internal buffer pointer to C.
       def add_buffer(str)
-        CZMQ::FFI.zmsg_addmem_s(@ptr, str, str.bytesize)
+        CZMQ::FFI.zmsg_addmem_s(to_ptr, str, str.bytesize)
       end
 
       def first
-        ptr = CZMQ::FFI.zmsg_first(@ptr)
+        ptr = CZMQ::FFI.zmsg_first(to_ptr)
         return nil if ptr.null?
         _borrowed_frame(ptr)
       end
 
       def next
-        ptr = CZMQ::FFI.zmsg_next(@ptr)
+        ptr = CZMQ::FFI.zmsg_next(to_ptr)
         return nil if ptr.null?
         _borrowed_frame(ptr)
       end
@@ -461,7 +470,7 @@ module CZMQ
     end
 
     # -----------------------------------------------------------------
-    # Zframe (lightweight — only used for borrowed frames from Zmsg)
+    # Zframe (lightweight; only used for borrowed frames from Zmsg)
     # -----------------------------------------------------------------
     class Zframe
       # Wraps a borrowed zframe_t pointer (not owned, no finalizer).

data/lib/cztop/monitor.rb

@@ -69,6 +69,7 @@ module CZTop
     # @return [Event, nil] the event, or nil on timeout
     #
     def receive(timeout: 0.1)
+      raise IOError, 'monitor is closed' if @closed
       CZMQ::FFI.zsock_set_rcvtimeo(@actor_ptr, (timeout * 1000).to_i)
 
       zmsg_ptr = CZMQ::FFI.zmsg_recv(@actor_ptr)

data/lib/cztop/socket/dealer.rb

@@ -13,7 +13,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to connect to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/pair.rb

@@ -13,7 +13,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to connect to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/pub.rb

@@ -12,7 +12,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to bind to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/pull.rb

@@ -12,7 +12,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to bind to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/push.rb

@@ -12,7 +12,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to connect to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/readable.rb

@@ -18,6 +18,7 @@ module CZTop
         # Fast path: nonblock recv (no GVL release)
         parts = recv_nonblock
         return parts if parts
+        raise IO::EAGAINWaitReadable if read_timeout == 0
 
         # Slow path: FD poll → blocking recv
         wait_readable
@@ -56,7 +57,11 @@ module CZTop
       def recv_nonblock
         sock_ptr = to_ptr
         frame = CZMQ::FFI.zframe_recv_nowait(sock_ptr)
-        return nil if frame.null?
+        if frame.null?
+          errno = CZMQ::FFI::Errors.errno
+          HasFFIDelegate.raise_zmq_err(errno: errno) unless errno == Errno::EAGAIN::Errno
+          return nil
+        end
 
         pp = _zframe_pp
         parts = []

data/lib/cztop/socket/rep.rb

@@ -13,7 +13,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to bind to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/req.rb

@@ -13,7 +13,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to connect to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/router.rb

@@ -13,7 +13,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to bind to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/stream.rb

@@ -14,7 +14,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to connect to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/sub.rb

@@ -17,7 +17,7 @@ module CZTop
       # @param prefix [String, nil] subscription prefix; defaults to no
       #   subscription. Pass {EVERYTHING} (+""+) to subscribe to everything.
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, prefix: nil, curve: nil, linger: 0)
         super(endpoints, curve: curve, linger: linger)

data/lib/cztop/socket/writable.rb

@@ -16,18 +16,19 @@ module CZTop
       # @return [self]
       #
       def send(message)
-        parts = message.is_a?(Array) ? message : [message]
+        parts = message.is_a?(Array) ? message.map(&:to_s) : [message.to_s]
         raise ArgumentError, 'message has no parts' if parts.empty?
 
         # Fast path: nonblock send (no GVL release)
         return self if send_nonblock(parts)
+        raise IO::EAGAINWaitWritable if write_timeout == 0
 
         # Slow path: FD poll → blocking send
         wait_writable
 
         zmsg = CZMQ::FFI::Zmsg.new
         parts.each do |part|
-          rc = zmsg.add_buffer(part.to_s)
+          rc = zmsg.add_buffer(part)
           HasFFIDelegate.raise_zmq_err unless rc.zero?
         end
 
@@ -65,9 +66,8 @@ module CZTop
         last_idx = parts.size - 1
 
         parts.each_with_index do |part, i|
-          str = part.to_s
-          frame = CZMQ::FFI.zframe_new_s(str, str.bytesize)
-          return false if frame.null?
+          frame = CZMQ::FFI.zframe_new_s(part, part.bytesize)
+          raise NoMemoryError, 'could not allocate message frame' if frame.null?
 
           flags = CZMQ::FFI::ZFRAME_DONTWAIT
           flags |= CZMQ::FFI::ZFRAME_MORE if i < last_idx
@@ -75,7 +75,9 @@ module CZTop
           pp.write_pointer(frame)
           rc = CZMQ::FFI.zframe_send(pp, sock_ptr, flags)
           unless rc.zero?
+            errno = CZMQ::FFI::Errors.errno
             CZMQ::FFI.zframe_destroy(pp)
+            HasFFIDelegate.raise_zmq_err(errno: errno) unless errno == Errno::EAGAIN::Errno
             return false
           end
         end

data/lib/cztop/socket/xpub.rb

@@ -13,7 +13,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to bind to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket/xsub.rb

@@ -13,7 +13,7 @@ module CZTop
 
       # @param endpoints [String] endpoints to connect to
       # @param curve [Hash, nil] CURVE encryption options
-      # @param linger [Integer] linger period in milliseconds (default: 0)
+      # @param linger [Numeric, nil] linger period in seconds (default: 0)
       #
       def initialize(endpoints = nil, curve: nil, linger: 0)
         super

data/lib/cztop/socket.rb

@@ -142,7 +142,7 @@ module CZTop
     # Connects or binds based on CZMQ endpoint prefix convention.
     # @api private
     # @param endpoints [String] endpoint, optionally prefixed with +@+ (bind) or +>+ (connect)
-    # @param default [Symbol] +:connect+ or +:bind+ — action when no prefix given
+    # @param default [Symbol] +:connect+ or +:bind+; action when no prefix given
     #
     def _attach(endpoints, default:)
       return unless endpoints

data/lib/cztop/version.rb

@@ -2,6 +2,6 @@
 
 module CZTop
 
-  VERSION = '2.0.2'
+  VERSION = '2.0.3'
 
 end

data/lib/cztop/zsock_options.rb

@@ -145,7 +145,15 @@ module CZTop
     # @return [String] current socket identity
     #
     def identity
-      Zsock.identity(self).read_string
+      ptr = Zsock.identity(self)
+      HasFFIDelegate.raise_zmq_err if ptr.null?
+      begin
+        ptr.read_string
+      ensure
+        ref = ::FFI::MemoryPointer.new(:pointer)
+        ref.write_pointer(ptr)
+        CZMQ::FFI.zstr_free(ref)
+      end
     end
 
 

data/lib/cztop.rb

@@ -40,5 +40,5 @@ require_relative 'cztop/monitor'
 require_relative 'cztop/curve'
 require_relative 'cztop/curve/auth'
 
-# Convenience alias — allows `Cztop::Socket::REQ` alongside `CZTop::Socket::REQ`.
+# Convenience alias; allows `Cztop::Socket::REQ` alongside `CZTop::Socket::REQ`.
 Cztop = CZTop

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cztop
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.3
 platform: ruby
 authors:
 - Patrik Wenger
@@ -198,7 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.20
 specification_version: 4
 summary: CZMQ FFI binding to bring ZMQ sockets to Ruby
 test_files: []