cztop 0.1.0

data/lib/cztop/message/frames.rb

@@ -0,0 +1,74 @@
+module CZTop
+  class Message
+
+    # @return [Integer] number of frames
+    # @see content_size
+    def size
+      frames.count
+    end
+
+    # Access to this {Message}'s {Frame}s.
+    # @return [FramesAccessor]
+    def frames
+      FramesAccessor.new(self)
+    end
+
+    # Used to access a {Message}'s {Frame}s.
+    class FramesAccessor
+      include Enumerable
+
+      # @param message [Message]
+      def initialize(message)
+        @message = message
+      end
+
+      # Returns the last frame of this message.
+      # @return [Frame] first frame of Message
+      # @return [nil] if there are no frames
+      def first
+        first = @message.ffi_delegate.first
+        return nil if first.null?
+        Frame.from_ffi_delegate(first)
+      end
+
+      # Returns the last frame of this message.
+      # @return [Frame] last {Frame} of {Message}
+      # @return [nil] if there are no frames
+      def last
+        last = @message.ffi_delegate.last
+        return nil if last.null?
+        Frame.from_ffi_delegate(last)
+      end
+
+      # Index access to a frame/frames of this message, just like with an
+      # array.
+      # @overload [](index)
+      #   @param index [Integer] index of {Frame} within {Message}
+      # @overload [](*args)
+      #   @note See Array#[] for details.
+      # @return [Frame] frame Message
+      # @return [nil] if there are no corresponding frames
+      def [](*args)
+        case args
+        when [0] then first # speed up
+        when [-1] then last # speed up
+        else to_a[*args]
+        end
+      end
+
+      # Yields all frames for this message to the given block.
+      # @note Not thread safe.
+      # @yieldparam frame [Frame]
+      # @return [self]
+      def each
+        first = first()
+        return unless first
+        yield first
+        while frame = @message.ffi_delegate.next and not frame.null?
+          yield Frame.from_ffi_delegate(frame)
+        end
+        return self
+      end
+    end
+  end
+end

data/lib/cztop/message.rb

@@ -0,0 +1,191 @@
+module CZTop
+  # Represents a CZMQ::FFI::Zmsg.
+  class Message
+    include HasFFIDelegate
+    extend CZTop::HasFFIDelegate::ClassMethods
+    include ::CZMQ::FFI
+
+    # Coerces an object into a {Message}.
+    # @param msg [Message, String, Frame, Array<String>, Array<Frame>]
+    # @return [Message]
+    # @raise [ArgumentError] if it can't be coerced
+    def self.coerce(msg)
+      case msg
+      when Message
+        return msg
+      when String, Frame, Array
+        return new(msg)
+      else
+        raise ArgumentError, "cannot coerce message: %p" % msg
+      end
+    end
+
+    # @param parts [String, Frame, Array<String>, Array<Frame>] initial parts
+    #   of the message
+    def initialize(parts = nil)
+      attach_ffi_delegate(Zmsg.new)
+      Array(parts).each { |part| self << part } if parts
+    end
+
+    # @return [Boolean] if this message is empty or not
+    def empty?
+      content_size.zero?
+    end
+
+    # Send {Message} to a {Socket} or {Actor}.
+    #
+    # @note Do NOT use this {Message} anymore afterwards. Its native
+    #   counterpart will have been destroyed.
+    #
+    # @param destination [Socket, Actor] where to send this message to
+    # @return [void]
+    #
+    # @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
+    #   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
+    #   corresponding
+    #   to the given routing ID)
+    # @raise [ArgumentError] if the message is invalid, e.g. when trying to
+    #   send a multi-part message over a CLIENT/SERVER socket
+    # @raise [SystemCallError] for any other error code set after +zmsg_send+
+    #   returns with failure. Please report as bug.
+    #
+    def send_to(destination)
+      rc = Zmsg.send(ffi_delegate, destination)
+      return if rc == 0
+      raise_zmq_err
+    rescue Errno::EAGAIN
+      raise IO::EAGAINWaitWritable
+    end
+
+    # Receive a {Message} from a {Socket} or {Actor}.
+    # @param source [Socket, Actor]
+    # @return [Message] the newly received message
+    # @raise [IO::EAGAINWaitReadable] if the receive timeout has been reached
+    #   (see {ZsockOptions::OptionsAccessor#rcvtimeo=})
+    # @raise [Interrupt] if interrupted while waiting for a message
+    # @raise [SystemCallError] for any other error code set after +zmsg_recv+
+    #   returns with failure. Please report as bug.
+    def self.receive_from(source)
+      delegate = Zmsg.recv(source)
+      return from_ffi_delegate(delegate) unless delegate.null?
+      HasFFIDelegate.raise_zmq_err
+    rescue Errno::EAGAIN
+      raise IO::EAGAINWaitReadable
+    end
+
+    # Append a frame to this message.
+    # @param frame [String, Frame] what to append
+    # @raise [ArgumentError] if frame has an invalid type
+    # @raise [SystemCallError] if this fails
+    # @note If you provide a {Frame}, do NOT use that frame afterwards
+    #   anymore, as its native counterpart will have been destroyed.
+    # @return [self] so it can be chained
+    def <<(frame)
+      case frame
+      when String
+        # NOTE: can't use addstr because the data might be binary
+        mem = FFI::MemoryPointer.from_string(frame)
+        rc = ffi_delegate.addmem(mem, mem.size - 1) # without NULL byte
+      when Frame
+        rc = ffi_delegate.append(frame.ffi_delegate)
+      else
+        raise ArgumentError, "invalid frame: %p" % frame
+      end
+      raise_zmq_err unless rc == 0
+      self
+    end
+
+    # Prepend a frame to this message.
+    # @param frame [String, Frame] what to prepend
+    # @raise [ArgumentError] if frame has an invalid type
+    # @raise [SystemCallError] if this fails
+    # @note If you provide a {Frame}, do NOT use that frame afterwards
+    #   anymore, as its native counterpart will have been destroyed.
+    # @return [void]
+    def prepend(frame)
+      case frame
+      when String
+        # NOTE: can't use pushstr because the data might be binary
+        mem = FFI::MemoryPointer.from_string(frame)
+        rc = ffi_delegate.pushmem(mem, mem.size - 1) # without NULL byte
+      when Frame
+        rc = ffi_delegate.prepend(frame.ffi_delegate)
+      else
+        raise ArgumentError, "invalid frame: %p" % frame
+      end
+      raise_zmq_err unless rc == 0
+    end
+
+    # Removes first part from message and returns it as a string.
+    # @return [String, nil] first part, if any, or nil
+    def pop
+      # NOTE: can't use popstr because the data might be binary
+      ptr = ffi_delegate.pop
+      return nil if ptr.null?
+      Frame.from_ffi_delegate(ptr).to_s
+    end
+
+    # @return [Integer] size of this message in bytes
+    # @see size
+    def content_size
+      ffi_delegate.content_size
+    end
+
+    # Returns all frames as strings in an array. This is useful if for quick
+    # inspection of the message.
+    # @note It'll read all frames in the message and turn them into Ruby
+    #   strings. This can be a problem if the message is huge/has huge frames.
+    # @return [Array<String>] all frames
+    def to_a
+      frames.map(&:to_s)
+    end
+
+    # Inspects this {Message}.
+    # @return [String] shows class, number of frames, content size, and
+    #   content (only if it's up to 200 bytes)
+    def inspect
+      "#<%s:0x%x frames=%i content_size=%i content=%s>" % [
+        self.class,
+        to_ptr.address,
+        size,
+        content_size,
+        content_size <= 500 ? to_a.inspect : "[...]"
+      ]
+    end
+
+    # Return a frame's content.
+    # @return [String] the frame's content, if it exists
+    # @return [nil] if frame doesn't exist at given index
+    def [](frame_index)
+      frame = frames[frame_index] or return nil
+      frame.to_s
+    end
+
+    # 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 message is sent to a {CZTop::Socket::SERVER}
+    #   socket.
+    # @param new_routing_id [Integer] new routing ID
+    # @raise [ArgumentError] if new routing ID is not an Integer
+    # @raise [RangeError] if new routing ID is out of +uint32_t+ range
+    # @return [new_routing_id]
+    def routing_id=(new_routing_id)
+      raise ArgumentError unless new_routing_id.is_a? Integer
+
+      # 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/monitor.rb

@@ -0,0 +1,102 @@
+require "pry"
+
+module CZTop
+  # CZMQ monitor. Listen for socket events.
+  #
+  # This is implemented using an {Actor}.
+  #
+  # @note This works only on connection oriented transports, like TCP, IPC,
+  #   and TIPC.
+  # @see http://api.zeromq.org/czmq3-0:zmonitor
+  # @see http://api.zeromq.org/4-1:zmq-socket-monitor
+  class Monitor
+    include ::CZMQ::FFI
+
+    # function pointer to the `zmonitor()` function
+    ZMONITOR_FPTR = ::CZMQ::FFI.ffi_libraries.each do |dl|
+      fptr = dl.find_function("zmonitor")
+      break fptr if fptr
+    end
+    raise LoadError, "couldn't find zmonitor()" if ZMONITOR_FPTR.nil?
+
+    # @param socket [Socket, Actor] the socket or actor to monitor
+    def initialize(socket)
+      @actor = Actor.new(ZMONITOR_FPTR, socket)
+    end
+
+    # @return [Actor] the actor behind this monitor
+    attr_reader :actor
+
+    # Terminates the monitor.
+    # @return [void]
+    def terminate
+      @actor.terminate
+    end
+
+    # Enable verbose logging of commands and activity.
+    # @return [void]
+    def verbose!
+      @actor << "VERBOSE"
+    end
+
+    # @return [Array<String>] types of valid events
+    EVENTS = %w[
+      CONNECTED
+      CONNECT_DELAYED
+      CONNECT_RETRIED
+      LISTENING
+      BIND_FAILED
+      ACCEPTED
+      ACCEPT_FAILED
+      CLOSED
+      CLOSE_FAILED
+      DISCONNECTED
+      MONITOR_STOPPED
+      ALL
+    ]
+
+    # Configure monitor to listen for specific events.
+    # @param events [String] one or more events from {EVENTS}
+    # @return [void]
+    def listen(*events)
+      events.each do |event|
+        EVENTS.include?(event) or
+          raise ArgumentError, "invalid event: #{event.inspect}"
+      end
+      @actor << [ "LISTEN", *events ]
+    end
+
+    # Start the monitor. After this, you can read events using {#next}.
+    # @return [void]
+    def start
+      @actor << "START"
+      @actor.wait
+    end
+
+    # Get next event. This blocks until the next event is available.
+    # @example
+    #   socket = CZTop::Socket::ROUTER.new("tcp://127.0.0.1:5050")
+    #   # ... normal stuff with socket
+    #
+    #   # do this in another thread, or using a Poller, so it's possible to
+    #   # interact with the socket and the monitor
+    #   Thread.new do
+    #     monitor = CZTop::Monitor.new(socket)
+    #     monitor.listen "CONNECTED", "DISCONNECTED"
+    #     while event = monitor.next
+    #       case event[0]
+    #       when "CONNECTED"
+    #         puts "a client has connected"
+    #       when "DISCONNECTED"
+    #         puts "a client has disconnected"
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String] one of the events from {EVENTS}, something like
+    #   <tt>["ACCEPTED", "73", "tcp://127.0.0.1:55585"]</tt>
+    def next
+      @actor.receive
+    end
+  end
+end

data/lib/cztop/poller.rb

@@ -0,0 +1,334 @@
+module CZTop
+  # A non-trivial socket poller.
+  #
+  # It can poll for reading and writing, and supports getting back an array of
+  # readable/writable sockets after the call to {#wait}. The reason for this
+  # feature is to be able to use it in Celluloid::ZMQ, where in a call to
+  # Celluloid::ZMQ::Reactor#run_once all readable/writable sockets need to be
+  # processed.
+  #
+  # This implementation is NOT based on zpoller. Reasons:
+  #
+  # * zpoller can only poll for reading
+  #
+  # It's also NOT based on `zmq_poller()`. Reasons:
+  #
+  # * zmq_poller() doesn't exist in older versions of ZMQ < 4.2
+  #
+  # Possible future implementation on +zmq_poller()+ might work like this, to
+  # support getting an array of readable/writable sockets:
+  #
+  # * in {#wait}, poll with normal timeout
+  # * then poll again with zero timeout until no more sockets, accumulate
+  #   results
+  #
+  # = Limitations
+  #
+  # This poller can't poll for writing on CLIENT/SERVER sockets.
+  # Implementation could be adapted to support them using
+  # {CZTop::Poller::ZPoller}, at least for reading. But it'd make the code
+  # ugly.
+  #
+  class Poller
+    # CZTop's interface to the low-level +zmq_poll()+ function.
+    module ZMQ
+
+      POLL    = 1
+      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]
+
+      # Represents a struct of type +zmq_pollitem_t+.
+      class PollItem < FFI::Struct
+        ##
+        # shamelessly taken from https://github.com/mtortonesi/ruby-czmq-ffi
+        #
+
+
+        FD_TYPE = if FFI::Platform::IS_WINDOWS && FFI::Platform::ADDRESS_SIZE == 64
+          # On Windows, zmq.h defines fd as a SOCKET, which is 64 bits on x64.
+          :uint64
+        else
+          :int
+        end
+
+        layout  :socket,  :pointer,
+                :fd,      FD_TYPE,
+                :events,  :short,
+                :revents, :short
+
+        # @return [Boolean] whether the socket is readable
+        def readable?
+          (self[:revents] & POLLIN) > 0
+        end
+
+        # @return [Boolean] whether the socket is writable
+        def writable?
+          (self[:revents] & POLLOUT) > 0
+        end
+      end
+
+      opts = {
+        blocking: true  # only necessary on MRI to deal with the GIL.
+      }
+
+      #ZMQ_EXPORT int  zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);
+      attach_function :poll, :zmq_poll, [:pointer, :int, :long], :int, **opts
+    end
+
+    # @param readers [Socket, Actor] sockets to poll for input
+    def initialize(*readers)
+      @readers = {}
+      @writers = {}
+      @readables = []
+      @writables = []
+      @rebuild_needed = true
+      readers.each { |r| add_reader(r) }
+    end
+
+    # @return [Array<CZTop::Socket>] registered reader sockets
+    def readers
+      @readers.values
+    end
+
+    # @return [Array<CZTop::Socket>] registered writer sockets
+    def writers
+      @writers.values
+    end
+
+    # Adds a socket to be polled for reading.
+    # @param socket [Socket, Actor] the socket
+    # @return [void]
+    # @raise [ArgumentError] if it's not a socket
+    def add_reader(socket)
+      raise ArgumentError unless socket.is_a?(Socket) || socket.is_a?(Actor)
+      ptr = CZMQ::FFI::Zsock.resolve(socket) # get low-level handle
+      @readers[ptr.to_i] = socket
+      @rebuild_needed = true
+    end
+
+    # Removes a previously registered reader socket. Won't raise if you're
+    # trying to remove a socket that's not registered.
+    # @param socket [Socket, Actor] the socket
+    # @return [void]
+    # @raise [ArgumentError] if it's not a socket
+    def remove_reader(socket)
+      raise ArgumentError unless socket.is_a?(Socket) || socket.is_a?(Actor)
+      ptr = CZMQ::FFI::Zsock.resolve(socket) # get low-level handle
+      @readers.delete(ptr.to_i) and @rebuild_needed = true
+    end
+
+    # Adds a socket to be polled for writing.
+    # @param socket [Socket, Actor] the socket
+    # @return [void]
+    # @raise [ArgumentError] if it's not a socket
+    def add_writer(socket)
+      raise ArgumentError unless socket.is_a?(Socket) || socket.is_a?(Actor)
+      ptr = CZMQ::FFI::Zsock.resolve(socket) # get low-level handle
+      @writers[ptr.to_i] = socket
+      @rebuild_needed = true
+    end
+
+    # Removes a previously registered writer socket. Won't raise if you're
+    # trying to remove a socket that's not registered.
+    # @param socket [Socket, Actor] the socket
+    # @return [void]
+    # @raise [ArgumentError] if it's not a socket
+    def remove_writer(socket)
+      raise ArgumentError unless socket.is_a?(Socket) || socket.is_a?(Actor)
+      ptr = CZMQ::FFI::Zsock.resolve(socket) # get low-level handle
+      @writers.delete(ptr.to_i) and @rebuild_needed = true
+    end
+
+    # Waits for registered sockets to become readable or writable, depending
+    # on what you're interested in.
+    #
+    # @param timeout [Integer] how long to wait in ms, or 0 to avoid blocking,
+    #   or -1 to wait indefinitely
+    # @return [Socket, Actor] the first readable socket
+    # @return [nil] if the timeout expired or
+    # @raise [Interrupt] if the timeout expired or
+    def wait(timeout = -1)
+      rebuild if @rebuild_needed
+      @readables = @writables = nil
+
+      num = ZMQ.poll(@items_ptr, @nitems, timeout)
+      HasFFIDelegate.raise_zmq_err if num == -1
+
+      return nil if num == 0
+      return readables[0] if readables.any?
+
+      # TODO: handle CLIENT/SERVER sockets using ZPoller
+#      if threadsafe_sockets.any?
+#        zpoller.wait(0)
+#      end
+    end
+
+    # @return [Array<CZTop::Socket>] readable sockets (memoized)
+    def readables
+      @readables ||= @reader_items.select(&:readable?).map do |item|
+        ptr = item[:socket]
+        @readers[ ptr.to_i ]
+      end
+    end
+
+    # @return [Array<CZTop::Socket>] writable sockets (memoized)
+    def writables
+      @writables ||= @writer_items.select(&:writable?).map do |item|
+        ptr = item[:socket]
+        @writers[ ptr.to_i ]
+      end
+    end
+
+    private
+
+    # Rebuilds the list of `poll_item_t`.
+    # @return [void]
+    def rebuild
+      @nitems = @readers.size + @writers.size
+      @items_ptr = FFI::MemoryPointer.new(ZMQ::PollItem, @nitems)
+      @items_ptr.autorelease = true
+
+      # memory addresses
+      mem = Enumerator.new do |y|
+        @nitems.times { |i| y << @items_ptr + i * ZMQ::PollItem.size }
+      end
+
+      @reader_items = @readers.map{|_,s| new_item(mem.next, s, ZMQ::POLLIN) }
+      @writer_items = @writers.map{|_,s| new_item(mem.next, s, ZMQ::POLLOUT) }
+
+      @rebuild_needed = false
+    end
+
+    # @param address [FFI::Pointer] allocated memory address for this item
+    # @param socket [CZTop::Socket] socket we're interested in
+    # @param events [Integer] the events we're interested in
+    # @return [ZMQ::PollItem] a new item for
+    def new_item(address, socket, events)
+      item = ZMQ::PollItem.new(address)
+      item[:socket] = CZMQ::FFI::Zsock.resolve(socket)
+      item[:fd] = 0
+      item[:events] = events
+      item[:revents] = 0
+      item
+    end
+
+    # This is the trivial poller based on zpoller. It only supports polling
+    # for reading, 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 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
+
+      # Wait and return 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]
+      # @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
+end