ffi-rzmq 0.8.2 → 0.9.0

data/lib/ffi-rzmq/device.rb

@@ -1,15 +1,28 @@
 module ZMQ
-  class Device
-    attr_reader :device
-     
-    def initialize(device_type,frontend,backend)
-      [["frontend", frontend],["backend", backend]].each do |name,socket|
-        unless socket.is_a?(ZMQ::Socket)
-          raise ArgumentError, "Expected a ZMQ::Socket, not a #{socket.class} as the #{name}"
+  if LibZMQ.version2?
+    class Device
+      attr_reader :device
+      
+      def self.create(device_type, frontend, backend)
+        dev = nil
+        begin
+          dev = new device_type, frontend, backend
+        rescue ArgumentError
+          dev = nil
         end
+        
+        dev
+      end
+
+      def initialize(device_type,frontend,backend)
+        [["frontend", frontend],["backend", backend]].each do |name,socket|
+          unless socket.is_a?(ZMQ::Socket)
+            raise ArgumentError, "Expected a ZMQ::Socket, not a #{socket.class} as the #{name}"
+          end
+        end
+
+        LibZMQ.zmq_device(device_type, frontend.socket, backend.socket)
       end
-       
-      LibZMQ.zmq_device(device_type, frontend.socket, backend.socket)
     end
   end
 end

data/lib/ffi-rzmq/exceptions.rb

@@ -34,104 +34,6 @@ module ZMQ
   end # class ContextError
 
 
-  class PollError < ZeroMQError
-    # True when the exception was raised due to the library
-    # returning EMTHREAD.
-    #
-    # At least one of the members of the items array refers
-    # to a socket belonging to a different application
-    # thread.
-    #
-    def efault?() EFAULT == @error_code; end
-
-  end # class PollError
-
-
-  class SocketError < ZeroMQError
-    # True when the exception was raised due to the library
-    # returning EMTHREAD.
-    #
-    # Occurs for #send and #recv operations.
-    # * When calling #send, non-blocking mode was requested
-    # and the message cannot be queued at the moment.
-    # * When calling #recv, non-blocking mode was requested
-    # and no messages are available at the moment.
-    #
-    def egain?() EAGAIN == @error_code; end
-
-    # True when the exception was raised due to the library
-    # returning ENOCOMPATPROTO.
-    #
-    # The requested transport protocol is not compatible
-    # with the socket type.
-    #
-    def enocompatproto?() ENOCOMPATPROTO == @error_code; end
-
-    # True when the exception was raised due to the library
-    # returning EPROTONOSUPPORT.
-    #
-    # The requested transport protocol is not supported.
-    #
-    def eprotonosupport?() EPROTONOSUPPORT == @error_code; end
-
-    # True when the exception was raised due to the library
-    # returning EADDRINUSE.
-    #
-    # The given address is already in use.
-    #
-    def eaddrinuse?() EADDRINUSE == @error_code; end
-
-    # True when the exception was raised due to the library
-    # returning EADDRNOTAVAIL.
-    #
-    # A nonexistent interface was requested or the
-    # requested address was not local.
-    #
-    def eaddrnotavail?() EADDRNOTAVAIL == @error_code; end
-
-    # True when the exception was raised due to the library
-    # returning EMTHREAD.
-    #
-    # Occurs under 2 conditions.
-    # * When creating a new #Socket, the requested socket
-    # type is invalid.
-    #
-    # * When setting socket options with #setsockopt, the
-    # requested option +option_name+ is unknown, or the
-    # requested +option_len+ or +option_value+ is invalid.
-    #
-    def einval?() EINVAL == @error_code; end
-
-    # True when the exception was raised due to the library
-    # returning EMTHREAD.
-    #
-    # The send or recv operation cannot be performed on this
-    # socket at the moment due to the socket not being in
-    # the appropriate state. This error may occur with socket
-    # types that switch between several states, such as ZMQ::REP.
-    #
-    def efsm?() EFSM == @error_code; end
-
-    # True when the exception was raised due to the library
-    # returning ENOTSUP.
-    #
-    # The send or recv operation is not supported by this socket
-    # type.
-    #
-    def enotsup?() super; end
-
-    # True when the exception was raised due to the library
-    # returning EMTHREAD.
-    #
-    # The number of application threads using sockets within
-    # this context has been exceeded. See the +app_threads+
-    # parameter of #Context.
-    #
-    def emthread?() EMTHREAD == @error_code; end
-
-  end # class SocketError
-
-
   class MessageError < ZeroMQError
     # True when the exception was raised due to the library
     # returning ENOMEM.

data/lib/ffi-rzmq/libc.rb

@@ -0,0 +1,19 @@
+
+module LibC
+  extend FFI::Library
+  # figures out the correct libc for each platform including Windows
+  library = ffi_lib(FFI::Library::LIBC).first
+
+  # Size_t not working properly on Windows
+  find_type(:size_t) rescue typedef(:ulong, :size_t)
+
+  # memory allocators
+  attach_function :malloc, [: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
+end # module LibC

data/lib/ffi-rzmq/libzmq.rb

@@ -0,0 +1,188 @@
+
+# Wraps the libzmq library and attaches to the functions that are
+# common across the 2.x, 3.x and 4.x APIs.
+#
+module LibZMQ
+  extend FFI::Library
+
+  # bias the library discovery to a path inside the gem first, then
+  # to the usual system paths
+  inside_gem = File.join(File.dirname(__FILE__), '..', '..', 'ext')
+  ZMQ_LIB_PATHS = [
+    inside_gem, '/usr/local/lib', '/opt/local/lib', '/usr/local/homebrew/lib', '/usr/lib64'
+    ].map{|path| "#{path}/libzmq.#{FFI::Platform::LIBSUFFIX}"}
+  ffi_lib(ZMQ_LIB_PATHS + %w{libzmq})
+
+  # Size_t not working properly on Windows
+  find_type(:size_t) rescue typedef(:ulong, :size_t)
+
+  # Context and misc api
+  #
+  # @blocking = true is a hint to FFI that the following (and only the following)
+  # function may block, therefore it should release the GIL before calling it.
+  # This can aid in situations where the function call will/may block and another
+  # thread within the lib may try to call back into the ruby runtime. Failure to
+  # release the GIL will result in a hang; the hint *may* allow things to run
+  # smoothly for Ruby runtimes hampered by a GIL.
+  #
+  # This is really only honored by the MRI implementation but it *is* necessary
+  # otherwise the runtime hangs (and requires a kill -9 to terminate)
+  #
+  @blocking = true
+  attach_function :zmq_init, [:int], :pointer
+  @blocking = true
+  attach_function :zmq_socket, [:pointer, :int], :pointer
+  @blocking = true
+  attach_function :zmq_term, [:pointer], :int
+  @blocking = true
+  attach_function :zmq_errno, [], :int
+  @blocking = true
+  attach_function :zmq_strerror, [:int], :pointer
+  @blocking = true
+  attach_function :zmq_version, [:pointer, :pointer, :pointer], :void
+
+  def self.version
+    unless @version
+      major = FFI::MemoryPointer.new :int
+      minor = FFI::MemoryPointer.new :int
+      patch = FFI::MemoryPointer.new :int
+      LibZMQ.zmq_version major, minor, patch
+      @version = {:major => major.read_int, :minor => minor.read_int, :patch => patch.read_int}
+    end
+
+    @version
+  end
+
+  def self.version2?() version[:major] == 2 && version[:minor] >= 1  end
+
+  def self.version3?() version[:major] == 3 end
+
+  def self.version4?() version[:major] == 4 end
+
+
+  # Message api
+  @blocking = true
+  attach_function :zmq_msg_init, [:pointer], :int
+  @blocking = true
+  attach_function :zmq_msg_init_size, [:pointer, :size_t], :int
+  @blocking = true
+  attach_function :zmq_msg_init_data, [:pointer, :pointer, :size_t, :pointer, :pointer], :int
+  @blocking = true
+  attach_function :zmq_msg_close, [:pointer], :int
+  @blocking = true
+  attach_function :zmq_msg_data, [:pointer], :pointer
+  @blocking = true
+  attach_function :zmq_msg_size, [:pointer], :size_t
+  @blocking = true
+  attach_function :zmq_msg_copy, [:pointer, :pointer], :int
+  @blocking = true
+  attach_function :zmq_msg_move, [:pointer, :pointer], :int
+
+  # Used for casting pointers back to the struct
+  #
+  class Msg < FFI::Struct
+    layout :content,  :pointer,
+    :flags,    :uint8,
+    :vsm_size, :uint8,
+    :vsm_data, [:uint8, 30]
+  end # class Msg
+
+  # Socket api
+  @blocking = true
+  attach_function :zmq_setsockopt, [:pointer, :int, :pointer, :int], :int
+  @blocking = true
+  attach_function :zmq_bind, [:pointer, :string], :int
+  @blocking = true
+  attach_function :zmq_connect, [:pointer, :string], :int
+  @blocking = true
+  attach_function :zmq_close, [:pointer], :int
+
+  # Poll api
+  @blocking = true
+  attach_function :zmq_poll, [:pointer, :int, :long], :int
+
+  module PollItemLayout
+    def self.included(base)
+      base.class_eval do
+        layout :socket,  :pointer,
+        :fd,    :int,
+        :events, :short,
+        :revents, :short
+      end
+    end
+  end # module PollItemLayout
+
+  class PollItem < FFI::Struct
+    include PollItemLayout
+
+    def socket() self[:socket]; end
+
+    def readable?
+      (self[:revents] & ZMQ::POLLIN) > 0
+    end
+
+    def writable?
+      (self[:revents] & ZMQ::POLLOUT) > 0
+    end
+
+    def both_accessible?
+      readable? && writable?
+    end
+
+    def inspect
+      "socket [#{socket}], fd [#{self[:fd]}], events [#{self[:events]}], revents [#{self[:revents]}]"
+    end
+
+    def to_s; inspect; end
+  end # class PollItem
+
+end
+
+
+# Attaches to those functions specific to the 2.x API
+#
+if LibZMQ.version2?
+
+  module LibZMQ
+    # Socket api
+    @blocking = true
+    attach_function :zmq_getsockopt, [:pointer, :int, :pointer, :pointer], :int
+    @blocking = true
+    attach_function :zmq_recv, [:pointer, :pointer, :int], :int
+    @blocking = true
+    attach_function :zmq_send, [:pointer, :pointer, :int], :int
+    @blocking = true
+    attach_function :zmq_device, [:int, :pointer, :pointer], :int
+  end
+end
+
+
+# Attaches to those functions specific to the 3.x API
+#
+if LibZMQ.version3? || LibZMQ.version4?
+
+  module LibZMQ
+    # Socket api
+    @blocking = true
+    attach_function :zmq_getsockopt, [:pointer, :int, :pointer, :pointer], :int
+    @blocking = true
+    attach_function :zmq_recvmsg, [:pointer, :pointer, :int], :int
+    @blocking = true
+    attach_function :zmq_recv, [:pointer, :pointer, :size_t, :int], :int
+    @blocking = true
+    attach_function :zmq_sendmsg, [:pointer, :pointer, :int], :int
+    @blocking = true
+    attach_function :zmq_send, [:pointer, :pointer, :size_t, :int], :int
+  end
+end
+
+
+# Sanity check; print an error and exit if we are trying to load an unsupported
+# version of libzmq.
+#
+unless LibZMQ.version2? || LibZMQ.version3? || LibZMQ.version4?
+  hash = LibZMQ.version
+  version = "#{hash[:major]}.#{hash[:minor]}.#{hash[:patch]}"
+  STDERR.puts "Unable to load this gem. The libzmq version #{version} is incompatible with ffi-rzmq."
+  exit 255
+end

data/lib/ffi-rzmq/message.rb

@@ -1,21 +1,12 @@
 
 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
+  # 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 have *not* passed this on
-  # to Socket#send. That method calls #close on your behalf.
+  # 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
@@ -37,8 +28,17 @@ module ZMQ
   # 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.
+  #  received_message = Message.create
+  #  if received_message
+  #    rc = socket.recv(received_message)
+  #    if ZMQ::Util.resultcode_ok?(rc)
+  #      puts "Message contained: #{received_message.copy_out_string}"
+  #    else
+  #      STDERR.puts "Error when receiving message: #{ZMQ::Util.error_string}"
+  #    end
+  #
+  #
+  # Define a custom layout for the data sent between 0mq peers.
   #
   #  class MyMessage
   #    class Layout < FFI::Struct
@@ -85,6 +85,13 @@ module ZMQ
   #
   class Message
     include ZMQ::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
       @state = :uninitialized
@@ -99,7 +106,7 @@ module ZMQ
       else
         # initialize an empty message structure to receive a message
         result_code = LibZMQ.zmq_msg_init @pointer
-        error_check ZMQ_MSG_INIT_STR, result_code
+        raise unless Util.resultcode_ok?(result_code)
       end
     end
 
@@ -109,9 +116,6 @@ module ZMQ
     #
     # 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
       string_size = string.respond_to?(:bytesize) ? string.bytesize : string.size
       copy_in_bytes string, string_size if string
@@ -122,12 +126,7 @@ module ZMQ
     #
     # 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
-      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
@@ -135,10 +134,7 @@ module ZMQ
       # 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
-
-      error_check ZMQ_MSG_INIT_DATA_STR, result_code
-      @state = :initialized
+      LibZMQ.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
@@ -151,15 +147,11 @@ module ZMQ
     alias :pointer :address
 
     def copy source
-      result_code = LibZMQ.zmq_msg_copy @pointer, source.address
-      error_check ZMQ_MSG_COPY_STR, result_code
-      @state = :initialized
+      LibZMQ.zmq_msg_copy @pointer, source.address
     end
 
     def move source
-      result_code = LibZMQ.zmq_msg_copy @pointer, source.address
-      error_check ZMQ_MSG_MOVE_STR, result_code
-      @state = :initialized
+      LibZMQ.zmq_msg_move @pointer, source.address
     end
 
     # Provides the size of the data buffer for this +zmq_msg_t+ C struct.
@@ -192,17 +184,16 @@ module ZMQ
     # no ops.
     #
     def close
+      rc = 0
+      
       if @pointer
-        LibZMQ.zmq_msg_close @pointer
+        rc = LibZMQ.zmq_msg_close @pointer
         @pointer = nil
       end
+      
+      rc
     end
 
-
-    private
-
-    def initialized?(); :initialized == @state; end
-
   end # class Message
 
 
@@ -237,19 +228,21 @@ module ZMQ
     # handles deallocation of the native memory buffer.
     #
     def copy_in_bytes bytes, len
-      super
+      rc = super
       
       # 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
-      super
+      rc = super
       remove_finalizer
+      rc
     end