cztop 1.1.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f398a80bc75445bfd115544ca7f3e4c9f894cd1b9d58a9f0e2a90f6c0841275
-  data.tar.gz: 4d6b4c393b573c8bd64f4a65317bd6bbf258c5c2a7137ecabc681be6713c6f6a
+  metadata.gz: 0a5218cd3606b597506aa29ea2bc0ccfe2ccd8030f1a0ce1c6ea90791fe7c88e
+  data.tar.gz: 3ad76dccf7e6bad9aff9a19f679bb3420dcf08ec742b109ff6c0a688f3fce4e4
 SHA512:
-  metadata.gz: 12567ad2f7cadeb6067edcf61fb3ba975635d236edd4a5dd5465b6dcb931cf7c8b4f5852892c5bd4c0c5f0aaa87488f21b7ccb81a73a5d4134928b55f276ce4a
-  data.tar.gz: 99d6274e17d86865e80328184825f525f2959dbe926e052c9af88423f40e0fbf6f53531ef5de8eb22225315f2629e3580fd34f094031c21bbb37a665946d58b7
+  metadata.gz: 36ac2f1e2b1f0ddfb78f3cd77fc7fbfdb78591c1c379b3fb96b92d80566fc8e07e39f666c78b1b2aa6771fcd2fb22d6e6b7a173040b9c489053af27030689220
+  data.tar.gz: ef8061d7082e73bf757335d5c6cd550aeb39dfbdb54314b893e44350e9065ea96874d09b89720fbbe4b98873a0e1b575f76f91266025dcb2d5d45b88b5c11c90

data/CHANGES.md

@@ -1,3 +1,14 @@
+1.2.0 (1/7/2024)
+-----
+* refactor waiting for socket readability/writability
+* fix ROUTER socket hanging in busy loop if ZMQ_ROUTER_MANDATORY flag is set and sending a message while no peers are connected
+* same for unconnected CLIENT sockets
+* slim down packaged gem
+* modernize examples
+* require Ruby 3.2
+* some exceptions changed from EAGAIN to IO::TimeoutError
+* Certificate.load and .new_from raise NotImplementedError if CURVE is not available
+
 1.1.2 (1/5/2024)
 -----
 * refactor to make code Fiber Scheduler agnostic

data/cztop.gemspec

@@ -12,13 +12,13 @@ Gem::Specification.new do |spec|
   spec.description   = 'CZMQ binding based on the generated low-level FFI bindings of CZMQ'
   spec.homepage      = "https://rubygems.org/gems/cztop"
   spec.license       = "ISC"
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.metadata["homepage_uri"]    = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/paddor/cztop"
   spec.metadata["changelog_uri"]   = "https://github.com/paddor/cztop/blob/master/CHANGELOG.md"
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match?(%r{^(\.|Rakefile|spec/|examples/|ci/|perf/)}) }
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
@@ -32,7 +32,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec-given", "~> 3.8.0"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "yard"
-  spec.add_development_dependency "rubocop", "~> 1.36.0"
 
   if RUBY_VERSION >= '3.1'
     spec.add_development_dependency "async", ">= 2.0.1"

data/lib/cztop/actor.rb

@@ -12,7 +12,7 @@ module CZTop
   #
   # = About termination
   # Actors should be terminated explicitly, either by calling {#terminate}
-  # from the current process or sending them the "$TERM" command (from
+  # from the current process or sending them the {TERMINATE} command (from
   # outside). Not terminating them explicitly might make the process block at
   # exit.
   #
@@ -48,12 +48,20 @@ module CZTop
     class DeadActorError < RuntimeError; end
 
 
+    # the command which causes an actor handler to terminate
+    TERMINATE = '$TERM'
+
+
+    # timeout to use when sending the actor a message
+    SEND_TIMEOUT = 20 # ms
+
+
     # @return [Exception] the exception that crashed this actor, if any
     attr_reader :exception
 
 
     # Creates a new actor. Either pass a callback directly or a block. The
-    # block will be called for every received message.
+    # callback/block will be called for every received message.
     #
     # In case the given callback is an FFI::Pointer (to a C function), it's
     # used as-is. It is expected to do the handshake (signal) itself.
@@ -71,8 +79,9 @@ module CZTop
       @callback        = callback || handler
       @callback        = shim(@callback) unless @callback.is_a? ::FFI::Pointer
       ffi_delegate     = Zactor.new(@callback, c_args)
+
       attach_ffi_delegate(ffi_delegate)
-      options.sndtimeo = 20 # ms # see #<<
+      options.sndtimeo = SEND_TIMEOUT # see #<<
     end
 
 
@@ -83,11 +92,11 @@ module CZTop
     # @raise [IO::EAGAINWaitWritable, RuntimeError] anything that could be
     #   raised by {Message#send_to}
     # @note Normally this method is asynchronous, but if the message is
-    #   "$TERM", it blocks until the actor is terminated.
+    #   {TERMINATE}, it blocks until the actor is terminated.
     def <<(message)
       message = Message.coerce(message)
 
-      if TERM == message[0]
+      if TERMINATE == message[0]
         # NOTE: can't just send this to the actor. The sender might call
         # #terminate immediately, which most likely causes a hang due to race
         # conditions.
@@ -99,7 +108,7 @@ module CZTop
 
             message.send_to(self)
           end
-        rescue IO::EAGAINWaitWritable
+        rescue IO::EAGAINWaitWritable, IO::TimeoutError
           # The sndtimeo has been reached.
           #
           # This should fix the race condition (mainly on JRuby) between
@@ -111,9 +120,8 @@ module CZTop
           # at least when using a Ruby handler.
           #
           # In case of a C function handler, it MUST NOT crash and only
-          # terminate when being sent the "$TERM" message using #terminate (so
-          # #await_handler_death can set
-          # @running to false).
+          # terminate when being sent the {TERMINATE} message using #terminate (so
+          # #await_handler_death can set @running to false).
           retry
         end
       end
@@ -138,13 +146,13 @@ module CZTop
     # it.
     # @param message [Message] the request to the actor
     # @return [Message] the actor's response
-    # @raise [ArgumentError] if the message is "$TERM" (use {#terminate})
+    # @raise [ArgumentError] if the message is {TERMINATE} (use {#terminate})
     def request(message)
       @mtx.synchronize do
         raise DeadActorError unless @running
 
         message = Message.coerce(message)
-        raise ArgumentError, 'use #terminate' if TERM == message[0]
+        raise ArgumentError, 'use #terminate' if TERMINATE == message[0]
 
         message.send_to(self)
         Message.receive_from(self)
@@ -189,11 +197,11 @@ module CZTop
       @mtx.synchronize do
         return false unless @running
 
-        Message.new(TERM).send_to(self)
+        Message.new(TERMINATE).send_to(self)
         await_handler_death
         true
       end
-    rescue IO::EAGAINWaitWritable
+    rescue IO::EAGAINWaitWritable, IO::TimeoutError
       # same as in #<<
       retry
     end
@@ -236,8 +244,8 @@ module CZTop
         end
 
         process_messages(handler)
-      rescue Exception
-        @exception = $ERROR_INFO
+      rescue Exception => e
+        @exception = e
       ensure
         signal_shimmed_handler_death
       end
@@ -251,16 +259,12 @@ module CZTop
     end
 
 
-    # the command which causes an actor handler to terminate
-    TERM = '$TERM'
-
-
     # Successively receive messages that were sent to the actor and
     # yield them to the given handler to process them. The a pipe (a
     # {Socket::PAIR} socket) is also passed to the handler so it can send back
     # the result of a command, if needed.
     #
-    # When a message is "$TERM", or when the waiting for a message is
+    # When a message is {TERMINATE}, or when the waiting for a message is
     # interrupted, execution is aborted and the actor will terminate.
     #
     # @param handler [Proc, #call] the handler used to process messages
@@ -274,7 +278,7 @@ module CZTop
         rescue Interrupt
           break
         else
-          break if TERM == message[0]
+          break if TERMINATE == message[0]
         end
 
         handler.call(message, @pipe)
@@ -294,7 +298,7 @@ module CZTop
     #
     # This is needed to avoid the race condition between zactor_destroy()
     # which will wait for a signal from the handler in case it was able to
-    # send the "$TERM" command, and the @callback which might still haven't
+    # send the {TERMINATE} command, and the @callback which might still haven't
     # returned, but doesn't receive any messages anymore.
     #
     # @return [void]

data/lib/cztop/certificate.rb

@@ -8,19 +8,15 @@ module CZTop
     extend CZTop::HasFFIDelegate::ClassMethods
     include ::CZMQ::FFI
 
-    unless ::CZMQ::FFI::Zsys.has_curve
-      def self.new(...)
-        fail NotImplementedError
-      end
-    end
-
-
     # Warns if CURVE security isn't available.
-    # @return [void]
+    # @return [Boolean] whether it's available
     def self.check_curve_availability
-      return if Zsys.has_curve
-
-      warn "CZTop: CURVE isn't available. Consider installing libsodium."
+      if Zsys.has_curve
+        true
+      else
+        warn "CZTop: CURVE isn't available. Consider installing libsodium."
+        false
+      end
     end
 
 
@@ -57,6 +53,18 @@ module CZTop
       from_ffi_delegate(ptr)
     end
 
+    unless ::CZMQ::FFI::Zsys.has_curve
+      def self.new(...)
+        fail NotImplementedError
+      end
+      def self.load(...)
+        fail NotImplementedError
+      end
+      def self.new_from(...)
+        fail NotImplementedError
+      end
+    end
+
 
     # Initialize a new in-memory certificate with random keys.
     def initialize

data/lib/cztop/message.rb

@@ -49,7 +49,7 @@ module CZTop
     # @raise [IO::EAGAINWaitWritable] if the send timeout has been reached
     #   (see {ZsockOptions::OptionsAccessor#sndtimeo=})
     # @raise [SocketError] if the message can't be routed to the destination
-    #   (either if ROUTER_MANDATORY flag is set on a {Socket::ROUTER} socket
+    #   (either if ZMQ_ROUTER_MANDATORY flag is set on a {Socket::ROUTER} socket
     #   and the peer isn't connected or its SNDHWM is reached (see
     #   {ZsockOptions::OptionsAccessor#router_mandatory=}, or if it's
     #   a {Socket::SERVER} socket and there's no connected CLIENT
@@ -61,7 +61,7 @@ module CZTop
     #   returns with failure. Please report as bug.
     #
     def send_to(destination)
-      destination.wait_writable if Fiber.scheduler
+      destination.wait_writable
 
       rc = Zmsg.send(ffi_delegate, destination)
       return if rc.zero?
@@ -81,7 +81,7 @@ module CZTop
     # @raise [SystemCallError] for any other error code set after +zmsg_recv+
     #   returns with failure. Please report as bug.
     def self.receive_from(source)
-      source.wait_readable if Fiber.scheduler
+      source.wait_readable
 
       delegate = Zmsg.recv(source)
       return from_ffi_delegate(delegate) unless delegate.null?

data/lib/cztop/send_receive_methods.rb

@@ -10,7 +10,7 @@ module CZTop
     # Sends a message.
     #
     # @param message [Message, String, Array<parts>] the message to send
-    # @raise [IO::EAGAINWaitWritable] if send timeout has been reached (see
+    # @raise [IO::EAGAINWaitWritable, IO::TimeoutError] if send timeout has been reached (see
     #   {ZsockOptions::OptionsAccessor#sndtimeo=})
     # @raise [Interrupt, ArgumentError, SystemCallError] anything raised by
     #   {Message#send_to}
@@ -26,7 +26,7 @@ module CZTop
     # Receives a message.
     #
     # @return [Message]
-    # @raise [IO::EAGAINWaitReadable] if receive timeout has been reached (see
+    # @raise [IO::EAGAINWaitReadable, IO::TimeoutError] if receive timeout has been reached (see
     #   {ZsockOptions::OptionsAccessor#rcvtimeo=})
     # @raise [Interrupt, ArgumentError, SystemCallError] anything raised by
     #   {Message.receive_from}
@@ -36,7 +36,13 @@ module CZTop
     end
 
 
+    JIFFY = 0.015 # 15 ms
+
+
     # Waits for socket to become readable.
+    # @param timeout [Numeric, nil] timeout in seconds
+    # @return [true] if readable within timeout
+    # @raise [IO::EAGAINWaitReadable, IO::TimeoutError] if timeout has been reached
     def wait_readable(timeout = read_timeout)
       return true if readable?
 
@@ -47,16 +53,29 @@ module CZTop
 
         while true
           @fd_io.wait_readable(timeout)
-          break if readable? # NOTE: ZMQ FD can't be trusted 100%
+          break if readable? # NOTE: ZMQ FD can't be trusted
           raise ::IO::TimeoutError if now >= timeout_at
+
+          # HACK for edge case: avoid hogging CPU if FD for socket type doesn't block and just insists
+          sleep JIFFY
         end
       else
-        @fd_io.wait_readable until readable?
+        until readable?
+          @fd_io.wait_readable
+
+          # HACK for edge case: avoid hogging CPU if FD for socket type doesn't block and just insists
+          sleep JIFFY
+        end
       end
+
+      true
     end
 
 
     # Waits for socket to become writable.
+    # @param timeout [Numeric, nil] timeout in seconds
+    # @return [true] if writable within timeout
+    # @raise [IO::EAGAINWaitReadable, IO::TimeoutError] if timeout has been reached
     def wait_writable(timeout = write_timeout)
       return true if writable?
 
@@ -67,12 +86,22 @@ module CZTop
 
         while true
           @fd_io.wait_writable(timeout)
-          break if writable? # NOTE: ZMQ FD can't be trusted 100%
+          break if writable? # NOTE: ZMQ FD can't be trusted
           raise ::IO::TimeoutError if now >= timeout_at
+
+          # HACK for edge case: avoid hogging CPU if FD for socket type doesn't block and just insists
+          sleep JIFFY
         end
       else
-        @fd_io.wait_writable until writable?
+        until writable?
+          @fd_io.wait_writable
+
+          # HACK for edge case: avoid hogging CPU if FD for socket type doesn't block and just insists
+          sleep JIFFY
+        end
       end
+
+      true
     end
 
 

data/lib/cztop/socket/types.rb

@@ -76,6 +76,15 @@ module CZTop
         attach_ffi_delegate(Zsock.new_client(endpoints))
       end
 
+
+      # @raise [SocketError] if no peer is connected
+      def wait_writable(...)
+        if !writable?
+          fail SocketError, "no peer connected"
+        end
+
+        super
+      end
     end
 
 
@@ -160,6 +169,15 @@ module CZTop
         self << message
       end
 
+
+      # @raise [SocketError] if ZMQ_ROUTER_MANDATORY option and message is currently not routable
+      def wait_writable(...)
+        if options.router_mandatory? && !writable?
+          fail SocketError, "no peer connected"
+        end
+
+        super
+      end
     end
 
 

data/lib/cztop/version.rb

@@ -2,6 +2,6 @@
 
 module CZTop
 
-  VERSION = '1.1.2'
+  VERSION = '1.2.0'
 
 end

data/lib/cztop/zsock_options.rb

@@ -325,11 +325,19 @@ module CZTop
 
       # @!endgroup
 
-      # Accept only routable messages on ROUTER sockets. Default is off.
-      # @param bool [Boolean] whether to error if a message isn't routable
+      # ZMQ_ROUTER_MANDATORY: Accept only routable messages on ROUTER sockets. Default is off.
+      # @param bool [Boolean] whether to raise a SocketError if a message isn't routable
       #   (either if the that peer isn't connected or its SNDHWM is reached)
+      # @see https://libzmq.readthedocs.io/en/latest/zmq_setsockopt.html#_zmq_router_mandatory_accept_only_routable_messages_on_router_sockets
       def router_mandatory=(bool)
         Zsock.set_router_mandatory(@zocket, bool ? 1 : 0)
+        @router_mandatory = bool # NOTE: no way to read this option, so we need to remember
+      end
+
+
+      # @return [Boolean] whether ZMQ_ROUTER_MANDATORY has been set
+      def router_mandatory?
+        @router_mandatory
       end
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cztop
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Patrik Wenger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-01-05 00:00:00.000000000 Z
+date: 2024-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: czmq-ffi-gen
@@ -122,20 +122,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.36.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.36.0
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -159,39 +145,14 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/coverage.yml"
-- ".github/workflows/draft_api.yml"
-- ".github/workflows/stable_api.yml"
-- ".gitignore"
-- ".projections.json"
-- ".rspec"
-- ".rubocop.yml"
-- ".yardopts"
 - AUTHORS
 - CHANGES.md
 - Gemfile
 - LICENSE
 - README.md
-- Rakefile
 - bin/console
 - bin/setup
-- ci/install-libczmq
-- ci/install-libzmq
 - cztop.gemspec
-- examples/ruby_actor/actor.rb
-- examples/simple_req_rep/rep.rb
-- examples/simple_req_rep/req.rb
-- examples/taxi_system/.gitignore
-- examples/taxi_system/Makefile
-- examples/taxi_system/README.gsl
-- examples/taxi_system/README.md
-- examples/taxi_system/broker.rb
-- examples/taxi_system/client.rb
-- examples/taxi_system/generate_keys.rb
-- examples/taxi_system/start_broker.sh
-- examples/taxi_system/start_clients.sh
-- examples/weather_pub_sub/pub.rb
-- examples/weather_pub_sub/sub.rb
 - exe/z85decode
 - exe/z85encode
 - lib/cztop.rb
@@ -225,11 +186,6 @@ files:
 - lib/cztop/z85/pipe.rb
 - lib/cztop/zap.rb
 - lib/cztop/zsock_options.rb
-- perf/README.md
-- perf/inproc_lat.rb
-- perf/inproc_thru.rb
-- perf/local_lat.rb
-- perf/remote_lat.rb
 homepage: https://rubygems.org/gems/cztop
 licenses:
 - ISC
@@ -245,7 +201,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.github/workflows/coverage.yml

@@ -1,20 +0,0 @@
-name: Coverage
-
-on: [push,pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-22.04
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: 3.3
-    - name: Install CZMQ
-      run: sudo apt-get install libczmq-dev
-    - name: Run the default task
-      run: |
-        gem install bundler
-        bundle install
-        env REPORT_COVERAGE=true bundle exec rake

data/.github/workflows/draft_api.yml

@@ -1,27 +0,0 @@
-name: DRAFT API
-
-on: [push,pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-22.04
-    timeout-minutes: 15
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: '3.3'
-    - name: Install ZMQ and CZMQ
-      run: |
-        export PKG_CONFIG_PATH=$HOME/lib/pkgconfig # custom libs (for linking)
-        env
-        env ZMQ_VERSION=HEAD ci/install-libzmq
-        env CZMQ_VERSION=HEAD ci/install-libczmq
-    - name: Run the default task
-      run: |
-        export LD_LIBRARY_PATH=$HOME/lib # custom libs (for execution)
-        env
-        gem install bundler
-        bundle install
-        bundle exec rake

data/.github/workflows/stable_api.yml

@@ -1,26 +0,0 @@
-name: STABLE API
-
-on: [push,pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-22.04
-    strategy:
-      matrix:
-        ruby:
-          - '3.1'
-          - '3.2'
-          - '3.3'
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby ${{ matrix.ruby }}
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-    - name: Install CZMQ
-      run: sudo apt-get install libczmq-dev
-    - name: Run the default task
-      run: |
-        gem install bundler
-        bundle install
-        bundle exec rake

data/.gitignore

@@ -1,10 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-/*.vimsession

data/.projections.json

@@ -1,4 +0,0 @@
-{
-  "lib/*.rb": { "alternate": "spec/{}_spec.rb" },
-  "spec/*_spec.rb": { "alternate": "lib/{}.rb", "dispatch": "bundle exec rspec -ff {file}" }
-}

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---color