cztop 0.1.0

data/lib/cztop/zsock_options.rb

@@ -0,0 +1,334 @@
+module CZTop
+  # This module adds the ability to access options of a {Socket} or an
+  # {Actor}.
+  #
+  # @note Most socket options only take effect for subsequent bind/connects.
+  #
+  # @see http://api.zeromq.org/4-1:zmq-setsockopt
+  # @see http://api.zeromq.org/4-1:zmq-getsockopt
+  # @see http://api.zeromq.org/czmq3-0:zsock-option
+  #
+  module ZsockOptions
+    # Access to the options of this socket.
+    # @return [OptionsAccessor]
+    def options
+      OptionsAccessor.new(self)
+    end
+
+    # Used to access the options of a {Socket} or {Actor}.
+    class OptionsAccessor
+      # @return [Socket, Actor] whose options this {OptionsAccessor} instance
+      #   is accessing
+      attr_reader :zocket
+
+      # @param zocket [Socket, Actor]
+      def initialize(zocket)
+        @zocket = zocket
+      end
+
+      # Fuzzy option getter. This is to make it easier when porting
+      # applications from CZMQ libraries to CZTop.
+      # @param option_name [Symbol, String] case insensitive option name
+      # @raise [NoMethodError] if option name can't be recognized
+      def [](option_name)
+        # NOTE: beware of predicates, especially #CURVE_server? & friends
+        m = public_methods.reject { |m| m =~ /=$/ }
+              .find { |m| m =~ /^#{option_name}\??$/i }
+        raise NoMethodError, option_name if m.nil?
+        __send__(m)
+      end
+
+      # Fuzzy option setter. This is to make it easier when porting
+      # applications from CZMQ libraries to CZTop.
+      # @param option_name [Symbol, String] case insensitive option name
+      # @param new_value [String, Integer] new value
+      # @raise [NoMethodError] if option name can't be recognized
+      def []=(option_name, new_value)
+        m = public_methods.find { |m| m =~ /^#{option_name}=$/i }
+        raise NoMethodError, option_name if m.nil?
+        __send__(m, new_value)
+      end
+
+      include CZMQ::FFI
+
+      # @!group High Water Marks
+
+      # @return [Integer] the send high water mark
+      def sndhwm() Zsock.sndhwm(@zocket) end
+      # @param value [Integer] the new send high water mark.
+      def sndhwm=(value) Zsock.set_sndhwm(@zocket, value) end
+      # @return [Integer] the receive high water mark
+      def rcvhwm() Zsock.rcvhwm(@zocket) end
+      # @param value [Integer] the new receive high water mark
+      def rcvhwm=(value) Zsock.set_rcvhwm(@zocket, value) end
+
+      # @!endgroup
+
+      # @!group (CURVE) Security
+
+      # @return [Boolean] whether this zocket is a CURVE server
+      def CURVE_server?() Zsock.curve_server(@zocket) > 0 end
+
+      # Make this zocket a CURVE server.
+      # @param bool [Boolean]
+      # @note You'll have to use a {CZTop::Authenticator}.
+      def CURVE_server=(bool)
+        Zsock.set_curve_server(@zocket, bool ? 1 : 0)
+      end
+
+      # @return [String] Z85 encoded server key set
+      # @return [nil] if the current mechanism isn't CURVE or CURVE isn't
+      #   supported
+      def CURVE_serverkey
+        CURVE_key(:curve_serverkey)
+      end
+
+      # Get one of the CURVE keys.
+      # @param key_name [Symbol] something like +:curve_serverkey+
+      # @return [String, nil] key, if CURVE is supported and active, or nil
+      def CURVE_key(key_name)
+        return nil if mechanism != :CURVE
+        ptr = Zsock.__send__(key_name, @zocket)
+        return nil if ptr.null?
+        ptr.read_string
+      end
+      private :CURVE_key
+
+      # Sets the server's public key, so the zocket can authenticate the
+      # remote server.
+      # @param key [String] Z85 (40 bytes) or binary (32 bytes) server key
+      # @raise [ArgumentError] if key has wrong size
+      def CURVE_serverkey=(key)
+        case key.bytesize
+        when 40
+          Zsock.set_curve_serverkey(@zocket, key)
+        when 32
+          ptr = ::FFI::MemoryPointer.from_string(key)
+          Zsock.set_curve_serverkey_bin(@zocket, ptr)
+        else
+          raise ArgumentError, "invalid server key: %p" % key
+        end
+      end
+
+      # supported security mechanisms and their macro value equivalent
+      MECHANISMS = {
+        0 => :NULL,  # ZMQ_NULL
+        1 => :PLAIN, # ZMQ_PLAIN
+        2 => :CURVE, # ZMQ_CURVE
+        3 => :GSSAPI # ZMQ_GSSAPI
+      }
+
+      # @return [Symbol] the current security mechanism in use
+      # @note This is automatically set through the use of CURVE certificates,
+      #   etc
+      def mechanism
+        #int zsock_mechanism (void *self);
+        code = Zsock.mechanism(@zocket)
+        MECHANISMS[code] or
+          raise "unknown ZMQ security mechanism code: %i" % code
+      end
+
+      # @return [String] Z85 encoded secret key set
+      # @return [nil] if the current mechanism isn't CURVE or CURVE isn't
+      #   supported
+      def CURVE_secretkey
+        CURVE_key(:curve_secretkey)
+      end
+
+      # @return [String] Z85 encoded public key set
+      # @return [nil] if the current mechanism isn't CURVE or CURVE isn't
+      #   supported
+      def CURVE_publickey
+        CURVE_key(:curve_publickey)
+      end
+
+      # Gets the ZAP domain used for authentication.
+      # @see http://rfc.zeromq.org/spec:27
+      # @return [String]
+      def zap_domain
+        Zsock.zap_domain(@zocket).read_string
+      end
+      # Sets the ZAP domain used for authentication.
+      # @param domain [String] the new ZAP domain
+      def zap_domain=(domain)
+        raise ArgumentError, "domain too long" if domain.bytesize > 254
+        Zsock.set_zap_domain(@zocket, domain)
+      end
+
+      # @return [Boolean] whether this zocket is a PLAIN server
+      def PLAIN_server?() Zsock.plain_server(@zocket) > 0 end
+
+      # Make this zocket a PLAIN server.
+      # @param bool [Boolean]
+      # @note You'll have to use a {CZTop::Authenticator}.
+      def PLAIN_server=(bool)
+        Zsock.set_plain_server(@zocket, bool ? 1 : 0)
+      end
+
+      # @return [String] username set for PLAIN mechanism
+      # @return [nil] if the current mechanism isn't PLAIN
+      def PLAIN_username
+        return nil if mechanism != :PLAIN
+        Zsock.plain_username(@zocket).read_string
+      end
+      # @param username [String] username for PLAIN mechanism
+      # @note You'll have to use a {CZTop::Authenticator}.
+      def PLAIN_username=(username)
+        Zsock.set_plain_username(@zocket, username)
+      end
+      # @return [String] password set for PLAIN mechanism
+      # @return [nil] if the current mechanism isn't PLAIN
+      def PLAIN_password
+        return nil if mechanism != :PLAIN
+        Zsock.plain_password(@zocket).read_string
+      end
+      # @param password [String] password for PLAIN mechanism
+      def PLAIN_password=(password)
+        Zsock.set_plain_password(@zocket, password)
+      end
+
+      # @!endgroup
+
+      # @!group Send and Receive Timeouts
+
+      # @return [Integer] the timeout when receiving a message
+      # @see Message.receive_from
+      def rcvtimeo() Zsock.rcvtimeo(@zocket) end
+      # @param timeout [Integer] new timeout
+      # @see Message.receive_from
+      def rcvtimeo=(timeout) Zsock.set_rcvtimeo(@zocket, timeout) end
+
+      # @return [Integer] the timeout when sending a message
+      # @see Message#send_to
+      def sndtimeo() Zsock.sndtimeo(@zocket) end
+      # @param timeout [Integer] new timeout
+      # @see Message#send_to
+      def sndtimeo=(timeout) Zsock.set_sndtimeo(@zocket, timeout) end
+
+      # @!endgroup
+
+      # Accept only routable messages on ROUTER sockets. Default is off.
+      # @param bool [Boolean] whether to error if a message isn't routable
+      #   (either if the that peer isn't connected or its SNDHWM is reached)
+      def router_mandatory=(bool)
+        Zsock.set_router_mandatory(@zocket, bool ? 1 : 0)
+      end
+
+      # @return [String] current socket identity
+      def identity() Zsock.identity(@zocket).read_string end
+      # @param identity [String] new socket identity
+      def identity=(identity) Zsock.set_identity(@zocket, identity) end
+
+      # @return [Integer] current value of Type of Service
+      def tos() Zsock.tos(@zocket) end
+      # @param new_value [Integer] new value for Type of Service
+      def tos=(new_value)
+        raise ArgumentError, "invalid TOS" unless new_value >= 0
+        Zsock.set_tos(@zocket, new_value)
+      end
+
+      # @return [Integer] current value of Heartbeat IVL
+      def heartbeat_ivl() Zsock.heartbeat_ivl(@zocket) end
+      # @param new_value [Integer] new value for Heartbeat IVL
+      def heartbeat_ivl=(new_value)
+        raise ArgumentError, "invalid IVL" unless new_value >= 0
+        Zsock.set_heartbeat_ivl(@zocket, new_value)
+      end
+
+      # @return [Integer] current value of Heartbeat TTL, in milliseconds
+      def heartbeat_ttl() Zsock.heartbeat_ttl(@zocket) end
+      # @param new_value [Integer] new value for Heartbeat TTL, in
+      #   milliseconds
+      # @note The value will internally be rounded to the nearest decisecond.
+      #   So a value of less than 100 will have no effect.
+      def heartbeat_ttl=(new_value)
+        unless new_value.is_a? Integer
+          raise ArgumentError, "invalid TTL: #{new_value}"
+        end
+        unless (0..65536).include? new_value
+          raise ArgumentError, "TTL out of range: #{new_value}"
+        end
+        Zsock.set_heartbeat_ttl(@zocket, new_value)
+      end
+
+      # @return [Integer] current value of Heartbeat Timeout
+      def heartbeat_timeout() Zsock.heartbeat_timeout(@zocket) end
+      # @param new_value [Integer] new value for Heartbeat Timeout
+      def heartbeat_timeout=(new_value)
+        raise ArgumentError, "invalid timeout" unless new_value >= 0
+        Zsock.set_heartbeat_timeout(@zocket, new_value)
+      end
+
+      # @return [Integer] current value of LINGER
+      def linger() Zsock.linger(@zocket) end
+      # This defines the number of milliseconds to wait while
+      # closing/disconnecting a socket if there are outstanding messages to
+      # send.
+      #
+      # Default is 0, which means to not wait at all. -1 means to wait
+      # indefinitely
+      #
+      # @param new_value [Integer] new value for LINGER
+      def linger=(new_value)
+        Zsock.set_linger(@zocket, new_value)
+      end
+
+# TODO: a reasonable subset of these
+#//  Get socket options
+#int zsock_gssapi_server (void *self);
+#int zsock_gssapi_plaintext (void *self);
+#char * zsock_gssapi_principal (void *self);
+#char * zsock_gssapi_service_principal (void *self);
+#int zsock_ipv6 (void *self);
+#int zsock_immediate (void *self);
+#int zsock_type (void *self);
+#int zsock_affinity (void *self);
+#int zsock_rate (void *self);
+#int zsock_recovery_ivl (void *self);
+#int zsock_sndbuf (void *self);
+#int zsock_rcvbuf (void *self);
+#int zsock_reconnect_ivl (void *self);
+#int zsock_reconnect_ivl_max (void *self);
+#int zsock_backlog (void *self);
+#int zsock_maxmsgsize (void *self);
+#int zsock_multicast_hops (void *self);
+#int zsock_tcp_keepalive (void *self);
+#int zsock_tcp_keepalive_idle (void *self);
+#int zsock_tcp_keepalive_cnt (void *self);
+#int zsock_tcp_keepalive_intvl (void *self);
+#int zsock_rcvmore (void *self);
+#SOCKET zsock_fd (void *self);
+#int zsock_events (void *self);
+#char * zsock_last_endpoint (void *self);
+#
+#//  Set socket options
+#void zsock_set_router_handover (void *self, int router_handover);
+#void zsock_set_probe_router (void *self, int probe_router);
+#void zsock_set_req_relaxed (void *self, int req_relaxed);
+#void zsock_set_req_correlate (void *self, int req_correlate);
+#void zsock_set_conflate (void *self, int conflate);
+#void zsock_set_gssapi_server (void *self, int gssapi_server);
+#void zsock_set_gssapi_plaintext (void *self, int gssapi_plaintext);
+#void zsock_set_gssapi_principal (void *self, const char * gssapi_principal);
+#void zsock_set_gssapi_service_principal (void *self, const char * gssapi_service_principal);
+#void zsock_set_ipv6 (void *self, int ipv6);
+#void zsock_set_immediate (void *self, int immediate);
+#void zsock_set_delay_attach_on_connect (void *self, int delay_attach_on_connect);
+#void zsock_set_affinity (void *self, int affinity);
+#void zsock_set_rate (void *self, int rate);
+#void zsock_set_recovery_ivl (void *self, int recovery_ivl);
+#void zsock_set_sndbuf (void *self, int sndbuf);
+#void zsock_set_rcvbuf (void *self, int rcvbuf);
+#void zsock_set_reconnect_ivl (void *self, int reconnect_ivl);
+#void zsock_set_reconnect_ivl_max (void *self, int reconnect_ivl_max);
+#void zsock_set_backlog (void *self, int backlog);
+#void zsock_set_maxmsgsize (void *self, int maxmsgsize);
+#void zsock_set_multicast_hops (void *self, int multicast_hops);
+#void zsock_set_xpub_verbose (void *self, int xpub_verbose);
+#void zsock_set_tcp_keepalive (void *self, int tcp_keepalive);
+#void zsock_set_tcp_keepalive_idle (void *self, int tcp_keepalive_idle);
+#void zsock_set_tcp_keepalive_cnt (void *self, int tcp_keepalive_cnt);
+#void zsock_set_tcp_keepalive_intvl (void *self, int tcp_keepalive_intvl);
+    end
+  end
+end

data/lib/cztop.rb

@@ -0,0 +1,55 @@
+require 'czmq-ffi-gen'
+require_relative 'cztop/version'
+
+# CZTop tries to provide a complete CZMQ binding with a nice, Ruby-like API.
+module CZTop
+end
+
+# modules
+require_relative 'cztop/has_ffi_delegate'
+require_relative 'cztop/zsock_options'
+require_relative 'cztop/send_receive_methods'
+require_relative 'cztop/polymorphic_zsock_methods'
+
+# CZMQ classes
+require_relative 'cztop/actor'
+require_relative 'cztop/authenticator'
+require_relative 'cztop/beacon'
+require_relative 'cztop/certificate'
+require_relative 'cztop/config'
+require_relative 'cztop/frame'
+require_relative 'cztop/message'
+require_relative 'cztop/monitor'
+require_relative 'cztop/poller'
+require_relative 'cztop/proxy'
+require_relative 'cztop/socket'
+require_relative 'cztop/z85'
+
+# additional
+require_relative 'cztop/config/comments'
+require_relative 'cztop/config/traversing'
+require_relative 'cztop/config/serialization'
+require_relative 'cztop/message/frames'
+require_relative 'cztop/socket/types'
+
+
+# make Ctrl-C work in case a low-level call hangs
+CZMQ::FFI::Signals.disable_default_handling
+
+##
+# Probably useless in this Ruby binding:
+#
+#  * CertificateStore
+#  * UUID
+#  * Dir
+#  * DirPatch
+#  * File
+#  * HashX
+#  * String
+#  * Trie
+#  * Hash
+#  * List
+
+# Implemented before, but removed because useless:
+#
+#  * Loop

data/perf/README.md

@@ -0,0 +1,79 @@
+# Performance Measurement
+
+This directory contains simple performance measurement utilities:
+
+- `inproc_lat.rb` measures the latency of the inproc transport
+- `inproc_thr.rb` measures the throughput of the inproc transport
+- `local_lat.rb` and `remote_lat.rb` measure the latency other transports
+- `local_thr.rb` and `remote_thr.rb` measure the throughput other transports
+
+## Example Output
+
+On my laptop, it currently looks something like this:
+
+### Latency
+
+over inproc, using 10k roundtrips of a repeatedly allocated 1kb message:
+```
+$ ./inproc_lat_reqrep.rb 1_000 10_000
+message size: 1000 [B]
+roundtrip count: 10000
+elapsed time: 0.469 [s]
+average latency: 23.439 [us]<Paste>
+```
+
+over IPC, using 10k roundtrips of a repeatedly allocated 1kb message:
+```
+$ ./local_lat.rb ipc:///tmp/cztop-perf 1000 1000 & ./remote_lat.rb ipc:///tmp/cztop-perf 1000 1000
+[3] 58043
+message size: 1000 [B]
+roundtrip count: 1000
+elapsed time: 0.091 [s]
+average latency: 45.482 [us]
+[3]    58043 done       ./local_lat.rb ipc:///tmp/cztop-perf 1000 1000
+```
+
+over local TCP/IP stack, using 10k roundtrips of a repeatedly allocated
+1kb message:
+```
+[3] 58064
+message size: 1000 [B]
+roundtrip count: 1000
+elapsed time: 0.123 [s]
+average latency: 61.434 [us]
+[3]    58064 done       ./local_lat.rb tcp://127.0.0.1:55667 1000 1000
+```
+
+### Throughput
+
+over inproc, with message sizes from 100 bytes to 100kb, 10,000 each:
+
+```
+$ ./inproc_thru.rb 100 10_000
+message size: 100 [B]
+message count: 10000
+elapsed time: 0.270 [s]
+mean throughput: 37093 [msg/s]
+mean throughput: 29.674 [Mb/s]
+
+$ ./inproc_thru.rb 1_000 10_000
+message size: 1000 [B]
+message count: 10000
+elapsed time: 0.260 [s]
+mean throughput: 38498 [msg/s]
+mean throughput: 307.987 [Mb/s]
+
+$ ./inproc_thru.rb 10_000 10_000
+message size: 10000 [B]
+message count: 10000
+elapsed time: 0.317 [s]
+mean throughput: 31501 [msg/s]
+mean throughput: 2520.102 [Mb/s]
+
+$ ./inproc_thru.rb 100_000 10_000
+message size: 100000 [B]
+message count: 10000
+elapsed time: 0.906 [s]
+mean throughput: 11034 [msg/s]
+mean throughput: 8827.440 [Mb/s]
+```

data/perf/inproc_lat.rb

@@ -0,0 +1,49 @@
+#! /usr/bin/env ruby
+require_relative "../lib/cztop"
+require "benchmark"
+#require "ruby-prof"
+
+if ARGV.size != 2
+  abort <<MSG
+Usage: #{$0} <message-size> <roundtrip-count>
+MSG
+end
+
+MSG_SIZE = Integer(ARGV[0]) # bytes
+ROUNDTRIP_COUNT = Integer(ARGV[1]) # round trips
+MSG = "X" * MSG_SIZE
+
+Thread.new do
+  s = CZTop::Socket::PAIR.new("@inproc://perf")
+  s.signal
+  ROUNDTRIP_COUNT.times do
+    msg = s.receive
+    raise "wrong message size" if msg.content_size != MSG_SIZE
+    s << msg
+  end
+end
+
+s = CZTop::Socket::PAIR.new(">inproc://perf")
+s.wait
+
+#RubyProf.start
+tms = Benchmark.measure do
+  ROUNDTRIP_COUNT.times do
+    s << MSG
+    msg = s.receive
+    raise "wrong message size" if msg.content_size != MSG_SIZE
+  end
+end
+#rubyprof_result = RubyProf.stop
+
+elapsed = tms.real
+latency = elapsed / (ROUNDTRIP_COUNT * 2) * 1_000_000
+puts "message size: #{MSG_SIZE} [B]"
+puts "roundtrip count: #{ROUNDTRIP_COUNT}"
+puts "elapsed time: %.3f [s]" % elapsed
+puts "average latency: %.3f [us]" % latency
+
+# print a flat profile to text
+#printer = RubyProf::FlatPrinter.new(rubyprof_result)
+#printer.print(STDOUT)
+

data/perf/inproc_thru.rb

@@ -0,0 +1,42 @@
+#! /usr/bin/env ruby
+require_relative "../lib/cztop"
+require "benchmark"
+
+if ARGV.size != 2
+  abort <<MSG
+Usage: #{$0} <message-size> <message-count>
+MSG
+end
+
+MSG_SIZE = Integer(ARGV[0]) # bytes
+MSG_COUNT = Integer(ARGV[1]) # number of messages
+MSG = "X" * MSG_SIZE
+
+Thread.new do
+  s = CZTop::Socket::PAIR.new("@inproc://perf")
+  s.signal
+  MSG_COUNT.times do
+    msg = s.receive
+    raise "wrong message size" if msg.content_size != MSG_SIZE
+  end
+end
+
+s = CZTop::Socket::PAIR.new(">inproc://perf")
+s.wait
+
+tms = Benchmark.measure do
+  MSG_COUNT.times do
+    s << MSG
+  end
+end
+
+elapsed = tms.real
+
+throughput = MSG_COUNT / elapsed
+megabits = (throughput * MSG_SIZE * 8) / 1_000_000
+
+puts "message size: #{MSG_SIZE} [B]"
+puts "message count: #{MSG_COUNT}"
+puts "elapsed time: %.3f [s]" % elapsed
+puts "mean throughput: %d [msg/s]" % throughput
+puts "mean throughput: %.3f [Mb/s]" % megabits

data/perf/local_lat.rb

@@ -0,0 +1,35 @@
+#! /usr/bin/env ruby
+require_relative "../lib/cztop"
+require "benchmark"
+
+if ARGV.size != 3
+  abort <<MSG
+Usage: #{$0} <bind-to> <message-size> <roundtrip-count>
+MSG
+end
+
+ENDPOINT = ARGV[0]
+MSG_SIZE = Integer(ARGV[1]) # bytes
+ROUNDTRIP_COUNT = Integer(ARGV[2]) # round trips
+MSG = "X" * MSG_SIZE
+
+s = CZTop::Socket::REP.new(ENDPOINT)
+
+# synchronize
+s.wait
+s.signal
+
+tms = Benchmark.measure do
+  ROUNDTRIP_COUNT.times do
+    msg = s.receive
+    raise "wrong message size" if msg.content_size != MSG_SIZE
+    s << msg
+  end
+end
+
+elapsed = tms.real
+latency = elapsed / (ROUNDTRIP_COUNT * 2) * 1_000_000
+puts "message size: #{MSG_SIZE} [B]"
+puts "roundtrip count: #{ROUNDTRIP_COUNT}"
+puts "elapsed time: %.3f [s]" % elapsed
+puts "average latency: %.3f [us]" % latency

data/perf/remote_lat.rb

@@ -0,0 +1,26 @@
+#! /usr/bin/env ruby
+require_relative "../lib/cztop"
+require "benchmark"
+
+if ARGV.size != 3
+  abort <<MSG
+Usage: #{$0} <connect-to> <message-size> <roundtrip-count>
+MSG
+end
+
+ENDPOINT = ARGV[0]
+MSG_SIZE = Integer(ARGV[1]) # bytes
+ROUNDTRIP_COUNT = Integer(ARGV[2]) # round trips
+MSG = "X" * MSG_SIZE
+
+s = CZTop::Socket::REQ.new(ENDPOINT)
+
+# synchronize
+s.signal
+s.wait
+
+ROUNDTRIP_COUNT.times do
+  s << MSG
+  msg = s.receive
+  raise "wrong message size" if msg.content_size != MSG_SIZE
+end