cztop 0.1.0

data/lib/cztop/config/comments.rb

@@ -0,0 +1,66 @@
+module CZTop
+  class Config
+
+    # Access this config item's comments.
+    # @note Note that comments are discarded when loading a config (either from
+    #   a string or file) and thus, only the comments you add during runtime
+    #   are accessible.
+    # @return [CommentsAccessor]
+    def comments
+      return CommentsAccessor.new(self)
+    end
+
+    # Used to access a {Config}'s comments.
+    class CommentsAccessor
+      include Enumerable
+
+      # @param config [Config]
+      def initialize(config)
+        @config = config
+      end
+
+      # Adds a new comment.
+      # @param new_comment [String]
+      # @return [self]
+      def <<(new_comment)
+        @config.ffi_delegate.set_comment("%s", :string, new_comment)
+        return self
+      end
+
+      # Deletes all comments for this {Config} item.
+      # @return [void]
+      def delete_all
+        @config.ffi_delegate.set_comment(nil)
+      end
+
+      # Yields all comments for this {Config} item.
+      # @yieldparam comment [String]
+      # @return [void]
+      def each
+        while comment = _zlist.next
+          break if comment.null?
+          yield comment.read_string
+        end
+      rescue CZMQ::FFI::Zlist::DestroyedError
+        # there are no comments
+        nil
+      end
+
+      # Returns the number of comments for this {Config} item.
+      # @return [Integer] number of comments
+      def size
+        _zlist.size
+      rescue CZMQ::FFI::Zlist::DestroyedError
+        0
+      end
+
+      private
+
+      # Returns the Zlist to the list of comments for this config item.
+      # @return [CZMQ::FFI::Zlist] the zlist of comments for this config item
+      def _zlist
+        @config.ffi_delegate.comments
+      end
+    end
+  end
+end

data/lib/cztop/config/serialization.rb

@@ -0,0 +1,82 @@
+# Methods used around serialization of {CZTop::Config} items.
+module CZTop::Config::Serialization
+  # Serialize to a string in the ZPL format.
+  # @return [String]
+  def to_s
+    ffi_delegate.str_save.read_string
+  end
+
+  # Returns the path/filename of the file this {Config} tree was loaded from.
+  # @return [String]
+  def filename
+    ffi_delegate.filename
+  end
+
+  # Some class methods for {Config} related to serialization.
+  module ClassMethods
+    # Loads a {Config} tree from a string.
+    # @param string [String] the tree
+    # @return [Config]
+    def from_string(string)
+      from_ffi_delegate CZMQ::FFI::Zconfig.str_load(string)
+    end
+
+    # Loads a {Config} tree from a file.
+    # @param path [String, Pathname, #to_s] the path to the ZPL config file
+    # @raise [SystemCallError] if this fails
+    # @return [Config]
+    def load(path)
+      ptr = CZMQ::FFI::Zconfig.load(path.to_s)
+      return from_ffi_delegate(ptr) unless ptr.null?
+      CZTop::HasFFIDelegate.raise_zmq_err(
+        "error while reading the file %p" % path.to_s)
+    end
+
+    # Loads a {Config} tree from a marshalled string.
+    # @note This method is automatically used by Marshal.load.
+    # @param string [String] marshalled {Config}
+    # @return [Config]
+    def _load(string)
+      from_string(string)
+    end
+  end
+
+  # Saves the Config tree to a file.
+  # @param path [String, Pathname, #to_s] the path to the ZPL config file
+  # @return [void]
+  # @raise [SystemCallError] if this fails
+  def save(path)
+    rc = ffi_delegate.save(path.to_s)
+    return if rc == 0
+    raise_zmq_err("error while saving to the file %s" % path)
+  end
+
+  # Reload config tree from same file that it was previously loaded from.
+  # @raise [TypeError] if this is an in-memory config
+  # @raise [SystemCallError] if this fails (no existing data will be
+  #   changed)
+  # @return [void]
+  def reload
+    # NOTE: can't use Zconfig.reload, as we won't get the self pointer that
+    # gets reassigned by zconfig_reload(). We can just use Zconfig.load and
+    # swap out the FFI delegate.
+    filename = filename() or
+      raise TypeError, "can't reload in-memory config"
+    ptr = CZMQ::FFI::Zconfig.load(filename)
+    return attach_ffi_delegate(ptr) unless ptr.null?
+    raise_zmq_err("error while reloading from the file %p" % filename)
+  end
+
+  # Serialize (marshal) this Config and all its children.
+  #
+  # @note This method is automatically used by Marshal.dump.
+  # @return [String] marshalled {Config}
+  def _dump(_level)
+    to_s
+  end
+end
+
+class CZTop::Config
+  include Serialization
+  extend Serialization::ClassMethods
+end

data/lib/cztop/config/traversing.rb

@@ -0,0 +1,157 @@
+# Methods used to traverse a {CZTop::Config} tree.
+module CZTop::Config::Traversing
+
+  # Calls the given block once for each {Config} item in the tree, starting
+  # with self.
+  #
+  # @yieldparam config [Config] the config item
+  # @yieldparam level [Integer] level of the item (self has level 0,
+  #   its direct children have level 1)
+  # @return [Object] the block's return value
+  # @raise [ArgumentError] if no block given
+  # @raise [Exception] the block's exception, in case it raises (it won't
+  #   call the block any more after that)
+  def execute
+    raise ArgumentError, "no block given" unless block_given?
+    exception = nil
+    block_value = nil
+    ret = nil
+    callback = CZMQ::FFI::Zconfig.fct do |zconfig, _arg, level|
+      begin
+        # NOTE: work around JRuby and Rubinius bug, where it'd keep calling
+        # this FFI::Function, even when the block `break`ed
+        if ret != -1
+          config = from_ffi_delegate(zconfig)
+          block_value = yield config, level
+          ret = 0 # report success to keep zconfig_execute() going
+        end
+      rescue
+        # remember exception, so we can raise it later to the ruby code
+        # (it can't be raised now, as we have to report failure to
+        # zconfig_execute())
+        exception = $!
+
+        ret = -1 # report failure to stop zconfig_execute() immediately
+      ensure
+        ret ||= -1 # in case of 'break'
+      end
+      ret
+    end
+    ffi_delegate.execute(callback, _arg = nil)
+    raise exception if exception
+    return block_value
+  end
+
+  # Access to this config item's direct children.
+  # @return [ChildrenAccessor]
+  def children
+    ChildrenAccessor.new(self)
+  end
+
+  # Access to this config item's siblings.
+  # @note Only the "younger" (later in the ZPL file) config items are
+  #   considered.
+  # @return [SiblingsAccessor]
+  def siblings
+    SiblingsAccessor.new(self)
+  end
+
+  # Used to give access to a {Config} item's children or siblings.
+  # @abstract
+  class FamilyAccessor
+    include Enumerable
+
+    # @param config [Config] the relative starting point (either parent or
+    #   an older sibling)
+    def initialize(config)
+      @config = config
+    end
+
+    # This is supposed to return the first relevant config item.
+    # @abstract
+    # @return [Config, nil]
+    def first; end
+
+    # Yields all direct children/younger siblings. Starts with {#first}, if
+    # set.
+    # @yieldparam config [Config]
+    def each
+      current = first()
+      return if current.nil?
+      yield current
+      current_delegate = current.ffi_delegate
+      while current_delegate = current_delegate.next
+        break if current_delegate.null?
+        yield CZTop::Config.from_ffi_delegate(current_delegate)
+      end
+    end
+
+    # Recursively compares these config items with the ones of the other.
+    # @param other [FamilyAccessor]
+    def ==(other)
+      these = to_a
+      those = other.to_a
+      these.size == those.size && these.zip(those) do |this, that|
+        this.tree_equal?(that) or return false
+      end
+      return true
+    end
+  end
+
+  # Accesses the younger siblings of a given {Config} item.
+  class SiblingsAccessor < FamilyAccessor
+    # Returns the first sibling.
+    # @return [Config]
+    # @return [nil] if no younger siblings
+    def first
+      ptr = @config.ffi_delegate.next
+      return nil if ptr.null?
+      CZTop::Config.from_ffi_delegate(ptr)
+    end
+  end
+
+  # Accesses the direct children of a given {Config} item.
+  class ChildrenAccessor < FamilyAccessor
+    def first
+      ptr = @config.ffi_delegate.child
+      return nil if ptr.null?
+      CZTop::Config.from_ffi_delegate(ptr)
+    end
+
+    # Adds a new Config item and yields it, so it can be configured in
+    # a block.
+    # @param name [String] name for new config item
+    # @param value [String] value for new config item
+    # @yieldparam [Config] the new config item, if block was given
+    # @return [Config] the new config item
+    def new(name = nil, value = nil)
+      config = CZTop::Config.new(name, value, parent: @config)
+      yield config if block_given?
+      config
+    end
+  end
+
+  # Finds a config item along a path, relative to the current item.
+  # @param path [String] path (leading slash is optional and will be
+  #   ignored)
+  # @return [Config] the found config item
+  # @return [nil] if there's no config item under this path
+  def locate(path)
+    ptr = ffi_delegate.locate(path)
+    return nil if ptr.null?
+    from_ffi_delegate(ptr)
+  end
+
+  # Finds last item at given level (0 = root).
+  # @return [Config] the last config item at given level
+  # @return [nil] if there's no config item at given level
+  def last_at_depth(level)
+    ptr = ffi_delegate.at_depth(level)
+    return nil if ptr.null?
+    from_ffi_delegate(ptr)
+  end
+end
+
+class CZTop::Config
+  include Traversing
+end

data/lib/cztop/config.rb

@@ -0,0 +1,119 @@
+module CZTop
+
+  # Represents a CZMQ::FFI::Zconfig item.
+  # @see http://rfc.zeromq.org/spec:4/ZPL
+  class Config
+    include HasFFIDelegate
+    extend CZTop::HasFFIDelegate::ClassMethods
+
+    # Initializes a new {Config} item. Takes an optional block to initialize
+    # the item further.
+    # @param name [String] config item name
+    # @param value [String] config item value
+    # @param parent [Config] parent config item
+    # @yieldparam config [self]
+    # @note If parent is given, the native child will be destroyed when the
+    #   native parent is destroyed (and not when the child's corresponding
+    #   {Config} object is garbage collected).
+    def initialize(name = nil, value = nil, parent: nil)
+      if parent
+        parent = parent.ffi_delegate if parent.is_a?(Config)
+        delegate = ::CZMQ::FFI::Zconfig.new(name, parent)
+        attach_ffi_delegate(delegate)
+
+        # NOTE: this delegate must not be freed automatically, because the
+        # parent will free it.
+        delegate.__undef_finalizer
+      else
+        delegate = ::CZMQ::FFI::Zconfig.new(name, nil)
+        attach_ffi_delegate(delegate)
+      end
+
+      self.value = value if value
+      yield self if block_given?
+    end
+
+    # @!group ZPL attributes
+
+    # Gets the name.
+    # @return [String] name of the config item
+    def name
+      ptr = ffi_delegate.name
+      return nil if ptr.null? # NOTE: for unnamed elements
+      ptr.read_string
+    end
+
+    # Sets a new name.
+    # @param new_name [String, #to_s]
+    # @return [new_name]
+    def name=(new_name)
+      ffi_delegate.set_name(new_name.to_s)
+    end
+
+    # Get the value of the config item.
+    # @return [String]
+    # @note This returns an empty string if the value is unset.
+    def value
+      ptr = ffi_delegate.value
+      return "" if ptr.null? # NOTE: for root elements
+      ptr.read_string
+    end
+
+    # Set or update the value of the config item.
+    # @param new_value [String, #to_s]
+    # @return [new_value]
+    def value=(new_value)
+      ffi_delegate.set_value("%s", :string, new_value.to_s)
+    end
+
+    # Inspects this {Config} item.
+    # @return [String] shows class, name, and value
+    def inspect
+      "#<#{self.class.name}: name=#{name.inspect} value=#{value.inspect}>"
+    end
+
+    # Update the value of a config item by path.
+    # @param path [String, #to_s] path to config item
+    # @param value [String, #to_s] path to config item
+    # @return [value]
+    def []=(path, value)
+      ffi_delegate.put(path.to_s, value.to_s)
+    end
+    alias_method :put, :[]=
+
+    # Get the value of the current config item.
+    # @param path [String, #to_s] path to config item
+    # @param default [String, #to_s] default value to return if config item
+    #   doesn't exist
+    # @return [String]
+    # @return [default] if config item doesn't exist
+    # @note The default value is not returned when the config item exists but
+    #   just doesn't have a value. In that case, it'll return the empty
+    #   string.
+    def [](path, default = "")
+      ptr = ffi_delegate.get(path, default)
+      return nil if ptr.null?
+      ptr.read_string
+    end
+    alias_method :get, :[]
+
+    # @!endgroup
+
+    # Compares this config item to another. Only the name and value are
+    # considered. If you need to compare a config tree, use {#tree_equal?}.
+    # @param other [Config] the other config item
+    # @return [Boolean] whether they're equal
+    def ==(other)
+      name == other.name &&
+      value == other.value
+    end
+
+    # Compares this config tree to another tree or subtree. Names, values, and
+    # children are considered.
+    # @param other [Config] the other config tree
+    # @return [Boolean] whether they're equal
+    def tree_equal?(other)
+      self == other && self.children == other.children
+    end
+  end
+end

data/lib/cztop/frame.rb

@@ -0,0 +1,158 @@
+module CZTop
+  # Represents a CZMQ::FFI::Zframe, a part of a message.
+  #
+  # @note Dealing with frames (parts of a message) is pretty low-level. You'll
+  #   probably not really need this functionality. It's only useful when you
+  #   need to be able to receive and send single frames. Just use {Message}
+  #   instead.
+  #
+  # @see http://api.zeromq.org/czmq3-0:zframe
+  class Frame
+    include HasFFIDelegate
+    extend CZTop::HasFFIDelegate::ClassMethods
+
+    # Initialize a new {Frame}.
+    # @param content [String] initial content
+    def initialize(content = nil)
+      attach_ffi_delegate(CZMQ::FFI::Zframe.new_empty)
+      self.content = content if content
+    end
+
+    FLAG_MORE = 1
+    FLAG_REUSE = 2
+    FLAG_DONTWAIT = 4
+
+    # Send {Message} to a {Socket}/{Actor}.
+    # @param destination [Socket, Actor] where to send this {Message} to
+    # @param more [Boolean] whether there are more {Frame}s to come for the
+    #   same {Message}
+    # @param reuse [Boolean] whether this {Frame} will be used to send to
+    #   other destinations later
+    # @param dontwait [Boolean] whether the operation should be performed in
+    #   non-blocking mode
+    # @note If you don't specify +reuse: true+, do NOT use this {Frame}
+    #   anymore afterwards. Its native counterpart will have been destroyed.
+    # @note This is low-level. Consider just sending a {Message}.
+    # @return [void]
+    # @raise [IO::EAGAINWaitWritable] if dontwait was set and the operation
+    #   would have blocked right now
+    # @raise [SystemCallError] if there was some error. In that case, the
+    #   native counterpart still exists and this {Frame} can be reused.
+    def send_to(destination, more: false, reuse: false, dontwait: false)
+      flags = 0
+      flags |= FLAG_MORE if more
+      flags |= FLAG_REUSE if reuse
+      flags |= FLAG_DONTWAIT if dontwait
+
+      # remember pointer, in case the zframe_t won't be destroyed
+      zframe_ptr = ffi_delegate.to_ptr
+      ret = CZMQ::FFI::Zframe.send(ffi_delegate, destination, flags)
+
+      if reuse || ret == -1
+        # zframe_t hasn't been destroyed yet: avoid memory leak.
+        attach_ffi_delegate(CZMQ::FFI::Zframe.__new(zframe_ptr, true))
+        # OPTIMIZE: reuse existing Zframe object by redefining its finalizer
+      end
+
+      if ret == -1
+        if dontwait && FFI.errno == Errno::EAGAIN::Errno
+          raise IO::EAGAINWaitWritable
+        end
+
+        raise_zmq_err
+      end
+    end
+
+    # Receive {Frame} from a {Socket}/{Actor}.
+    # @note This is low-level. Consider just receiving a {Message}.
+    # @return [Frame]
+    def self.receive_from(source)
+      from_ffi_delegate(CZMQ::FFI::Zframe.recv(source))
+    end
+
+    # @note This string is always binary. Use String#force_encoding if needed.
+    # @return [String] content as string (encoding = Encoding::BINARY)
+    def content
+      ffi_delegate.data.read_string(size)
+    end
+    alias_method :to_s, :content
+
+    # @return [Boolean] if this {Frame} has zero-sized content
+    def empty?
+      size.zero?
+    end
+
+    # Sets new content of this {Frame}.
+    # @param new_content [String]
+    # @return [new_content]
+    def content=(new_content)
+      content_ptr = ::FFI::MemoryPointer.new(new_content.bytesize)
+      content_ptr.write_bytes(new_content)
+      ffi_delegate.reset(content_ptr, content_ptr.size)
+      # NOTE: FFI::MemoryPointer will autorelease
+    end
+
+    # Duplicates a frame.
+    # @return [Frame] new frame with same content
+    def dup
+      from_ffi_delegate(ffi_delegate.dup)
+    end
+
+    # @return [Boolean] if the MORE indicator is set
+    # @note This happens when reading a frame from a {Socket} or using
+    #   {#more=}.
+    def more?
+      ffi_delegate.more == 1
+    end
+
+    # Sets the MORE indicator.
+    # @param indicator [Boolean]
+    # @note This is NOT used when sending frame to socket.
+    # @see #send_to
+    # @return [indicator]
+    def more=(indicator)
+      ffi_delegate.set_more(indicator ? 1 : 0)
+    end
+
+    # Compare to another frame.
+    # @param other [Frame]
+    # @return [Boolean] if this and the other frame have identical size and
+    #   data
+    # @note If you need to compare to a string, as zframe_streq() would do,
+    #   just get this frame's content first and compare that to the string.
+    #     frame = CZTop::Frame.new("foobar")
+    #     frame.to_s == "foobar" #=> true
+    # @example
+    #   frame1 = Frame.new("foo")
+    #   frame2 = Frame.new("foo")
+    #   frame3 = Frame.new("bar")
+    #   frame1 == frame2    #=> true
+    #   frame1 == frame3    #=> false
+    # @note The {#more?} flag and the {#routing_id} are ignored.
+    def ==(other)
+      ffi_delegate.eq(other.ffi_delegate)
+    end
+
+    # @return [Integer] content length in bytes
+    ffi_delegate :size
+
+    # Gets the routing ID.
+    # @note This only set when the frame came 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}
+    #   socket.
+    # @param new_routing_id [Integer] new routing ID
+    # @raise [RangeError] if new routing ID is out of +uint32_t+ range
+    # @return [new_routing_id]
+    def routing_id=(new_routing_id)
+      # need to raise manually, as FFI lacks this feature.
+      # @see https://github.com/ffi/ffi/issues/473
+      raise RangeError if new_routing_id < 0
+      ffi_delegate.set_routing_id(new_routing_id)
+    end
+  end
+end

data/lib/cztop/has_ffi_delegate.rb

@@ -0,0 +1,85 @@
+require 'forwardable'
+require 'socket' # for SocketError
+
+# This module is used to attach the low-level objects of classes within the
+# CZMQ::FFI namespace (coming from the _czmq-ffi-gen_ gem) as delegates.
+module CZTop::HasFFIDelegate
+  # @return [CZMQ::FFI::*] the attached delegate
+  attr_reader :ffi_delegate
+
+  # @return [FFI::Pointer] FFI delegate's pointer
+  def to_ptr
+    @ffi_delegate.to_ptr
+  end
+
+  # 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
+  # @return [void]
+  def attach_ffi_delegate(ffi_delegate)
+    raise_zmq_err(CZMQ::FFI::Errors.strerror) if ffi_delegate.null?
+    @ffi_delegate = ffi_delegate
+  end
+
+  # Same as the counterpart in {ClassMethods}, but usable from within an
+  # instance.
+  # @see CZTop::FFIDelegate::ClassMethods#from_ffi_delegate
+  # @return [CZTop::*] the new object
+  def from_ffi_delegate(ffi_delegate)
+    self.class.from_ffi_delegate(ffi_delegate)
+  end
+
+  module_function
+
+  # Raises the appropriate exception for the reported ZMQ error.
+  #
+  # @param msg [String] error message
+  # @raise [ArgumentError] if EINVAL was reported
+  # @raise [Interrupt] if EINTR was reported
+  # @raise [SocketError] if EAGAIN was reported
+  # @raise [SystemCallError] any other reported error (appropriate
+  #   SystemCallError subclass, if errno is known)
+  def raise_zmq_err(msg = CZMQ::FFI::Errors.strerror,
+                    errno: CZMQ::FFI::Errors.errno)
+
+    # If the errno is known, the corresponding Errno::* exception is
+    # automatically constructed. Otherwise, it'll be a plain SystemCallError.
+    # In any case, #errno will return the corresponding errno.
+    raise SystemCallError.new(msg, errno), msg, caller
+  rescue Errno::EINVAL
+    raise ArgumentError, msg, caller
+  rescue Errno::EINTR
+    raise Interrupt, msg, caller
+  rescue Errno::EHOSTUNREACH
+    raise SocketError, msg, caller
+  end
+
+  # Some class methods related to FFI delegates.
+  module ClassMethods
+    include Forwardable
+
+    # Delegate specified instance method to the registered FFI delegate.
+    # @note It only takes one method name so it's easy to add some
+    #   documentation for each delegated method.
+    # @param method [Symbol] method to delegate
+    # @return [void]
+    def ffi_delegate(method)
+      def_delegator(:@ffi_delegate, method)
+    end
+
+    # Allocates a new instance and attaches the FFI delegate to it. This is
+    # useful if you already have an FFI delegate and need to attach it to a
+    # fresh high-level object.
+    # @return [CZTop::*] the fresh object
+    # @note #initialize won't be called on the fresh object. This works around
+    #   the fact that #initialize usually assumes that no FFI delegate is
+    #   attached yet and will try to do so (and also expect to be called in a
+    #   specific way).
+    def from_ffi_delegate(ffi_delegate)
+      obj = allocate
+      obj.attach_ffi_delegate(ffi_delegate)
+      return obj
+    end
+  end
+end