ffi-rzmq 0.5.1 → 0.6.0

data/lib/ffi-rzmq/message.rb

@@ -15,10 +15,12 @@ module ZMQ
   # 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.
+  # to Socket#send. That method calls #close on your behalf.
   #
-  # (This class is not really zero-copy. Ruby makes this near impossible.)
+  # (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 +zmq_msg_t+ C struct.
   # Access the underlying memory buffer and the buffer size using the
@@ -32,41 +34,54 @@ module ZMQ
   # 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.
+  # When you are done using a *received* message object, call #close to
+  # release the associated buffers.
   #
   # As noted above, for sent objects the underlying library will call close
   # for you.
   #
   #  class MyMessage
+  #    class Layout < FFI::Struct
+  #      layout :value1, :uint8,
+  #             :value2, :uint64,
+  #             :value3, :uint32,
+  #             :value4, [:char, 30]
+  #    end
+  #
   #    def initialize msg_struct = nil
-  #      @msg_t = msg_struct ? msg_struct : ZMQ::Message.new
+  #      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 decode
-  #      @decoded_data = JSON.parse(@msg_t.copy_out_string)
+  #    def value1
+  #      @data[:value1]
   #    end
   #
-  #    def field1
-  #      @field1 ||= decode[:field1]
+  #    def value4
+  #      @data[:value4].to_ptr.read_string
   #    end
   #
-  #    def field2
-  #      @field2 ||= decode[:field2]
+  #    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 "field1 is #{message.field1}"
+  #  puts "value1 is #{message.value1}"
   #
   class Message
     include ZMQ::Util
@@ -84,9 +99,8 @@ module ZMQ
         copy_in_string message
       else
         # initialize an empty message structure to receive a message
-        result_code = LibZMQ.zmq_msg_init @struct
+        result_code = LibZMQ.zmq_msg_init @pointer
         error_check ZMQ_MSG_INIT_STR, result_code
-        @state = :initialized
       end
     end
 
@@ -94,6 +108,11 @@ module ZMQ
     # 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.
+    #
+    # Can raise a MessageError when #copy_in_string or #copy_in_bytes is
+    # called multiple times on the same instance. 
+    #
     def copy_in_string string
       copy_in_bytes string, string.size if string
     end
@@ -101,25 +120,23 @@ module ZMQ
     # 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.
+    #
+    # Can raise a MessageError when #copy_in_string or #copy_in_bytes is
+    # called multiple times on the same instance. 
+    #
     def copy_in_bytes bytes, len
-      # release any associated buffers if this Message object is being
-      # reused
-      close unless uninitialized? # FIXME: this is a bug waiting to happen
+      raise MessageError.new "#{self}", -1, -1, "This object cannot be reused; allocate a new one!" if initialized?
 
       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
+      # 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
+      result_code = LibZMQ.zmq_msg_init_data @pointer, data_buffer, len, LibC::Free, nil
 
-      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
@@ -129,18 +146,18 @@ module ZMQ
     # require a real data address.
     #
     def address
-      @struct.pointer
+      @pointer
     end
     alias :pointer :address
 
     def copy source
-      result_code = LibZMQ.zmq_msg_copy @struct.pointer, source.address
+      result_code = LibZMQ.zmq_msg_copy @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
+      result_code = LibZMQ.zmq_msg_copy @pointer, source.address
       error_check ZMQ_MSG_MOVE_STR, result_code
       @state = :initialized
     end
@@ -148,7 +165,7 @@ module ZMQ
     # Provides the size of the data buffer for this +zmq_msg_t+ C struct.
     #
     def size
-      LibZMQ.zmq_msg_size @struct.pointer
+      LibZMQ.zmq_msg_size @pointer
     end
 
     # Returns a pointer to the data buffer.
@@ -157,7 +174,7 @@ module ZMQ
     # collected.
     #
     def data
-      LibZMQ.zmq_msg_data @struct.pointer
+      LibZMQ.zmq_msg_data @pointer
     end
 
     # Returns the data buffer as a string.
@@ -171,22 +188,69 @@ module ZMQ
     # 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 @pointer
+    end
+
+
+    private
+
+    def initialized?(); :initialized == @state; 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
+      super
+      
+      # make sure we have a way to deallocate this memory if the object goes
+      # out of scope
+      define_finalizer
+    end
+
+    # Manually release the message struct and its associated data
+    # buffer.
     #
     def close
-      LibZMQ.zmq_msg_close @struct.pointer
+      super
       remove_finalizer
-      @state = :uninitialized
     end
 
 
     private
 
-    def uninitialized?(); :uninitialized == @state; end
-
     def define_finalizer
-      ObjectSpace.define_finalizer(self, self.class.close(@struct))
+      ObjectSpace.define_finalizer(self, self.class.close(@pointer))
     end
 
     def remove_finalizer
@@ -198,13 +262,13 @@ module ZMQ
     # 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
+    def self.close ptr
       Proc.new do
         # release the data buffer
-        LibZMQ.zmq_msg_close struct.pointer
+        LibZMQ.zmq_msg_close ptr
       end
     end
 
-  end # class Message
+  end # class ManagedMessage
 
 end # module ZMQ

data/lib/ffi-rzmq/poll_items.rb

@@ -86,7 +86,7 @@ module ZMQ
         # copy over
         offset = 0
         @items.each do |item|
-          LibC.memcpy(@store + offset, item, @element_size)
+          LibC.memcpy(@store + offset, item.pointer, @element_size)
           offset += @element_size
         end
 

data/lib/ffi-rzmq/socket.rb

@@ -13,29 +13,38 @@ module ZMQ
   class Socket
     include ZMQ::Util
 
-    attr_reader :socket
+    attr_reader :socket, :name
 
-    # By default, this class uses ZMQ::Message for regular Ruby
-    # memory management.
+    # Allocates a socket of type +type+ for sending and receiving data.
     #
     # +type+ can be one of ZMQ::REQ, ZMQ::REP, ZMQ::PUB,
     # ZMQ::SUB, ZMQ::PAIR, ZMQ::PULL, ZMQ::PUSH,
     # ZMQ::XREQ or ZMQ::XREP.
     #
+    # By default, this class uses ZMQ::Message for manual
+    # memory management. For automatic garbage collection of received messages,
+    # it is possible to override the :receiver_class to use ZMQ::ManagedMessage.
+    #
+    #  sock = Socket.new(Context.new, ZMQ::REQ, :receiver_class => ZMQ::ManagedMessage)
+    #
+    # Advanced users may want to replace the receiver class with their 
+    # own custom class. The custom class must conform to the same public API
+    # as ZMQ::Message.
+    #
     # Can raise two kinds of exceptions depending on the error.
     # ContextError:: Raised when a socket operation is attempted on a terminated
     # #Context. See #ContextError.
     # SocketError:: See all of the possibilities in the docs for #SocketError.
     #
-    def initialize context_ptr, type
-      # maybe at some point we'll want to allow users to override this with their
-      # own classes? Or is this a YAGNI mistake?
-      @sender_klass = ZMQ::Message
-      @receiver_klass = ZMQ::Message
+    def initialize context_ptr, type, opts = {:receiver_class => ZMQ::Message}
+      # users may override the classes used for receiving; class must conform to the
+      # same public API as ZMQ::Message
+      @receiver_klass = opts[:receiver_class]
 
       unless context_ptr.null?
         @socket = LibZMQ.zmq_socket context_ptr, type
         error_check ZMQ_SOCKET_STR, @socket.null? ? 1 : 0
+        @name = SocketTypeNameMap[type]
       else
         raise ContextError.new ZMQ_SOCKET_STR, 0, ETERM, "Context pointer was null"
       end
@@ -64,15 +73,18 @@ module ZMQ
     # SocketError:: See all of the possibilities in the docs for #SocketError.
     #
     def setsockopt option_name, option_value, option_len = nil
+      option_value = sanitize_value option_name, option_value
+      option_len ||= option_value.size
+      
       begin
         case option_name
-        when HWM, SWAP, AFFINITY, RATE, RECOVERY_IVL, MCAST_LOOP
-          option_value_ptr = LibC.malloc option_value.size
+        when HWM, SWAP, AFFINITY, RATE, RECOVERY_IVL, MCAST_LOOP, SNDBUF, RCVBUF
+          option_value_ptr = LibC.malloc option_len
           option_value_ptr.write_long option_value
 
         when IDENTITY, SUBSCRIBE, UNSUBSCRIBE
           # note: not checking errno for failed memory allocations :(
-          option_value_ptr = LibC.malloc option_value.size
+          option_value_ptr = LibC.malloc option_len
           option_value_ptr.write_string option_value
 
         else
@@ -81,7 +93,7 @@ module ZMQ
           error_check ZMQ_SETSOCKOPT_STR, EINVAL
         end
 
-        result_code = LibZMQ.zmq_setsockopt @socket, option_name, option_value_ptr, option_len || option_value.size
+        result_code = LibZMQ.zmq_setsockopt @socket, option_name, option_value_ptr, option_len
         error_check ZMQ_SETSOCKOPT_STR, result_code
       ensure
         LibC.free option_value_ptr unless option_value_ptr.nil? || option_value_ptr.null?
@@ -188,8 +200,8 @@ module ZMQ
     error_check ZMQ_CLOSE_STR, result_code
   end
 
-  # Queues the message for transmission. Message is assumed to be an instance or
-  # subclass of #Message.
+  # Queues the message for transmission. Message is assumed to conform to the
+  # same public API as #Message.
   #
   # +flags+ may take two values:
   # * 0 (default) - blocking operation
@@ -197,13 +209,14 @@ module ZMQ
   # * ZMQ::SNDMORE - this message is part of a multi-part message
   #
   # Returns true when the message was successfully enqueued.
-  # Returns false when the message could not be enqueued *and* +flags+ is set
-  # with ZMQ::NOBLOCK.
+  # Returns false under two conditions.
+  # 1. The message could not be enqueued
+  # 2. When +flags+ is set with ZMQ::NOBLOCK and the socket returned EAGAIN.
   #
   # The application code is *not* responsible for handling the +message+ object
-  # lifecycle when #send return ZMQ::NOBLOCK or it raises an exception. The
+  # lifecycle when #send returns successfully or it raises an exception. The
   # #send method takes ownership of the +message+ and its associated buffers.
-  # A failed call will release the +message+ data buffer.
+  # Both successful and failed calls will release the +message+ data buffer.
   #
   # Again, once a +message+ object has been passed to this method,
   # do not try to access its #data buffer anymore. The 0mq library now owns it.
@@ -239,7 +252,7 @@ module ZMQ
   # SocketError:: See all of the possibilities in the docs for #SocketError.
   #
   def send_string message_string, flags = 0
-    message = @sender_klass.new
+    message = Message.new
     message.copy_in_string message_string
     result = send message, flags
     result
@@ -327,6 +340,17 @@ module ZMQ
       [FFI::MemoryPointer.new(255), length]
     end
   end
+  
+  def sanitize_value option_name, option_value
+    case option_name
+    when HWM, AFFINITY, SNDBUF, RCVBUF
+      option_value.abs
+    when MCAST_LOOP
+      option_value ? 1 : 0
+    else
+      option_value
+    end
+  end
 
   def define_finalizer
     ObjectSpace.define_finalizer(self, self.class.close(@socket))

data/lib/ffi-rzmq/wrapper.rb

@@ -3,7 +3,7 @@ require 'ffi' unless RBX # external gem
 module LibC
   extend FFI::Library
   # figures out the correct libc for each platform including Windows
-  ffi_lib FFI::Library::LIBC unless RBX
+  library = ffi_lib(FFI::Library::LIBC).first
 
   # memory allocators
   attach_function :malloc, [:size_t], :pointer
@@ -11,6 +11,9 @@ module LibC
   attach_function :valloc, [:size_t], :pointer
   attach_function :realloc, [:pointer, :size_t], :pointer
   attach_function :free, [:pointer], :void
+  
+  # get a pointer to the free function; used for ZMQ::Message deallocation
+  Free = library.find_symbol('free')
 
   # memory movers
   attach_function :memcpy, [:pointer, :pointer, :size_t], :pointer
@@ -46,12 +49,6 @@ module LibZMQ
   attach_function :zmq_msg_copy, [:pointer, :pointer], :int
   attach_function :zmq_msg_move, [:pointer, :pointer], :int
 
-  unless RBX
-    MessageDeallocator = FFI::Function.new(:void, [:pointer, :pointer]) do |data_ptr, hint_ptr|
-      LibC.free data_ptr
-    end
-    MessageDeallocator.autorelease = false
-  end
 
   # Used for casting pointers back to the struct
   class Msg < FFI::Struct

data/lib/ffi-rzmq/zmq.rb

@@ -11,6 +11,18 @@ module ZMQ
   XREP = 6
   PULL = UPSTREAM = 7
   PUSH = DOWNSTREAM = 8
+  
+  SocketTypeNameMap = {
+    PAIR => "PAIR",
+    PUB => "PUB",
+    SUB => "SUB",
+    REQ => "REQ",
+    REP => "REP",
+    XREQ => "XREQ",
+    XREP => "XREP",
+    PULL => "PULL",
+    PUSH => "PUSH"
+  }
 
   #  Socket options
   HWM = 1
@@ -120,18 +132,19 @@ module ZMQ
     # send/recv. True only when #errno is EGAIN and +result_code+ is non-zero.
     #
     def error_check_nonblock result_code
-      queue_operation = eagain? && !result_code.zero? ? false : true
-      queue_operation
+      !result_code.zero? && eagain? ? false : true
     end
 
     def raise_error source, result_code
       case source
-      when ZMQ_SOCKET_STR, ZMQ_SETSOCKOPT_STR, ZMQ_GETSOCKOPT_STR, ZMQ_BIND_STR, ZMQ_CONNECT_STR, ZMQ_SEND_STR, ZMQ_RECV_STR
+      when ZMQ_SEND_STR, ZMQ_RECV_STR, ZMQ_SOCKET_STR, ZMQ_SETSOCKOPT_STR, ZMQ_GETSOCKOPT_STR, ZMQ_BIND_STR, ZMQ_CONNECT_STR
         raise SocketError.new source, result_code, errno, error_string
       when ZMQ_INIT_STR, ZMQ_TERM_STR
         raise ContextError.new source, result_code, errno, error_string
       when ZMQ_POLL_STR
         raise PollError.new source, result_code, errno, error_string
+      when ZMQ_MSG_INIT_STR, ZMQ_MSG_INIT_DATA_STR, ZMQ_MSG_COPY_STR, ZMQ_MSG_MOVE_STR
+        raise MessageError.new source, result_code, errno, error_string
       else
         raise ZeroMQError.new source, result_code, -1, 
         "Source [#{source}] does not match any zmq_* strings, rc [#{result_code}], errno [#{errno}], error_string [#{error_string}]"