cztop 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 117c17b6787d700550999d0302f299aebc833902
-  data.tar.gz: 1b81e1fb89f114c51d9646e439d606083cd6b446
+  metadata.gz: c4906ff9fd7c2ebd3fb3b33eadcab389799649ff
+  data.tar.gz: 0332b4b9a1fed07870e459298ca43fb82223acd8
 SHA512:
-  metadata.gz: 07ed4e2fa8914018dfa2806c1df8bd10b4ba610348e96c79500edc811311fc2b4d58841cf9b5cac7d7d30d9a91219acf58f86f595fee493e4e6e02332fb6f38e
-  data.tar.gz: b867d2966b91bc2b371f1a61386cb0d0899047e415f9753119852a55047c9c103da1acd302af8a5ae7efaa38c18a3dc66cb6fdc75df9d05b1152c547118fe6d3
+  metadata.gz: 8727db3d61b640eb5a2e0611086d180f6515418d7fd4ecebd6ff6fd76e15f82fb10116e2420121c4dc8279bf11b426604228971d03d646f244d8886735475db7
+  data.tar.gz: 838b219829c9df9f8fc04081d3e262360bda1cf02f5c5d7e8881c2593e4aa7921a1ecaea54fd0e344a091d0cc5e1338267375ab6758ab1eb60b652fc4db2bfd5

data/.travis.yml

@@ -12,6 +12,7 @@ rvm:
 env:
   # recognized by czmq-ffi-gen's ci-scripts
   - CZMQ_VERSION=HEAD ZMQ_VERSION=HEAD
+  - CZMQ_VERSION=stable ZMQ_VERSION=stable
 matrix:
   allow_failures:
     - rvm: rbx

data/CHANGES.md

@@ -1,3 +1,10 @@
+0.11.0 (11/06/2016)
+-----
+* upgrade to czmq-ffi-gen's 0.12.x line (which includes the CZMQ v4.0.0 release)
+* add support for RADIO/DISH and SCATTER/GATHER sockets
+* add CZTop::Frame#group and #group= methods
+* add CZTop::Metadata to encode/decode ZMTP metadata
+
 0.10.0 (10/24/2016)
 -----
 * add Socket#readable? and #writable?

data/README.md

@@ -6,6 +6,10 @@ FFI binding of [CZMQ](https://github.com/zeromq/czmq) and has a focus on being
 easy to use for Rubyists (POLS) and providing first class support for security
 mechanisms (like CURVE).
 
+You might wanna check out
+[cztop-patterns](https://github.com/paddor/cztop-patterns). It's still very
+new, but will contain some reusable patterns described in the Zguide.
+
 [![Build Status on Travis CI](https://travis-ci.org/paddor/cztop.svg?branch=master)](https://travis-ci.org/paddor/cztop?branch=master)
 [![Code Climate](https://codeclimate.com/repos/56677a7849f50a141c001784/badges/48f3cca3c62df9e4b17b/gpa.svg)](https://codeclimate.com/repos/56677a7849f50a141c001784/feed)
 [![Inline docs](http://inch-ci.org/github/paddor/cztop.svg?branch=master&style=shields)](http://inch-ci.org/github/paddor/cztop)
@@ -44,9 +48,11 @@ Here's an overview of the core classes:
   * [Frame](http://www.rubydoc.info/gems/cztop/CZTop/Frame)
   * [Message](http://www.rubydoc.info/gems/cztop/CZTop/Message)
   * [Monitor](http://www.rubydoc.info/gems/cztop/CZTop/Monitor) < Actor
+  * [Metadata](http://www.rubydoc.info/gems/cztop/CZTop/Metadata)
   * [Proxy](http://www.rubydoc.info/gems/cztop/CZTop/Proxy) < Actor
-  * [Poller](http://www.rubydoc.info/gems/cztop/CZTop/Poller)
+  * [Poller](http://www.rubydoc.info/gems/cztop/CZTop/Poller) (based on `zmq_poller_*()` functions)
     * [Aggregated](http://www.rubydoc.info/gems/cztop/CZTop/Poller/Aggregated)
+    * [ZPoller](http://www.rubydoc.info/gems/cztop/CZTop/Poller/ZPoller)
   * [Socket](http://www.rubydoc.info/gems/cztop/CZTop/Socket)
     * [REQ](http://www.rubydoc.info/gems/cztop/CZTop/Socket/REQ) < Socket
     * [REP](http://www.rubydoc.info/gems/cztop/CZTop/Socket/REP) < Socket
@@ -62,6 +68,10 @@ Here's an overview of the core classes:
     * [STREAM](http://www.rubydoc.info/gems/cztop/CZTop/Socket/STREAM) < Socket
     * [CLIENT](http://www.rubydoc.info/gems/cztop/CZTop/Socket/CLIENT) < Socket
     * [SERVER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/SERVER) < Socket
+    * [RADIO](http://www.rubydoc.info/gems/cztop/CZTop/Socket/RADIO) < Socket
+    * [DISH](http://www.rubydoc.info/gems/cztop/CZTop/Socket/DISH) < Socket
+    * [SCATTER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/SCATTER) < Socket
+    * [GATHER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/GATHER) < Socket
   * [Z85](http://www.rubydoc.info/gems/cztop/CZTop/Z85)
     * [Padded](http://www.rubydoc.info/gems/cztop/CZTop/Z85/Padded) < Z85
     * [Pipe](http://www.rubydoc.info/gems/cztop/CZTop/Z85/Pipe)
@@ -88,11 +98,12 @@ More information in the [API documentation](http://www.rubydoc.info/github/paddo
   * no need to manually pass some constant
     * but you can: `CZTop::Socket.new_by_type(:REP)`
   * e.g. `#subscribe` only exists on CZTop::Socket::SUB
-* SERVER and CLIENT ready
-  * see CZTop::Socket::SERVER and CZTop::Socket::CLIENT
-  * there are `#routing_id` and `#routing_id=` on the following classes:
+* DRAFT API ready
+  * CLIENT/SERVER/RADIO/DISH/SCATTER/GATHER and other DRAFT methods are supported if the libraries (ZMQ/CZMQ) have been compiled with DRAFT APIs enabled (`--enable-drafts`)
+  * there is `#routing_id` and `#routing_id=` on the following classes:
     * CZTop::Message
     * CZTop::Frame
+  * there is `#group` and `#group=` on CZTop::Frame
 * ZMTP 3.1 heartbeat ready
   * `socket.options.heartbeat_ivl = 2000`
   * `socket.options.heartbeat_timeout = 8000`
@@ -101,12 +112,11 @@ More information in the [API documentation](http://www.rubydoc.info/github/paddo
 
 You'll need:
 
-* CZMQ > 3.0.2 (currently built from master)
-* ZMQ >= 4.2 (currently built from master)
-
-For security mechanisms like CURVE, you'll need:
+* CZMQ >= 4.0.0
+* ZMQ >= 4.2.0
 
-* [libsodium](https://github.com/jedisct1/libsodium)
+For security mechanisms like CURVE, it's recommended to use Libsodium. However,
+ZMQ can be compiled with tweetnacl enabled.
 
 To install on OSX using homebrew, run:
 

data/ci-scripts/install-deps

@@ -4,6 +4,5 @@ mkdir -p vendor
 cd vendor
 git clone --depth 1 https://github.com/paddor/czmq-ffi-gen
 cd czmq-ffi-gen
-ci-scripts/install-libsodium
 ci-scripts/install-libzmq
 ci-scripts/install-libczmq

data/cztop.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "czmq-ffi-gen", "~> 0.10.0"
+  spec.add_runtime_dependency "czmq-ffi-gen", "~> 0.12.0"
 
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"

data/lib/cztop/frame.rb

@@ -137,13 +137,13 @@ module CZTop
     ffi_delegate :size
 
     # Gets the routing ID.
-    # @note This only set when the frame came from a {CZTop::Socket::SERVER}
-    #   socket.
+    # @note This only set when the frame has been read from
+    #   a {CZTop::Socket::SERVER} socket.
     # @return [Integer] the routing ID, or 0 if unset
     ffi_delegate :routing_id
 
     # Sets a new routing ID.
-    # @note This is used when the frame is sent to a {CZTop::Socket::SERVER}
+    # @note This is used when the frame is sent via a {CZTop::Socket::CLIENT}
     #   socket.
     # @param new_routing_id [Integer] new routing ID
     # @raise [RangeError] if new routing ID is out of +uint32_t+ range
@@ -154,5 +154,27 @@ module CZTop
       raise RangeError if new_routing_id < 0
       ffi_delegate.set_routing_id(new_routing_id)
     end
+
+    # Gets the group (radio/dish pattern).
+    # @note This only set when the frame has been read from
+    #   a {CZTop::Socket::DISH} socket.
+    # @return [String] the group
+    # @return [nil] when no group has been set
+    def group
+      group = ffi_delegate.group
+      return nil if group.empty?
+      group
+    end
+
+    # Sets a new group (radio/dish pattern).
+    # @note This is used when the frame is sent via a {CZTop::Socket::RADIO}
+    #   socket.
+    # @param new_group [String] new group
+    # @raise [ArgumentError] if new group name is too long
+    # @return [new_group]
+    def group=(new_group)
+      rc = ffi_delegate.set_group(new_group)
+      raise_zmq_err("unable to set group to %p" % group) if rc == -1
+    end
   end
 end

data/lib/cztop/has_ffi_delegate.rb

@@ -15,8 +15,13 @@ module CZTop::HasFFIDelegate
   # Attaches an FFI delegate to the current (probably new) {CZTop} object.
   # @param ffi_delegate an instance of the corresponding class in the
   #   CZMQ::FFI namespace
-  # @raise [SystemCallError] if the FFI delegate's internal pointer is NULL
+  # @raise [SystemCallError, ArgumentError, ...] if the FFI delegate's
+  #   internal pointer is NULL
   # @return [void]
+  # @note This only raises the correct exception when the creation of the new
+  #   CZMQ object was the most recent thing done with the CZMQ library and
+  #   thus CZMQ::FFI::Errors.errno is still reports the correct error number.
+  # @see raise_zmq_err
   def attach_ffi_delegate(ffi_delegate)
     raise_zmq_err(CZMQ::FFI::Errors.strerror) if ffi_delegate.null?
     @ffi_delegate = ffi_delegate

data/lib/cztop/metadata.rb

@@ -0,0 +1,89 @@
+module CZTop
+  # Useful to encode and decode metadata as defined by ZMTP.
+  #
+  # ABNF:
+  #
+  #   metadata = *property
+  #   property = name value
+  #   name = OCTET 1*255name-char
+  #   name-char = ALPHA | DIGIT | "-" | "_" | "." | "+"
+  #   value = 4OCTET *OCTET       ; Size in network byte order
+  #
+  # @see https://rfc.zeromq.org/spec:23/ZMTP
+  class Metadata
+    VALUE_MAXLEN = 2**31-1
+
+    # Raised when decoding malformed metadata.
+    class InvalidData < StandardError
+    end
+
+    # regular expression used to validate property names
+    NAME_REGEX = /\A[[:alnum:]_.+-]{1,255}\Z/.freeze
+
+
+    # @param metadata [Hash<Symbol, #to_s>]
+    # @return [String]
+    def self.dump(metadata)
+      ic_names = Set.new
+      metadata.map do |k, v|
+        ic_name = k.to_sym.downcase
+        if ic_names.include?(ic_name)
+          raise ArgumentError, "property #{k.inspect}: duplicate name"
+        else
+          ic_names << ic_name
+        end
+        name = k.to_s
+        if NAME_REGEX !~ name
+          raise ArgumentError, "property #{k.inspect}: invalid name"
+        end
+        value = v.to_s
+        if value.bytesize > VALUE_MAXLEN
+          raise ArgumentError, "property #{k.inspect}: value too long"
+        end
+        [name.size, name, value.bytesize, value].pack("CA*NA*")
+      end.join
+    end
+
+    # @param string [String, Frame, #to_s]
+    # @return [Hash]
+    def self.load(string)
+      properties = {}
+      io = StringIO.new(string)
+      until io.eof?
+        # check for zero length names
+        name_length = io.read(1).unpack("C").first
+        raise InvalidData, "zero-length property name" if name_length.zero?
+        name = io.read(name_length)
+        name_sym = name.to_sym.downcase
+        if properties.has_key?(name_sym)
+          raise InvalidData, "property #{name.inspect}: duplicate name"
+        end
+
+        value_length = io.read(4).unpack("N").first
+        value = io.read(value_length)
+
+        properties[name_sym] = value
+      end
+      new(properties)
+    end
+
+    # @param properties [Hash<Symbol, String>] the properties as loaded by
+    #   {load}
+    def initialize(properties)
+      @properties = properties
+    end
+
+    # Gets the value corresponding to a property name. The case of the name
+    # is insignificant.
+    # @param name [Symbol, String] the property name
+    # @return [String] the value
+    def [](name)
+      @properties[name.to_sym.downcase]
+    end
+
+    # @return [Hash<Symbol, String] all properties
+    def to_h
+      @properties
+    end
+  end
+end

data/lib/cztop/poller/aggregated.rb

@@ -0,0 +1,126 @@
+module CZTop
+  # This is a poller which is able to provide a list of readable and a list
+  # of writable sockets. This is useful for when you need to process socket
+  # events in batch, rather than one per event loop iteration.
+  #
+  # In particular, this is needed in Celluloid::ZMQ, where in a call to
+  # Celluloid::ZMQ::Reactor#run_once all readable/writable sockets need to
+  # be processed.
+  #
+  # = Implementation
+  #
+  # It wraps a {CZTop::Poller} and just does the following to support
+  # getting an array of readable/writable sockets:
+  #
+  # * in {#wait}, poll with given timeout
+  # * in case there was an event:
+  #   * deregister the corresponding event(s) on the registered socket
+  #   * poll again with zero timeout until no more sockets
+  #   * repeat and accumulate results into two lists
+  #
+  # = Forwarded Methods
+  #
+  # The following methods are defined on this class too, and calls are
+  # forwarded directly to the actual {CZTop::Poller} instance:
+  #
+  # * {CZTop::Poller#add}
+  # * {CZTop::Poller#add_reader}
+  # * {CZTop::Poller#add_writer}
+  # * {CZTop::Poller#modify}
+  # * {CZTop::Poller#remove}
+  # * {CZTop::Poller#remove_reader}
+  # * {CZTop::Poller#remove_writer}
+  # * {CZTop::Poller#sockets}
+  #
+  class Poller::Aggregated
+
+    # @return [CZTop::Poller.new] the associated (regular) poller
+    attr_reader :poller
+
+    # @return [Array<CZTop::Socket>] readable sockets
+    attr_reader :readables
+
+    # @return [Array<CZTop::Socket>] writable sockets
+    attr_reader :writables
+
+    extend Forwardable
+    def_delegators :@poller,
+      :add,
+      :add_reader,
+      :add_writer,
+      :modify,
+      :remove,
+      :remove_reader,
+      :remove_writer,
+      :sockets
+
+    # Initializes the aggregated poller.
+    # @param poller [CZTop::Poller] the wrapped poller
+    def initialize(poller = CZTop::Poller.new)
+      @readables = []
+      @writables = []
+      @poller = poller
+    end
+
+    # Forgets all previous event information (which sockets are
+    # readable/writable) and waits for events anew. After getting the first
+    # event, {CZTop::Poller#wait} is called again with a zero-timeout to get
+    # all pending events to extract them into the aggregated lists of
+    # readable and writable sockets.
+    #
+    # For every event, the corresponding event mask flag is disabled for the
+    # associated socket, so it won't turn up again. Finally, all event masks
+    # are restored to what they were before the call to this method.
+    #
+    # @param timeout [Integer] how long to wait in ms, or 0 to avoid blocking,
+    #   or -1 to wait indefinitely
+    # @return [Boolean] whether there have been any events
+    def wait(timeout = -1)
+      @readables = []
+      @writables = []
+      @event_masks = {}
+
+      if event = @poller.wait(timeout)
+        extract(event)
+
+        # get all other pending events, if any, but no more blocking
+        while event = @poller.wait(0)
+          extract(event)
+        end
+
+        restore_event_masks
+        return true
+      end
+      return false
+    end
+
+    private
+
+    # Extracts the event information, adds the socket to the correct list(s)
+    # and modifies the socket's event mask for the socket to not turn up
+    # again during the next call(s) to {CZTop::Poller#wait} within {#wait}.
+    #
+    # @param event [CZTop::Poller::Event]
+    # @return [void]
+    def extract(event)
+      event_mask = poller.event_mask_for_socket(event.socket)
+      @event_masks[event.socket] = event_mask
+      if event.readable?
+        @readables << event.socket
+        event_mask &= 0xFFFF ^ CZTop::Poller::ZMQ::POLLIN
+      end
+      if event.writable?
+        @writables << event.socket
+        event_mask &= 0xFFFF ^ CZTop::Poller::ZMQ::POLLOUT
+      end
+      poller.modify(event.socket, event_mask)
+    end
+
+    # Restores the event mask for all registered sockets to the state they
+    # were before the call to {#wait}.
+    # @return [void]
+    def restore_event_masks
+      @event_masks.each { |socket, mask| poller.modify(socket, mask) }
+    end
+  end
+end

data/lib/cztop/poller/zmq.rb

@@ -0,0 +1,78 @@
+module CZTop
+
+  # CZTop's interface to the low-level +zmq_poller_*()+ functions.
+  module Poller::ZMQ
+
+    POLLIN  = 1
+    POLLOUT = 2
+    POLLERR = 4
+
+    extend ::FFI::Library
+    lib_name = 'libzmq'
+    lib_paths = ['/usr/local/lib', '/opt/local/lib', '/usr/lib64']
+      .map { |path| "#{path}/#{lib_name}.#{::FFI::Platform::LIBSUFFIX}" }
+    ffi_lib lib_paths + [lib_name]
+
+    # This represents a +zmq_poller_event_t+ as in:
+    #
+    #   typedef struct zmq_poller_event_t
+    #   {
+    #       void *socket;
+    #       int fd;
+    #       void *user_data;
+    #       short events;
+    #   } zmq_poller_event_t;
+    class PollerEvent < FFI::Struct
+      layout :socket, :pointer,
+             :fd, :int,
+             :user_data, :pointer,
+             :events, :short
+
+      # @return [Boolean] whether the socket is readable
+      def readable?
+        (self[:events] & POLLIN) > 0
+      end
+
+      # @return [Boolean] whether the socket is writable
+      def writable?
+        (self[:events] & POLLOUT) > 0
+      end
+    end
+
+#ZMQ_EXPORT void *zmq_poller_new (void);
+#ZMQ_EXPORT int  zmq_poller_destroy (void **poller_p);
+#ZMQ_EXPORT int  zmq_poller_add (void *poller, void *socket, void *user_data, short events);
+#ZMQ_EXPORT int  zmq_poller_modify (void *poller, void *socket, short events);
+#ZMQ_EXPORT int  zmq_poller_remove (void *poller, void *socket);
+#ZMQ_EXPORT int  zmq_poller_wait (void *poller, zmq_poller_event_t *event, long timeout);
+
+    # Gracefully attaches a function. If it's not available, this creates
+    # a placeholder class method which, when called, simply raises
+    # NotImplementedError with a helpful message.
+    def self.attach_function(function_nickname, function_name, *args)
+      super
+    rescue ::FFI::NotFoundError
+      if $VERBOSE || $DEBUG
+        warn "CZTop: The ZMQ function #{function_name}() is not available. Don't use CZTop::Poller."
+      end
+      define_singleton_method(function_nickname) do |*|
+        raise NotImplementedError, "compile ZMQ with --enable-drafts"
+      end
+    end
+
+    opts = {
+      blocking: true  # only necessary on MRI to deal with the GIL.
+    }
+    attach_function :poller_new, :zmq_poller_new, [], :pointer, **opts
+    attach_function :poller_destroy, :zmq_poller_destroy,
+      [:pointer], :int, **opts
+    attach_function :poller_add, :zmq_poller_add,
+      [:pointer, :pointer, :pointer, :short], :int, **opts
+    attach_function :poller_modify, :zmq_poller_modify,
+      [:pointer, :pointer, :short], :int, **opts
+    attach_function :poller_remove, :zmq_poller_remove,
+      [:pointer, :pointer], :int, **opts
+    attach_function :poller_wait, :zmq_poller_wait,
+      [:pointer, :pointer, :long], :int, **opts
+  end
+end

data/lib/cztop/poller/zpoller.rb

@@ -0,0 +1,113 @@
+module CZTop
+  # This is the trivial poller based on zpoller. It only supports polling
+  # for readability, but it also supports doing that on CLIENT/SERVER sockets,
+  # which is useful for {CZTop::Poller}.
+  #
+  # @see http://api.zeromq.org/czmq3-0:zpoller
+  class Poller::ZPoller
+    include HasFFIDelegate
+    extend CZTop::HasFFIDelegate::ClassMethods
+    include ::CZMQ::FFI
+
+    # Initializes the Poller. At least one reader has to be given.
+    # @param reader [Socket, Actor] socket to poll for input
+    # @param readers [Socket, Actor] any additional sockets to poll for input
+    def initialize(reader, *readers)
+      @sockets = {} # to keep references and return same instances
+      ptr = Zpoller.new(reader,
+                        *readers.flat_map {|r| [ :pointer, r ] },
+                        :pointer, nil)
+      attach_ffi_delegate(ptr)
+      remember_socket(reader)
+      readers.each { |r| remember_socket(r) }
+    end
+
+    # Adds another reader socket to the poller.
+    # @param reader [Socket, Actor] socket to poll for input
+    # @return [void]
+    # @raise [SystemCallError] if this fails
+    def add(reader)
+      rc = ffi_delegate.add(reader)
+      raise_zmq_err("unable to add socket %p" % reader) if rc == -1
+      remember_socket(reader)
+    end
+
+    # Removes a reader socket from the poller.
+    # @param reader [Socket, Actor] socket to remove
+    # @return [void]
+    # @raise [ArgumentError] if socket was invalid, e.g. it wasn't registered
+    #   in this poller
+    # @raise [SystemCallError] if this fails for another reason
+    def remove(reader)
+      rc = ffi_delegate.remove(reader)
+      raise_zmq_err("unable to remove socket %p" % reader) if rc == -1
+      forget_socket(reader)
+    end
+
+    # Waits and returns the first socket that becomes readable.
+    # @param timeout [Integer] how long to wait in ms, or 0 to avoid
+    #   blocking, or -1 to wait indefinitely
+    # @return [Socket, Actor] first socket of interest
+    # @return [nil] if the timeout expired or
+    # @raise [Interrupt] if the timeout expired or
+    def wait(timeout = -1)
+      ptr = ffi_delegate.wait(timeout)
+      if ptr.null?
+        raise Interrupt if ffi_delegate.terminated
+        return nil
+      end
+      return socket_by_ptr(ptr)
+    end
+
+    # Tells the zpoller to ignore interrupts. By default, {#wait} will return
+    # immediately if it detects an interrupt (when +zsys_interrupted+ is set
+    # to something other than zero). Calling this method will supress this
+    # behavior.
+    # @return [void]
+    def ignore_interrupts
+      ffi_delegate.ignore_interrupts
+    end
+
+    # By default the poller stops if the process receives a SIGINT or SIGTERM
+    # signal. This makes it impossible to shut-down message based architectures
+    # like zactors. This method lets you switch off break handling. The default
+    # nonstop setting is off (false).
+    #
+    # Setting this will cause {#wait} to never raise.
+    #
+    # @param flag [Boolean] whether the poller should run nonstop
+    def nonstop=(flag)
+      ffi_delegate.set_nonstop(flag)
+    end
+
+    private
+
+    # Remembers the socket so a call to {#wait} can return with the exact same
+    # instance of {Socket}, and it also makes sure the socket won't get
+    # GC'd.
+    # @param socket [Socket, Actor] the socket instance to remember
+    # @return [void]
+    def remember_socket(socket)
+      @sockets[socket.to_ptr.to_i] = socket
+    end
+
+    # Forgets the socket because it has been removed from the poller.
+    # @param socket [Socket, Actor] the socket instance to forget
+    # @return [void]
+    def forget_socket(socket)
+      @sockets.delete(socket.to_ptr.to_i)
+    end
+
+    # Gets the previously remembered socket associated to the given pointer.
+    # @param ptr [FFI::Pointer] the pointer to a socket
+    # @return [Socket, Actor] the socket associated to the given pointer
+    # @raise [SystemCallError] if no socket is registered under given pointer
+    def socket_by_ptr(ptr)
+      @sockets[ptr.to_i] or
+        # NOTE: This should never happen, since #wait will return nil if
+        # +zpoller_wait+ returned NULL. But it's better to fail early in case
+        # it ever returns a wrong pointer.
+        raise_zmq_err("no socket known for pointer #{ptr.inspect}")
+    end
+  end
+end

data/lib/cztop/poller.rb

@@ -213,303 +213,4 @@ module CZTop
       end
     end
   end
-
-  # This is a poller which is able to provide a list of readable and a list
-  # of writable sockets. This is useful for when you need to process socket
-  # events in batch, rather than one per event loop iteration.
-  #
-  # In particular, this is needed in Celluloid::ZMQ, where in a call to
-  # Celluloid::ZMQ::Reactor#run_once all readable/writable sockets need to
-  # be processed.
-  #
-  # = Implementation
-  #
-  # It wraps a {CZTop::Poller} and just does the following to support
-  # getting an array of readable/writable sockets:
-  #
-  # * in {#wait}, poll with given timeout
-  # * in case there was an event:
-  #   * deregister the corresponding event(s) on the registered socket
-  #   * poll again with zero timeout until no more sockets
-  #   * repeat and accumulate results into two lists
-  #
-  # = Forwarded Methods
-  #
-  # The following methods are defined on this class too, and calls are
-  # forwarded directly to the actual {CZTop::Poller} instance:
-  #
-  # * {CZTop::Poller#add}
-  # * {CZTop::Poller#add_reader}
-  # * {CZTop::Poller#add_writer}
-  # * {CZTop::Poller#modify}
-  # * {CZTop::Poller#remove}
-  # * {CZTop::Poller#remove_reader}
-  # * {CZTop::Poller#remove_writer}
-  # * {CZTop::Poller#sockets}
-  #
-  class Poller::Aggregated
-
-    # @return [CZTop::Poller.new] the associated (regular) poller
-    attr_reader :poller
-
-    # @return [Array<CZTop::Socket>] readable sockets
-    attr_reader :readables
-
-    # @return [Array<CZTop::Socket>] writable sockets
-    attr_reader :writables
-
-    extend Forwardable
-    def_delegators :@poller,
-      :add,
-      :add_reader,
-      :add_writer,
-      :modify,
-      :remove,
-      :remove_reader,
-      :remove_writer,
-      :sockets
-
-    # Initializes the aggregated poller.
-    # @param poller [CZTop::Poller] the wrapped poller
-    def initialize(poller = CZTop::Poller.new)
-      @readables = []
-      @writables = []
-      @poller = poller
-    end
-
-    # Forgets all previous event information (which sockets are
-    # readable/writable) and waits for events anew. After getting the first
-    # event, {CZTop::Poller#wait} is called again with a zero-timeout to get
-    # all pending events to extract them into the aggregated lists of
-    # readable and writable sockets.
-    #
-    # For every event, the corresponding event mask flag is disabled for the
-    # associated socket, so it won't turn up again. Finally, all event masks
-    # are restored to what they were before the call to this method.
-    #
-    # @param timeout [Integer] how long to wait in ms, or 0 to avoid blocking,
-    #   or -1 to wait indefinitely
-    # @return [Boolean] whether there have been any events
-    def wait(timeout = -1)
-      @readables = []
-      @writables = []
-      @event_masks = {}
-
-      if event = @poller.wait(timeout)
-        extract(event)
-
-        # get all other pending events, if any, but no more blocking
-        while event = @poller.wait(0)
-          extract(event)
-        end
-
-        restore_event_masks
-        return true
-      end
-      return false
-    end
-
-    private
-
-    # Extracts the event information, adds the socket to the correct list(s)
-    # and modifies the socket's event mask for the socket to not turn up
-    # again during the next call(s) to {CZTop::Poller#wait} within {#wait}.
-    #
-    # @param event [CZTop::Poller::Event]
-    # @return [void]
-    def extract(event)
-      event_mask = poller.event_mask_for_socket(event.socket)
-      @event_masks[event.socket] = event_mask
-      if event.readable?
-        @readables << event.socket
-        event_mask &= 0xFFFF ^ CZTop::Poller::ZMQ::POLLIN
-      end
-      if event.writable?
-        @writables << event.socket
-        event_mask &= 0xFFFF ^ CZTop::Poller::ZMQ::POLLOUT
-      end
-      poller.modify(event.socket, event_mask)
-    end
-
-    # Restores the event mask for all registered sockets to the state they
-    # were before the call to {#wait}.
-    # @return [void]
-    def restore_event_masks
-      @event_masks.each { |socket, mask| poller.modify(socket, mask) }
-    end
-  end
-
-  # CZTop's interface to the low-level +zmq_poll()+ function.
-  module Poller::ZMQ
-
-    POLLIN  = 1
-    POLLOUT = 2
-    POLLERR = 4
-
-    extend ::FFI::Library
-    lib_name = 'libzmq'
-    lib_paths = ['/usr/local/lib', '/opt/local/lib', '/usr/lib64']
-      .map { |path| "#{path}/#{lib_name}.#{::FFI::Platform::LIBSUFFIX}" }
-    ffi_lib lib_paths + [lib_name]
-
-    # This represents a +zmq_poller_event_t+ as in:
-    #
-    #   typedef struct zmq_poller_event_t
-    #   {
-    #       void *socket;
-    #       int fd;
-    #       void *user_data;
-    #       short events;
-    #   } zmq_poller_event_t;
-    class PollerEvent < FFI::Struct
-      layout :socket, :pointer,
-             :fd, :int,
-             :user_data, :pointer,
-             :events, :short
-
-      # @return [Boolean] whether the socket is readable
-      def readable?
-        (self[:events] & POLLIN) > 0
-      end
-
-      # @return [Boolean] whether the socket is writable
-      def writable?
-        (self[:events] & POLLOUT) > 0
-      end
-    end
-
-#ZMQ_EXPORT void *zmq_poller_new (void);
-#ZMQ_EXPORT int  zmq_poller_destroy (void **poller_p);
-#ZMQ_EXPORT int  zmq_poller_add (void *poller, void *socket, void *user_data, short events);
-#ZMQ_EXPORT int  zmq_poller_modify (void *poller, void *socket, short events);
-#ZMQ_EXPORT int  zmq_poller_remove (void *poller, void *socket);
-#ZMQ_EXPORT int  zmq_poller_wait (void *poller, zmq_poller_event_t *event, long timeout);
-
-    opts = {
-      blocking: true  # only necessary on MRI to deal with the GIL.
-    }
-    attach_function :poller_new, :zmq_poller_new, [], :pointer, **opts
-    attach_function :poller_destroy, :zmq_poller_destroy,
-      [:pointer], :int, **opts
-    attach_function :poller_add, :zmq_poller_add,
-      [:pointer, :pointer, :pointer, :short], :int, **opts
-    attach_function :poller_modify, :zmq_poller_modify,
-      [:pointer, :pointer, :short], :int, **opts
-    attach_function :poller_remove, :zmq_poller_remove,
-      [:pointer, :pointer], :int, **opts
-    attach_function :poller_wait, :zmq_poller_wait,
-      [:pointer, :pointer, :long], :int, **opts
-  end
-
-  # This is the trivial poller based on zpoller. It only supports polling
-  # for readability, but it also supports doing that on CLIENT/SERVER sockets,
-  # which is useful for {CZTop::Poller}.
-  #
-  # @see http://api.zeromq.org/czmq3-0:zpoller
-  class Poller::ZPoller
-    include HasFFIDelegate
-    extend CZTop::HasFFIDelegate::ClassMethods
-    include ::CZMQ::FFI
-
-    # Initializes the Poller. At least one reader has to be given.
-    # @param reader [Socket, Actor] socket to poll for input
-    # @param readers [Socket, Actor] any additional sockets to poll for input
-    def initialize(reader, *readers)
-      @sockets = {} # to keep references and return same instances
-      ptr = Zpoller.new(reader,
-                        *readers.flat_map {|r| [ :pointer, r ] },
-                        :pointer, nil)
-      attach_ffi_delegate(ptr)
-      remember_socket(reader)
-      readers.each { |r| remember_socket(r) }
-    end
-
-    # Adds another reader socket to the poller.
-    # @param reader [Socket, Actor] socket to poll for input
-    # @return [void]
-    # @raise [SystemCallError] if this fails
-    def add(reader)
-      rc = ffi_delegate.add(reader)
-      raise_zmq_err("unable to add socket %p" % reader) if rc == -1
-      remember_socket(reader)
-    end
-
-    # Removes a reader socket from the poller.
-    # @param reader [Socket, Actor] socket to remove
-    # @return [void]
-    # @raise [ArgumentError] if socket was invalid, e.g. it wasn't registered
-    #   in this poller
-    # @raise [SystemCallError] if this fails for another reason
-    def remove(reader)
-      rc = ffi_delegate.remove(reader)
-      raise_zmq_err("unable to remove socket %p" % reader) if rc == -1
-      forget_socket(reader)
-    end
-
-    # Waits and returns the first socket that becomes readable.
-    # @param timeout [Integer] how long to wait in ms, or 0 to avoid
-    #   blocking, or -1 to wait indefinitely
-    # @return [Socket, Actor] first socket of interest
-    # @return [nil] if the timeout expired or
-    # @raise [Interrupt] if the timeout expired or
-    def wait(timeout = -1)
-      ptr = ffi_delegate.wait(timeout)
-      if ptr.null?
-        raise Interrupt if ffi_delegate.terminated
-        return nil
-      end
-      return socket_by_ptr(ptr)
-    end
-
-    # Tells the zpoller to ignore interrupts. By default, {#wait} will return
-    # immediately if it detects an interrupt (when +zsys_interrupted+ is set
-    # to something other than zero). Calling this method will supress this
-    # behavior.
-    # @return [void]
-    def ignore_interrupts
-      ffi_delegate.ignore_interrupts
-    end
-
-    # By default the poller stops if the process receives a SIGINT or SIGTERM
-    # signal. This makes it impossible to shut-down message based architectures
-    # like zactors. This method lets you switch off break handling. The default
-    # nonstop setting is off (false).
-    #
-    # Setting this will cause {#wait} to never raise.
-    #
-    # @param flag [Boolean] whether the poller should run nonstop
-    def nonstop=(flag)
-      ffi_delegate.set_nonstop(flag)
-    end
-
-    private
-
-    # Remembers the socket so a call to {#wait} can return with the exact same
-    # instance of {Socket}, and it also makes sure the socket won't get
-    # GC'd.
-    # @param socket [Socket, Actor] the socket instance to remember
-    # @return [void]
-    def remember_socket(socket)
-      @sockets[socket.to_ptr.to_i] = socket
-    end
-
-    # Forgets the socket because it has been removed from the poller.
-    # @param socket [Socket, Actor] the socket instance to forget
-    # @return [void]
-    def forget_socket(socket)
-      @sockets.delete(socket.to_ptr.to_i)
-    end
-
-    # Gets the previously remembered socket associated to the given pointer.
-    # @param ptr [FFI::Pointer] the pointer to a socket
-    # @return [Socket, Actor] the socket associated to the given pointer
-    # @raise [SystemCallError] if no socket is registered under given pointer
-    def socket_by_ptr(ptr)
-      @sockets[ptr.to_i] or
-        # NOTE: This should never happen, since #wait will return nil if
-        # +zpoller_wait+ returned NULL. But it's better to fail early in case
-        # it ever returns a wrong pointer.
-        raise_zmq_err("no socket known for pointer #{ptr.inspect}")
-    end
-  end
 end

data/lib/cztop/socket/types.rb

@@ -206,5 +206,62 @@ module CZTop
         attach_ffi_delegate(Zsock.new_stream(endpoints))
       end
     end
+
+    # Group-based pub/sub (vs topic-based). This is the publisher socket.
+    # @see https://github.com/zeromq/libzmq/pull/1727
+    class RADIO < Socket
+      # @param endpoints [String] endpoints to connect to
+      def initialize(endpoints = nil)
+        attach_ffi_delegate(Zsock.new_radio(endpoints))
+      end
+    end
+
+    # Group-based pub/sub (vs topic-based). This is the subscriber socket.
+    # @see https://github.com/zeromq/libzmq/pull/1727
+    class DISH < Socket
+      # @param endpoints [String] endpoints to connect to
+      def initialize(endpoints = nil)
+        attach_ffi_delegate(Zsock.new_dish(endpoints))
+      end
+
+      # Joins the given group.
+      # @param group [String] group to join, up to 15 characters
+      # @return [void]
+      # @raise [ArgumentError] when group name is invalid or group has already
+      #   been joined before
+      # @raise [SystemCallError] in case of failure
+      def join(group)
+        rc = ffi_delegate.join(group)
+        raise_zmq_err("unable to join group %p" % group) if rc == -1
+      end
+
+      # Leaves the given group.
+      # @param group [String] group to leave
+      # @return [void]
+      # @raise [ArgumentError] when group wasn't joined before
+      # @raise [SystemCallError] in case of another failure
+      def leave(group)
+        rc = ffi_delegate.leave(group)
+        raise_zmq_err("unable to leave group %p" % group) if rc == -1
+      end
+    end
+
+    # Scatter/gather pattern.
+    # @see https://github.com/zeromq/libzmq/pull/1909
+    class SCATTER < Socket
+      # @param endpoints [String] endpoints to connect to
+      def initialize(endpoints = nil)
+        attach_ffi_delegate(Zsock.new_scatter(endpoints))
+      end
+    end
+
+    # Scatter/gather pattern.
+    # @see https://github.com/zeromq/libzmq/pull/1909
+    class GATHER < Socket
+      # @param endpoints [String] endpoints to connect to
+      def initialize(endpoints = nil)
+        attach_ffi_delegate(Zsock.new_gather(endpoints))
+      end
+    end
   end
 end

data/lib/cztop/version.rb

@@ -1,3 +1,3 @@
 module CZTop
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/cztop/zsock_options.rb

@@ -330,6 +330,18 @@ module CZTop
 #int zsock_tcp_keepalive_intvl (void *self);
 #int zsock_rcvmore (void *self);
 #char * zsock_last_endpoint (void *self);
+#attach_function :zsock_connect_timeout, [:pointer], :int, **opts
+#attach_function :zsock_handshake_ivl, [:pointer], :int, **opts
+#attach_function :zsock_invert_matching, [:pointer], :int, **opts
+#attach_function :zsock_multicast_maxtpdu, [:pointer], :int, **opts
+#attach_function :zsock_socks_proxy, [:pointer], :pointer, **opts
+#attach_function :zsock_tcp_maxrt, [:pointer], :int, **opts
+#attach_function :zsock_thread_safe, [:pointer], :int, **opts
+#attach_function :zsock_use_fd, [:pointer], :int, **opts
+#attach_function :zsock_vmci_buffer_max_size, [:pointer], :int, **opts
+#attach_function :zsock_vmci_buffer_min_size, [:pointer], :int, **opts
+#attach_function :zsock_vmci_buffer_size, [:pointer], :int, **opts
+#attach_function :zsock_vmci_connect_timeout, [:pointer], :int, **opts
 #
 #//  Set socket options
 #void zsock_set_router_handover (void *self, int router_handover);
@@ -358,6 +370,24 @@ module CZTop
 #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);
+#attach_function :zsock_set_connect_rid, [:pointer, :string], :void, **opts
+#attach_function :zsock_set_connect_rid_bin, [:pointer, :pointer], :void, **opts
+#attach_function :zsock_set_connect_timeout, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_handshake_ivl, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_invert_matching, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_multicast_maxtpdu, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_socks_proxy, [:pointer, :string], :void, **opts
+#attach_function :zsock_set_stream_notify, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_tcp_maxrt, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_use_fd, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_vmci_buffer_max_size, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_vmci_buffer_min_size, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_vmci_buffer_size, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_vmci_connect_timeout, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_xpub_manual, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_xpub_nodrop, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_xpub_verboser, [:pointer, :int], :void, **opts
+#attach_function :zsock_set_xpub_welcome_msg, [:pointer, :string], :void, **opts
     end
   end
 end

data/lib/cztop.rb

@@ -31,6 +31,10 @@ require_relative 'cztop/config/comments'
 require_relative 'cztop/config/traversing'
 require_relative 'cztop/config/serialization'
 require_relative 'cztop/message/frames'
+require_relative 'cztop/metadata'
+require_relative 'cztop/poller/aggregated'
+require_relative 'cztop/poller/zmq'
+require_relative 'cztop/poller/zpoller'
 require_relative 'cztop/socket/types'
 require_relative 'cztop/z85/padded'
 require_relative 'cztop/z85/pipe'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cztop
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Patrik Wenger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-24 00:00:00.000000000 Z
+date: 2016-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: czmq-ffi-gen
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -261,8 +261,12 @@ files:
 - lib/cztop/has_ffi_delegate.rb
 - lib/cztop/message.rb
 - lib/cztop/message/frames.rb
+- lib/cztop/metadata.rb
 - lib/cztop/monitor.rb
 - lib/cztop/poller.rb
+- lib/cztop/poller/aggregated.rb
+- lib/cztop/poller/zmq.rb
+- lib/cztop/poller/zpoller.rb
 - lib/cztop/polymorphic_zsock_methods.rb
 - lib/cztop/proxy.rb
 - lib/cztop/send_receive_methods.rb