ffi-rxs 1.1.0 → 1.2.0

data/lib/ffi-rxs/message.rb~

@@ -1,282 +0,0 @@
-
-module XS
-
-  # The factory 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 are done with the data.
-  #
-  # (This class is not really zero-copy. Ruby makes this near impossible
-  # since Ruby objects can be relocated in memory by the GC at any
-  # time. There is no way to peg them to native memory or have them
-  # use non-movable native memory as backing store.)
-  #
-  # Message represents ruby equivalent of the +xs_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, call #close to
-  # release the associated buffers.
-  #
-  #  received_message = Message.create
-  #  if received_message
-  #    rc = socket.recvmsg(received_message)
-  #    if XS::Util.resultcode_ok?(rc)
-  #      puts "Message contained: #{received_message.copy_out_string}"
-  #    else
-  #      STDERR.puts "Error when receiving message: #{XS::Util.error_string}"
-  #    end
-  #
-  #
-  # Define a custom layout for the data sent between Crossroads peers.
-  #
-  #  class MyMessage
-  #    class Layout < FFI::Struct
-  #      layout :value1, :uint8,
-  #             :value2, :uint64,
-  #             :value3, :uint32,
-  #             :value4, [:char, 30]
-  #    end
-  #
-  #    def initialize msg_struct = nil
-  #      if msg_struct
-  #        @msg_t = msg_struct
-  #        @data = Layout.new(@msg_t.data)
-  #      else
-  #        @pointer = FFI::MemoryPointer.new :byte, Layout.size, true
-  #        @data = Layout.new @pointer
-  #      end
-  #    end
-  #
-  #    def size() @size = @msg_t.size; end
-  #
-  #    def value1
-  #      @data[:value1]
-  #    end
-  #
-  #    def value4
-  #      @data[:value4].to_ptr.read_string
-  #    end
-  #
-  #    def value1=(val)
-  #      @data[:value1] = val
-  #    end
-  #
-  #    def create_sendable_message
-  #      msg = Message.new
-  #      msg.copy_in_bytes @pointer, Layout.size
-  #    end
-  #
-  #
-  #  message = Message.new
-  #  successful_read = socket.recv message
-  #  message = MyMessage.new message if successful_read
-  #  puts "value1 is #{message.value1}"
-  #
-  class Message
-    include XS::Util
-    
-    # Recommended way to create a standard message. A Message object is 
-    # returned upon success, nil when allocation fails.
-    #
-    def self.create message = nil
-      new(message) rescue nil
-    end
-
-    def initialize message = nil
-      # 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 Message.msg_size, 1, false
-
-      if message
-        copy_in_string message
-      else
-        # initialize an empty message structure to receive a message
-        result_code = LibXS.xs_msg_init @pointer
-        raise unless Util.resultcode_ok?(result_code)
-      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.
-    #
-    # Can only be initialized via #copy_in_string or #copy_in_bytes once.
-    #
-    def copy_in_string string
-      string_size = string.respond_to?(:bytesize) ? string.bytesize : string.size
-      copy_in_bytes string, string_size if string
-    end
-
-    # Makes a copy of +len+ bytes from the ruby string +bytes+. Library
-    # handles deallocation of the native memory buffer.
-    #
-    # Can only be initialized via #copy_in_string or #copy_in_bytes once.
-    #
-    def copy_in_bytes bytes, len
-      data_buffer = LibC.malloc len
-      # writes the exact number of bytes, no null byte to terminate string
-      data_buffer.write_string bytes, len
-
-      # use libC to call free on the data buffer; earlier versions used an
-      # FFI::Function here that called back into Ruby, but Rubinius won't 
-      # support that and there are issues with the other runtimes too
-      LibXS.zmq_msg_init_data @pointer, data_buffer, len, LibC::Free, nil
-    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
-      @pointer
-    end
-    alias :pointer :address
-
-    def copy source
-      LibXS.xs_msg_copy @pointer, source
-    end
-
-    def move source
-      LibXS.xs_msg_move @pointer, source
-    end
-
-    # Provides the size of the data buffer for this +zmq_msg_t+ C struct.
-    #
-    def size
-      LibZMQ.xs_msg_size @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
-      LibXS.xs_msg_data @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.
-    #
-    # Only releases the buffer a single time. Subsequent calls are
-    # no ops.
-    #
-    def close
-      rc = 0
-      
-      if @pointer
-        rc = LibXS.xs_msg_close @pointer
-        @pointer = nil
-      end
-      
-      rc
-    end
-    
-    # cache the msg size so we don't have to recalculate it when creating
-    # each new instance
-    @msg_size = LibXS::Msg.size
-    
-    def self.msg_size() @msg_size; end
-
-  end # class Message
-
-
-
-  # A subclass of #Message that includes finalizers for deallocating
-  # native memory when this object is garbage collected. Note that on
-  # certain Ruby runtimes the use of finalizers can add 10s of
-  # microseconds of overhead for each message. The convenience comes
-  # at a price.
-  #
-  # 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. That method calls #close on your behalf.
-  #
-  # 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 ManagedMessage < Message
-    # 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
-      rc = super(bytes, len)
-      
-      # make sure we have a way to deallocate this memory if the object goes
-      # out of scope
-      define_finalizer
-      rc
-    end
-
-    # Manually release the message struct and its associated data
-    # buffer.
-    #
-    def close
-      rc = super()
-      remove_finalizer
-      rc
-    end
-
-
-    private
-
-    def define_finalizer
-      ObjectSpace.define_finalizer(self, self.class.close(@pointer))
-    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 ptr
-      Proc.new do
-        # release the data buffer
-        LibXS.zmq_msg_close ptr
-      end
-    end
-
-    # cache the msg size so we don't have to recalculate it when creating
-    # each new instance
-    # need to do this again because ivars are not inheritable
-    @msg_size = LibXS::Msg.size
-
-  end # class ManagedMessage
-
-end # module XS

data/lib/ffi-rxs/poll.rb~

@@ -1,212 +0,0 @@
-
-module XS
-
-  class Poller
-    include XS::Util
-
-    attr_reader :readables, :writables
-
-    def initialize
-      @items = XS::PollItems.new
-      @raw_to_socket = {}
-      @sockets = []
-      @readables = []
-      @writables = []
-    end
-
-    # Checks each registered socket 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.
-    #
-    # This method will return *immediately* when there are no registered
-    # sockets. In that case, the +timeout+ parameter is not honored. To
-    # prevent a CPU busy-loop, the caller of this method should detect
-    # this possible condition (via #size) and throttle the call
-    # frequency.
-    #
-    # Returns 0 when there are no registered sockets that are readable
-    # or writable. 
-    # 
-    # Return 1 (or greater) to indicate the number of readable or writable
-    # sockets. These sockets should be processed using the #readables and
-    # #writables accessors.
-    #
-    # Returns -1 when there is an error. Use ZMQ::Util.errno to get the related
-    # error number.
-    #
-    def poll timeout = :blocking
-      unless @items.empty?
-        timeout = adjust timeout
-        items_triggered = LibXS.xs_poll @items.address, @items.size, timeout
-        
-        if Util.resultcode_ok?(items_triggered)
-          update_selectables
-        end
-        
-        items_triggered
-      else
-        0
-      end
-    end
-
-    # The non-blocking version of #poll. See the #poll description for
-    # potential exceptions.
-    #
-    # May return -1 when an error is encounted. Check ZMQ::Util.errno
-    # to determine the underlying cause.
-    #
-    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.
-    #
-    def register sock, events = XS::POLLIN | XS::POLLOUT, fd = 0
-      return false if (sock.nil? && fd.zero?) || events.zero?
-
-      item = @items.get(@sockets.index(sock))
-
-      unless item
-        @sockets << sock
-        item = LibXS::PollItem.new
-
-        if sock.kind_of?(XS::Socket) || sock.kind_of?(Socket)
-          item[:socket] = sock.socket
-          item[:fd] = 0
-        else
-          item[:socket] = FFI::MemoryPointer.new(0)
-          item[:fd] = fd
-        end
-
-        @raw_to_socket[item.socket.address] = sock
-        @items << item
-      end
-
-      item[:events] |= events
-    end
-
-    # Deregister the +sock+ for +events+. When there are no events left,
-    # this also deletes the socket from the poll items.
-    #
-    def deregister sock, events, fd = 0
-      return unless sock || !fd.zero?
-
-      item = @items.get(@sockets.index(sock))
-
-      if item && (item[:events] & events) > 0
-        # change the value in place
-        item[:events] ^= events
-
-        delete sock if item[:events].zero?
-        true
-      else
-        false
-      end
-    end
-
-    # A helper method to register a +sock+ as readable events only.
-    #
-    def register_readable sock
-      register sock, XS::POLLIN, 0
-    end
-
-    # A helper method to register a +sock+ for writable events only.
-    #
-    def register_writable sock
-      register sock, XS::POLLOUT, 0
-    end
-
-    # A helper method to deregister a +sock+ for readable events.
-    #
-    def deregister_readable sock
-      deregister sock, XS::POLLIN, 0
-    end
-
-    # A helper method to deregister a +sock+ for writable events.
-    #
-    def deregister_writable sock
-      deregister sock, XS::POLLOUT, 0
-    end
-
-    # Deletes the +sock+ for all subscribed events. Called internally
-    # when a socket has been deregistered and has no more events
-    # registered anywhere.
-    #
-    # Can also be called directly to remove the socket from the polling
-    # array.
-    #
-    def delete sock
-      unless (size = @sockets.size).zero?
-        @sockets.delete_if { |socket| socket.socket.address == sock.socket.address }
-        socket_deleted = size != @sockets.size
-
-        item_deleted = @items.delete sock
-
-        raw_deleted = @raw_to_socket.delete(sock.socket.address)
-
-        socket_deleted && item_deleted && raw_deleted
-        
-      else
-        false
-      end
-    end
-
-    def size(); @items.size; end
-
-    def inspect
-      @items.inspect
-    end
-
-    def to_s(); inspect; end
-
-
-    private
-
-    def items_hash hash
-      @items.each do |poll_item|
-        hash[@raw_to_socket[poll_item.socket.address]] = poll_item
-      end
-    end
-
-    def update_selectables
-      @readables.clear
-      @writables.clear
-
-      @items.each do |poll_item|
-        #FIXME: spec for sockets *and* file descriptors
-        if poll_item.readable?
-          @readables << (poll_item.socket.address.zero? ? poll_item.fd : @raw_to_socket[poll_item.socket.address])
-        end
-        
-        if poll_item.writable?
-          @writables << (poll_item.socket.address.zero? ? poll_item.fd : @raw_to_socket[poll_item.socket.address])
-        end
-      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.to_i
-      end
-    end
-  end
-
-end # module XS

data/lib/ffi-rxs/poll_items.rb~

@@ -1,120 +0,0 @@
-
-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 sock
-      address = sock.socket.address
-      found = false
-      
-      each_with_index do |item, index|
-        if address == item[:socket].address
-          @items.delete_at index
-          found = true
-          @dirty = true
-          clean
-          break
-        end
-      end
-      
-      # these semantics are different from the usual Array#delete; returns a
-      # boolean instead of the actual item or nil
-      found
-    end
-    
-    def delete_at index
-      value = nil
-      unless @items.empty?
-        value = @items.delete_at index
-        @dirty = true
-        clean
-      end
-      
-      value
-    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, true
-
-        # copy over
-        offset = 0
-        @items.each do |item|
-          LibC.memcpy(@store + offset, item.pointer, @element_size)
-          offset += @element_size
-        end
-
-        @dirty = false
-      end
-    end
-
-  end # class PollItems
-end # module ZMQ