ffi-rzmq 0.5.0

data/lib/ffi-rzmq/message.rb

@@ -0,0 +1,210 @@
+
+module ZMQ
+
+  ZMQ_MSG_INIT_SIZE_STR = 'zmq_msg_init_size'.freeze
+  ZMQ_MSG_INIT_DATA_STR = 'zmq_msg_init_data'.freeze
+  ZMQ_MSG_INIT_STR = 'zmq_msg_init'.freeze
+  ZMQ_MSG_CLOSE_STR = 'zmq_msg_close'.freeze
+  ZMQ_MSG_COPY_STR = 'zmq_msg_copy'.freeze
+  ZMQ_MSG_MOVE_STR = 'zmq_msg_move'.freeze
+  ZMQ_MSG_SIZE_STR = 'zmq_msg_size'.freeze
+
+  # The constructor optionally takes a string as an argument. It will
+  # copy this string to native memory in preparation for transmission.
+  # So, don't pass a string unless you intend to send it. Internally it
+  # calls #copy_in_string.
+  #
+  # Call #close to release buffers when you have *not* passed this on
+  # to Socket#send or Socket#recv. Those methods call #close on your
+  # behalf.
+  #
+  # (This class is not really zero-copy. Ruby makes this near impossible.)
+  #
+  # Message represents ruby equivalent of the +zmq_msg_t+ C struct.
+  # Access the underlying memory buffer and the buffer size using the
+  # #data and #size methods respectively.
+  #
+  # It is recommended that this class be composed inside another class for
+  # access to the underlying buffer. The outer wrapper class can provide
+  # nice accessors for the information in the data buffer; a clever
+  # implementation can probably lazily encode/decode the data buffer
+  # on demand. Lots of protocols send more information than is strictly
+  # necessary, so only decode (copy from the 0mq buffer to Ruby) that
+  # which is necessary.
+  #
+  # When you are done using a *received* message object, just let it go out of
+  # scope to release the memory. During the next garbage collection run
+  # it will call the equivalent of #LibZMQ.zmq_msg_close to release
+  # all buffers. Obviously, this automatic collection of message objects
+  # comes at the price of a larger memory footprint (for the
+  # finalizer proc object) and lower performance. If you wanted blistering
+  # performance, Ruby isn't there just yet.
+  #
+  # As noted above, for sent objects the underlying library will call close
+  # for you.
+  #
+  #  class MyMessage
+  #    def initialize msg_struct = nil
+  #      @msg_t = msg_struct ? msg_struct : ZMQ::Message.new
+  #    end
+  #
+  #    def size() @size = @msg_t.size; end
+  #
+  #    def decode
+  #      @decoded_data = JSON.parse(@msg_t.copy_out_string)
+  #    end
+  #
+  #    def field1
+  #      @field1 ||= decode[:field1]
+  #    end
+  #
+  #    def field2
+  #      @field2 ||= decode[:field2]
+  #    end
+  # ---
+  #
+  #  message = Message.new
+  #  successful_read = socket.recv message
+  #  message = MyMessage.new message if successful_read
+  #  puts "field1 is #{message.field1}"
+  #
+  class Message
+    include ZMQ::Util
+
+    def initialize message = nil
+      @state = :uninitialized
+
+      # allocate our own pointer so that we can tell it to *not* zero out
+      # the memory; it's pointless work since the library is going to
+      # overwrite it anyway.
+      @pointer = FFI::MemoryPointer.new LibZMQ::Msg.size, 1, false
+      @struct = LibZMQ::Msg.new @pointer
+
+      if message
+        copy_in_string message
+      else
+        # initialize an empty message structure to receive a message
+        result_code = LibZMQ.zmq_msg_init @struct
+        error_check ZMQ_MSG_INIT_STR, result_code
+        @state = :initialized
+      end
+    end
+
+    # Makes a copy of the ruby +string+ into a native memory buffer so
+    # that libzmq can send it. The underlying library will handle
+    # deallocation of the native memory buffer.
+    #
+    def copy_in_string string
+      copy_in_bytes string, string.size
+    end
+
+    # Makes a copy of +len+ bytes from the ruby string +bytes+. Library
+    # handles deallocation of the native memory buffer.
+    #
+    def copy_in_bytes bytes, len
+      # release any associated buffers if this Message object is being
+      # reused
+      close unless uninitialized?
+
+      data_buffer = LibC.malloc len
+      # writes the exact number of bytes, no null byte to terminate string
+      data_buffer.write_string bytes, len
+
+      # make sure we have a way to deallocate this memory if the object goes
+      # out of scope
+      define_finalizer
+
+      unless RBX
+        result_code = LibZMQ.zmq_msg_init_data @struct.pointer, data_buffer, len, LibZMQ::MessageDeallocator, nil
+      else
+        # no callback for freeing up memory; memory leak!
+        result_code = LibZMQ.zmq_msg_init_data @struct.pointer, data_buffer, len, nil, nil
+      end
+      error_check ZMQ_MSG_INIT_DATA_STR, result_code
+      @state = :initialized
+    end
+
+    # Provides the memory address of the +zmq_msg_t+ struct. Used mostly for
+    # passing to other methods accessing the underlying library that
+    # require a real data address.
+    #
+    def address
+      @struct.pointer
+    end
+    alias :pointer :address
+
+    def copy source
+      result_code = LibZMQ.zmq_msg_copy @struct.pointer, source.address
+      error_check ZMQ_MSG_COPY_STR, result_code
+      @state = :initialized
+    end
+
+    def move source
+      result_code = LibZMQ.zmq_msg_copy @struct.pointer, source.address
+      error_check ZMQ_MSG_MOVE_STR, result_code
+      @state = :initialized
+    end
+
+    # Provides the size of the data buffer for this +zmq_msg_t+ C struct.
+    #
+    def size
+      LibZMQ.zmq_msg_size @struct.pointer
+    end
+
+    # Returns a pointer to the data buffer.
+    # This pointer should *never* be freed. It will automatically be freed
+    # when the +message+ object goes out of scope and gets garbage
+    # collected.
+    #
+    def data
+      LibZMQ.zmq_msg_data @struct.pointer
+    end
+
+    # Returns the data buffer as a string.
+    #
+    # Note: If this is binary data, it won't print very prettily.
+    #
+    def copy_out_string
+      data.read_string(size)
+    end
+
+    # Manually release the message struct and its associated data
+    # buffer.
+    #
+    # The Message object is still valid after this call and can be used
+    # again for sending or receiving.
+    #
+    def close
+      LibZMQ.zmq_msg_close @struct.pointer
+      remove_finalizer
+      @state = :uninitialized
+    end
+
+
+    private
+
+    def uninitialized?(); :uninitialized == @state; end
+
+    def define_finalizer
+      ObjectSpace.define_finalizer(self, self.class.close(@struct))
+    end
+
+    def remove_finalizer
+      ObjectSpace.undefine_finalizer self
+    end
+
+    # Message finalizer
+    # Note that there is no error checking for the call to #zmq_msg_close.
+    # This is intentional. Since this code runs as a finalizer, there is no
+    # way to catch a raised exception anywhere near where the error actually
+    # occurred in the code, so we just ignore deallocation failures here.
+    def self.close struct
+      Proc.new do
+        # release the data buffer
+        LibZMQ.zmq_msg_close struct.pointer
+      end
+    end
+
+  end # class Message
+
+end # module ZMQ

data/lib/ffi-rzmq/poll.rb

@@ -0,0 +1,186 @@
+
+module ZMQ
+
+  ZMQ_POLL_STR = 'zmq_poll'.freeze
+
+  class Poller
+    include ZMQ::Util
+
+    attr_reader :readables, :writables
+
+    def initialize
+      @items = ZMQ::PollItems.new
+      @raw_to_socket = {}
+      @sockets = []
+      @readables = []
+      @writables = []
+    end
+
+    # Checks each poll item for selectability based on the poll items'
+    # registered +events+. Will block for up to +timeout+ milliseconds
+    # A millisecond is 1/1000 of a second, so to block for 1 second
+    # pass the value "1000" to #poll.
+    #
+    # Pass "-1" or +:blocking+ for +timeout+ for this call to block
+    # indefinitely.
+    #
+    # May raise a ZMQ::PollError exception. This occurs when one of the
+    # registered sockets belongs to an application thread in another
+    # Context.
+    #
+    def poll timeout = :blocking
+      unless @items.empty?
+        timeout = adjust timeout
+        items_triggered = LibZMQ.zmq_poll @items.address, @items.size, timeout
+        error_check ZMQ_POLL_STR, items_triggered >= 0 ? 0 : items_triggered
+        update_selectables
+        items_hash
+      else
+        {}
+      end
+    end
+
+    # The non-blocking version of #poll. See the #poll description for
+    # potential exceptions.
+    #
+    # May raise a ZMQ::PollError exception. This occurs when one of the
+    # registered sockets belongs to an application thread in another
+    # Context.
+    #
+    def poll_nonblock
+      poll 0
+    end
+
+    # Register the +sock+ for +events+. This method is idempotent meaning
+    # it can be called multiple times with the same data and the socket
+    # will only get registered at most once. Calling multiple times with
+    # different values for +events+ will OR the event information together.
+    #
+    # Does not raise any exceptions.
+    #
+    def register sock, events = ZMQ::POLLIN | ZMQ::POLLOUT, fd = 0
+      return unless sock || !fd.zero? || !events.zero?
+
+      @poll_items_dirty = true
+      item = @items.get(@sockets.index(sock))
+
+      unless item
+        @sockets << sock
+        item = LibZMQ::PollItem.new
+        @raw_to_socket[item.socket] = sock
+
+        case sock
+        when ZMQ::Socket, Socket
+          item[:socket] = sock.socket
+          item[:fd] = 0
+        else
+          item[:socket] = 0
+          item[:fd] = fd
+        end
+      end
+
+      item[:events] |= events
+
+      @items << item
+    end
+
+    # Deregister the +sock+ for +events+.
+    #
+    # Does not raise any exceptions.
+    #
+    def deregister sock, events, fd = 0
+      return unless sock || !fd.zero?
+
+      item = @items.get(@sockets.index(sock))
+
+      if item
+        # change the value in place
+        item[:events] ^= events
+
+        delete sock if items[:events].zero?
+      end
+    end
+
+    # A helper method to register a +sock+ as readable events only.
+    #
+    def register_readable sock
+      register sock, ZMQ::POLLIN, 0
+    end
+
+    # A helper method to register a +sock+ for writable events only.
+    #
+    def register_writable sock
+      register sock, ZMQ::POLLOUT, 0
+    end
+
+    # A helper method to deregister a +sock+ for readable events.
+    #
+    def deregister_readable sock
+      deregister sock, ZMQ::POLLIN, 0
+    end
+
+    # A helper method to deregister a +sock+ for writable events.
+    #
+    def deregister_writable sock
+      deregister sock, ZMQ::POLLOUT, 0
+    end
+
+    # Deletes the +sock+ for all subscribed events.
+    #
+    def delete sock
+      if index = @sockets.index(sock)
+        @items.delete_at index
+        @sockets.delete sock
+        @raw_to_socket.delete sock.socket
+      end
+    end
+
+    def size(); @items.size; end
+
+    def inspect
+      @items.inspect
+    end
+
+    def to_s(); inspect; end
+
+
+    private
+
+    def items_hash
+      hsh = {}
+
+      @items.each do |poll_item|
+        hsh[@raw_to_socket[poll_item.socket]] = poll_item
+      end
+
+      hsh
+    end
+
+    def update_selectables
+      @readables.clear
+      @writables.clear
+
+      @items.each do |poll_item|
+        @readables << @raw_to_socket[poll_item.socket] if poll_item.readable?
+        @writables << @raw_to_socket[poll_item.socket] if poll_item.writable?
+      end
+    end
+
+    # Convert the timeout value to something usable by
+    # the library.
+    #
+    # -1 or :blocking should be converted to -1.
+    #
+    # Users will pass in values measured as
+    # milliseconds, so we need to convert that value to
+    # microseconds for the library.
+    def adjust timeout
+      if :blocking == timeout || -1 == timeout
+        -1
+      else
+        timeout *= 1000
+      end
+    end
+  end
+
+end # module ZMQ

data/lib/ffi-rzmq/poll_items.rb

@@ -0,0 +1,98 @@
+
+module ZMQ
+  class PollItems
+    include Enumerable
+
+    def initialize
+      @element_size = LibZMQ::PollItem.size
+      @store = nil
+      @items = []
+    end
+
+    def size; @items.size; end
+
+    def empty?; @items.empty?; end
+
+    def address
+      clean
+      @store
+    end
+
+    def get index
+      unless @items.empty? || index.nil?
+        clean
+
+        # pointer arithmetic in ruby! whee!
+        pointer = @store + (@element_size * index)
+
+        # cast the memory to a PollItem
+        LibZMQ::PollItem.new pointer
+      end
+    end
+    alias :[] :get
+
+    def <<(obj)
+      @dirty = true
+      @items << obj
+    end
+    alias :push :<<
+    
+    def delete_at index
+      unless @items.empty?
+        @items.delete_at index
+        @dirty = true
+        clean
+      end
+    end
+
+    def each &blk
+      clean
+      index = 0
+      until index >= @items.size do
+        struct = get index
+        yield struct
+        index += 1
+      end
+    end
+
+    def each_with_index &blk
+      clean
+      index = 0
+      until index >= @items.size do
+        struct = get index
+        yield struct, index
+        index += 1
+      end
+    end
+    
+    def inspect
+      clean
+      str = ""
+      each { |item| str << "ptr [#{item[:socket]}], events [#{item[:events]}], revents [#{item[:revents]}], " }
+      str.chop.chop
+    end
+    
+    def to_s(); inspect; end
+
+    private
+
+    # Allocate a contiguous chunk of memory and copy over the PollItem structs
+    # to this block. Note that the old +@store+ value goes out of scope so when
+    # it is garbage collected that native memory should be automatically freed.
+    def clean
+      if @dirty
+        @store = FFI::MemoryPointer.new @element_size, @items.size, false
+
+        # copy over
+        offset = 0
+        @items.each do |item|
+          LibC.memcpy(@store + offset, item, @element_size)
+          offset += @element_size
+        end
+
+        @dirty = false
+      end
+    end
+
+  end # class PollItems
+end # module ZMQ