ffi-rzmq 0.8.2 → 0.9.0

data/examples/v3api/request_response.rb

@@ -0,0 +1,40 @@
+
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'ffi-rzmq')
+
+
+def assert(rc)
+  raise "Last API call failed at #{caller(1)}" unless rc >= 0
+end
+
+link = "tcp://127.0.0.1:5555"
+
+begin
+  ctx = ZMQ::Context.new
+  s1 = ctx.socket(ZMQ::REQ)
+  s2 = ctx.socket(ZMQ::REP)
+rescue ContextError => e
+  STDERR.puts "Failed to allocate context or socket"
+  raise
+end
+
+assert(s1.setsockopt(ZMQ::LINGER, 100))
+assert(s2.setsockopt(ZMQ::LINGER, 100))
+
+assert(s2.bind(link))
+assert(s1.connect(link))
+
+payload = "#{ '3' * 2048 }"
+sent_msg = ZMQ::Message.new(payload)
+received_msg = ZMQ::Message.new
+
+assert(s1.sendmsg(sent_msg))
+assert(s2.recvmsg(received_msg))
+
+result = payload == received_msg.copy_out_string ? "Request received" : "Received wrong payload"
+
+p result
+
+assert(s1.close)
+assert(s2.close)
+
+ctx.terminate

data/examples/v3api/throughput_measurement.rb

@@ -0,0 +1,166 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'ffi-rzmq')
+require 'thread'
+
+# Within a single process, we start up five threads. Main thread has a PUB (publisher)
+# socket and the secondary threads have SUB (subscription) sockets. We measure the
+# *throughput* between these sockets. A high-water mark (HWM) is *not* set, so the
+# publisher queue is free to grow to the size of memory without dropping packets.
+#
+# This example also illustrates how a single context can be shared amongst several
+# threads. Sharing a single context also allows a user to specify the "inproc"
+# transport in addition to "tcp" and "ipc".
+#
+#  % ruby throughput_measurement.rb tcp://127.0.0.1:5555 1024 1_000_000
+#
+#  % ruby throughput_measurement.rb inproc://lm_sock 1024 1_000_000
+#
+
+if ARGV.length < 3
+  puts "usage: ruby throughput_measurement.rb <connect-to> <message-size> <roundtrip-count>"
+  exit
+end
+
+link = ARGV[0]
+message_size = ARGV[1].to_i
+count = ARGV[2].to_i
+
+def assert(rc)
+  raise "Last API call failed at #{caller(1)}" unless rc >= 0
+end
+
+begin
+  master_context = ZMQ::Context.new
+rescue ContextError => e
+  STDERR.puts "Failed to allocate context or socket!"
+  raise
+end
+
+
+class Receiver
+  def initialize context, link, size, count, stats
+    @context = context
+    @link = link
+    @size = size
+    @count = count
+    @stats = stats
+
+    begin
+      @socket = @context.socket(ZMQ::SUB)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate SUB socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(ZMQ::LINGER, 100))
+    assert(@socket.setsockopt(ZMQ::SUBSCRIBE, ""))
+
+    assert(@socket.connect(@link))
+  end
+
+  def run
+    msg = ZMQ::Message.new
+    assert(@socket.recvmsg(msg))
+
+    elapsed = elapsed_microseconds do
+      (@count - 1).times do
+        assert(@socket.recvmsg(msg))
+      end
+    end
+
+    @stats.record_elapsed(elapsed)
+    assert(@socket.close)
+  end
+
+  def elapsed_microseconds(&blk)
+    start = Time.now
+    yield
+    ((Time.now - start) * 1_000_000)
+  end
+end
+
+class Transmitter
+  def initialize context, link, size, count
+    @context = context
+    @link = link
+    @size = size
+    @count = count
+
+    begin
+      @socket = @context.socket(ZMQ::PUB)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate PUB socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(ZMQ::LINGER, 100))
+    assert(@socket.bind(@link))
+  end
+
+  def run
+    sleep 1
+    contents = "#{'0' * @size}"
+
+    i = 0
+    while i < @count
+      msg = ZMQ::Message.new(contents)
+      assert(@socket.sendmsg(msg))
+      i += 1
+    end
+
+  end
+  
+  def close
+    assert(@socket.close)
+  end
+end
+
+class Stats
+  def initialize size, count
+    @size = size
+    @count = count
+    
+    @mutex = Mutex.new
+    @elapsed = []
+  end
+
+  def record_elapsed(elapsed)
+    @mutex.synchronize do
+      @elapsed << elapsed
+    end
+  end
+
+  def output
+    @elapsed.each do |elapsed|
+      throughput = @count * 1000000 / elapsed
+      megabits = throughput * @size * 8 / 1000000
+
+      puts "message size: %i [B]" % @size
+      puts "message count: %i" % @count
+      puts "mean throughput: %i [msg/s]" % throughput
+      puts "mean throughput: %.3f [Mb/s]" % megabits
+      puts
+    end
+  end
+end
+
+threads = []
+stats = Stats.new message_size, count
+transmitter = Transmitter.new(master_context, link, message_size, count)
+
+threads << Thread.new do
+  transmitter.run
+end
+
+1.times do
+  threads << Thread.new do
+    receiver = Receiver.new(master_context, link, message_size, count, stats)
+    receiver.run
+  end
+end
+
+
+threads.each {|t| t.join}
+transmitter.close
+stats.output
+
+master_context.terminate

data/ext/README

@@ -0,0 +1,5 @@
+To avoid loading a system-wide 0mq library, place
+the C libraries here. This let's you run your Ruby
+code with a 0mq C library build that is different
+from the system-wide one. This can be handy for
+rolling upgrades or testing.

data/ffi-rzmq.gemspec

@@ -2,24 +2,24 @@
 
 Gem::Specification.new do |s|
   s.name = %q{ffi-rzmq}
-  s.version = "0.8.2"
+  s.version = "0.9.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Chuck Remes"]
-  s.date = %q{2011-01-30}
+  s.date = %q{2011-09-14}
   s.description = %q{This gem wraps the ZeroMQ networking library using the ruby FFI (foreign
 function interface). It's a pure ruby wrapper so this gem can be loaded
 and run by any ruby runtime that supports FFI. That's all of them:
 MRI 1.9.x, Rubinius and JRuby.}
   s.email = %q{cremes@mac.com}
   s.extra_rdoc_files = ["AUTHORS.txt", "History.txt", "README.rdoc", "examples/README.rdoc", "version.txt"]
-  s.files = [".bnsignore", "History.txt", "README.rdoc", "Rakefile", "examples/README.rdoc", "examples/local_lat.rb", "examples/local_lat_poll.rb", "examples/local_lat_zerocopy.rb", "examples/local_throughput.rb", "examples/publish_subscribe.rb", "examples/remote_lat.rb", "examples/remote_lat_zerocopy.rb", "examples/remote_throughput.rb", "examples/reqrep_poll.rb", "examples/request_response.rb", "ffi-rzmq.gemspec", "lib/ffi-rzmq.rb", "lib/ffi-rzmq/context.rb", "lib/ffi-rzmq/device.rb", "lib/ffi-rzmq/exceptions.rb", "lib/ffi-rzmq/message.rb", "lib/ffi-rzmq/poll.rb", "lib/ffi-rzmq/poll_items.rb", "lib/ffi-rzmq/socket.rb", "lib/ffi-rzmq/wrapper.rb", "lib/ffi-rzmq/zmq.rb", "spec/context_spec.rb", "spec/device_spec.rb", "spec/message_spec.rb", "spec/pushpull_spec.rb", "spec/reqrep_spec.rb", "spec/socket_spec.rb", "spec/spec_helper.rb", "version.txt"]
+  s.files = [".bnsignore", "History.txt", "README.rdoc", "Rakefile", "examples/README.rdoc", "examples/v2api/local_lat.rb", "examples/v2api/local_lat_poll.rb", "examples/v2api/local_throughput.rb", "examples/v2api/publish_subscribe.rb", "examples/v2api/remote_lat.rb", "examples/v2api/remote_throughput.rb", "examples/v2api/reqrep_poll.rb", "examples/v2api/request_response.rb", "examples/v2api/throughput_measurement.rb", "examples/v3api/local_lat.rb", "examples/v3api/local_lat_poll.rb", "examples/v3api/local_throughput.rb", "examples/v3api/publish_subscribe.rb", "examples/v3api/remote_lat.rb", "examples/v3api/remote_throughput.rb", "examples/v3api/reqrep_poll.rb", "examples/v3api/request_response.rb", "examples/v3api/throughput_measurement.rb", "ext/README", "ffi-rzmq.gemspec", "lib/ffi-rzmq.rb", "lib/ffi-rzmq/constants.rb", "lib/ffi-rzmq/context.rb", "lib/ffi-rzmq/device.rb", "lib/ffi-rzmq/exceptions.rb", "lib/ffi-rzmq/libc.rb", "lib/ffi-rzmq/libzmq.rb", "lib/ffi-rzmq/message.rb", "lib/ffi-rzmq/poll.rb", "lib/ffi-rzmq/poll_items.rb", "lib/ffi-rzmq/socket.rb", "lib/ffi-rzmq/util.rb", "spec/context_spec.rb", "spec/device_spec.rb", "spec/message_spec.rb", "spec/multipart_spec.rb", "spec/nonblocking_recv_spec.rb", "spec/pushpull_spec.rb", "spec/reqrep_spec.rb", "spec/socket_spec.rb", "spec/spec_helper.rb", "version.txt"]
   s.homepage = %q{http://github.com/chuckremes/ffi-rzmq}
   s.rdoc_options = ["--main", "README.rdoc"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{ffi-rzmq}
   s.rubygems_version = %q{1.3.7}
-  s.summary = %q{This gem wraps the ZeroMQ networking library using the ruby FFI (foreign function interface).}
+  s.summary = %q{This gem wraps the ZeroMQ (0mq) networking library using Ruby FFI (foreign function interface).}
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION

data/lib/ffi-rzmq.rb

@@ -66,7 +66,10 @@ end  # module ZMQ
 
 RBX = defined?(RUBY_ENGINE) && RUBY_ENGINE =~ /rbx/ ? true : false
 
+require 'ffi' unless RBX
+
 # the order of files is important
-%w(wrapper zmq exceptions context message socket poll_items poll device).each do |file|
+#%w(wrapper zmq exceptions context message socket poll_items poll device).each do |file|
+%w(libc libzmq constants util exceptions context message socket poll_items poll device).each do |file|
   require ZMQ.libpath(['ffi-rzmq', file])
 end

data/lib/ffi-rzmq/constants.rb

@@ -0,0 +1,178 @@
+module ZMQ
+  # Set up all of the constants that are *common* to all API
+  # versions
+  
+  #  Socket types
+  PAIR = 0
+  PUB = 1
+  SUB = 2
+  REQ = 3
+  REP = 4
+  XREQ = 5
+  XREP = 6
+  PULL = 7
+  PUSH = 8
+
+  SocketTypeNameMap = {
+    PAIR => "PAIR",
+    PUB => "PUB",
+    SUB => "SUB",
+    REQ => "REQ",
+    REP => "REP",
+    PULL => "PULL",
+    PUSH => "PUSH",
+    XREQ => "XREQ",
+    XREP => "XREP"
+  }
+
+  #  Socket options
+  AFFINITY = 4
+  SUBSCRIBE = 6
+  UNSUBSCRIBE = 7
+  RATE = 8
+  RECOVERY_IVL = 9
+  SNDBUF = 11
+  RCVBUF = 12
+  RCVMORE = 13
+  FD = 14
+  EVENTS = 15
+  TYPE = 16
+  LINGER = 17
+  RECONNECT_IVL = 18
+  BACKLOG = 19
+  RECONNECT_IVL_MAX = 21
+
+  #  Send/recv options
+  SNDMORE = 2
+
+  #  I/O multiplexing
+
+  POLL = 1
+  POLLIN = 1
+  POLLOUT = 2
+  POLLERR = 4
+
+  #  Socket errors
+  EAGAIN = Errno::EAGAIN::Errno
+  EINVAL = Errno::EINVAL::Errno
+  ENOMEM = Errno::ENOMEM::Errno
+  ENODEV = Errno::ENODEV::Errno
+  EFAULT = Errno::EFAULT::Errno
+
+  # ZMQ errors
+  HAUSNUMERO     = 156384712
+  EMTHREAD       = (HAUSNUMERO + 50)
+  EFSM           = (HAUSNUMERO + 51)
+  ENOCOMPATPROTO = (HAUSNUMERO + 52)
+  ETERM          = (HAUSNUMERO + 53)
+
+  # Rescue unknown constants and use the ZeroMQ defined values
+  # Usually only happens on Windows though some don't resolve on
+  # OSX too (ENOTSUP)
+  ENOTSUP         = Errno::ENOTSUP::Errno rescue (HAUSNUMERO + 1)
+  EPROTONOSUPPORT = Errno::EPROTONOSUPPORT::Errno rescue (HAUSNUMERO + 2)
+  ENOBUFS         = Errno::ENOBUFS::Errno rescue (HAUSNUMERO + 3)
+  ENETDOWN        = Errno::ENETDOWN::Errno rescue (HAUSNUMERO + 4)
+  EADDRINUSE      = Errno::EADDRINUSE::Errno rescue (HAUSNUMERO + 5)
+  EADDRNOTAVAIL   = Errno::EADDRNOTAVAIL::Errno rescue (HAUSNUMERO + 6)
+  ECONNREFUSED    = Errno::ECONNREFUSED::Errno rescue (HAUSNUMERO + 7)
+  EINPROGRESS     = Errno::EINPROGRESS::Errno rescue (HAUSNUMERO + 8)
+  ENOTSOCK        = Errno::ENOTSOCK::Errno rescue (HAUSNUMERO + 9)
+  EINTR           = Errno::EINTR::Errno rescue (HAUSNUMERO + 10)
+end # module ZMQ
+
+
+if LibZMQ.version2?
+  module ZMQ
+    # Socket types
+    UPSTREAM = PULL
+    DOWNSTREAM = PUSH
+    DEALER = XREQ
+    ROUTER = XREP
+
+    SocketTypeNameMap[ROUTER] = 'ROUTER'
+    SocketTypeNameMap[DEALER] = 'DEALER'
+
+    #  Device Types
+    STREAMER = 1
+    FORWARDER = 2
+    QUEUE = 3
+
+    # Socket options
+    HWM = 1
+    IDENTITY = 5
+    MCAST_LOOP = 10
+    SWAP = 3
+    RECOVERY_IVL_MSEC = 20
+
+    # Send/recv options
+    NOBLOCK = 1
+  end
+end # version2?
+
+
+if LibZMQ.version3?
+  module ZMQ
+    # Socket types
+    XPUB = 9
+    XSUB = 10
+    ROUTER = 11
+    DEALER = 12
+
+    SocketTypeNameMap[ROUTER] = 'ROUTER'
+    SocketTypeNameMap[DEALER] = 'DEALER'
+    SocketTypeNameMap[XPUB] = 'XPUB'
+    SocketTypeNameMap[XSUB] = 'XSUB'
+
+    # Socket options
+    IDENTITY = 5
+    MAXMSGSIZE = 22
+    SNDHWM = 23
+    RCVHWM = 24
+    MULTICAST_HOPS = 25
+    RCVTIMEO = 27
+    SNDTIMEO = 28
+    RCVLABEL = 29
+
+    # Send/recv options
+    DONTWAIT = 1
+    SNDLABEL = 4
+
+
+    # Socket & other errors
+    EMFILE = Errno::EMFILE::Errno
+
+  end
+end # version3?
+
+
+if LibZMQ.version4?
+  module ZMQ
+    # Socket types
+    XPUB = 9
+    XSUB = 10
+    ROUTER = 13
+
+    SocketTypeNameMap[ROUTER] = 'ROUTER'
+    SocketTypeNameMap[XPUB] = 'XPUB'
+    SocketTypeNameMap[XSUB] = 'XSUB'
+
+    # Socket options
+    MAXMSGSIZE = 22
+    SNDHWM = 23
+    RCVHWM = 24
+    MULTICAST_HOPS = 25
+    RCVTIMEO = 27
+    SNDTIMEO = 28
+    RCVLABEL = 29
+
+    # Send/recv options
+    DONTWAIT = 1
+    SNDLABEL = 4
+
+
+    # Socket & other errors
+    EMFILE = Errno::EMFILE::Errno
+
+  end
+end # version4?

data/lib/ffi-rzmq/context.rb

@@ -1,70 +1,82 @@
 
 module ZMQ
 
-  ZMQ_INIT_STR = 'zmq_init'.freeze
-  ZMQ_TERM_STR = 'zmq_term'.freeze
-  ZMQ_SOCKET_STR = 'zmq_socket'.freeze unless defined? ZMQ_SOCKET_STR
-
 
+  # Recommended to use the default for +io_threads+
+  # since most programs will not saturate I/O. 
+  #
+  # The rule of thumb is to make +io_threads+ equal to the number 
+  # gigabits per second that the application will produce.
+  #
+  # The +io_threads+ number specifies the size of the thread pool
+  # allocated by 0mq for processing incoming/outgoing messages.
+  #
+  # Returns a context object when allocation succeeds. It's necessary
+  # for passing to the
+  # #Socket constructor when allocating new sockets. All sockets
+  # live within a context.
+  #
+  # Also, Sockets should *only* be accessed from the thread where they
+  # were first created. Do *not* pass sockets between threads; pass
+  # in the context and allocate a new socket per thread. If you must
+  # use threads, then make sure to execute a full memory barrier (e.g.
+  # mutex) as you pass a socket from one thread to the next.
+  #
+  # To connect sockets between contexts, use +inproc+ or +ipc+
+  # transport and set up a 0mq socket between them. This is also the
+  # recommended technique for allowing sockets to communicate between
+  # threads.
+  #
+  #  context = ZMQ::Context.create
+  #  if context
+  #    socket = context.socket(ZMQ::REQ)
+  #    if socket
+  #      ...
+  #    else
+  #      STDERR.puts "Socket allocation failed"
+  #    end
+  #  else
+  #    STDERR.puts "Context allocation failed"
+  #  end
+  #
+  #
   class Context
     include ZMQ::Util
 
     attr_reader :context, :pointer
 
-    # Recommended to use the default for +io_threads+
-    # since most programs will not saturate I/O. 
-    #
-    # The rule of thumb is to make +io_threads+ equal to the number 
-    # gigabits per second that the application will produce.
-    #
-    # The +io_threads+ number specifies the size of the thread pool
-    # allocated by 0mq for processing incoming/outgoing messages.
-    #
-    # Returns a context object. It's necessary for passing to the
-    # #Socket constructor when allocating new sockets. All sockets
-    # live within a context. Sockets in one context may not be accessed
-    # from another context; doing so raises an exception.
-    #
-    # Also, Sockets should *only* be accessed from the thread where they
-    # were first created. Do *not* pass sockets between threads; pass
-    # in the context and allocate a new socket per thread.
-    #
-    # To connect sockets between contexts, use +inproc+ or +ipc+
-    # transport and set up a 0mq socket between them. This is also the
-    # recommended technique for allowing sockets to communicate between
-    # threads.
-    #
-    # Will raise a #ContextError when the native library context cannot be
-    # be allocated.
+    def self.create io_threads = 1
+      new(io_threads) rescue nil
+    end
+    
+    # Use the factory method Context#create to make contexts.
     #
     def initialize io_threads = 1
       @sockets = []
       @context = LibZMQ.zmq_init io_threads
       @pointer = @context
-      error_check ZMQ_INIT_STR, (@context.nil? || @context.null?) ? 1 : 0
+      error_check 'zmq_init', (@context.nil? || @context.null?) ? -1 : 0
 
       define_finalizer
     end
 
     # Call to release the context and any remaining data associated
     # with past sockets. This will close any sockets that remain
-    # open; further calls to those sockets will raise failure
-    # exceptions.
-    #
-    # Returns nil.
+    # open; further calls to those sockets will return -1 to indicate
+    # the operation failed.
     #
-    # Will raise a #ContextError when the call fails. Failures occur when
-    # the context has somehow become null (indicates a libzmq bug).
+    # Returns 0 for success, -1 for failure.
     #
     def terminate
       unless @context.nil? || @context.null?
-        result_code = LibZMQ.zmq_term @context
-        error_check ZMQ_TERM_STR, result_code
+        remove_finalizer
+        rc = LibZMQ.zmq_term @context
         @context = nil
         @sockets = nil
-        remove_finalizer
+        rc
+      else
+        0
       end
-      nil
     end
 
     # Short-cut to allocate a socket for a specific context.
@@ -80,13 +92,17 @@ module ZMQ
     #   #ZMQ::DEALER
     #   #ZMQ::ROUTER
     #
-    # Returns a #ZMQ::Socket.
-    #
-    # May raise a #ContextError or #SocketError.
+    # Returns a #ZMQ::Socket when the allocation succeeds, nil
+    # if it fails.
     #
     def socket type
-      sock = Socket.new @context, type
-      error_check ZMQ_SOCKET_STR, sock.nil? ? 1 : 0
+      sock = nil
+      begin
+        sock = Socket.new @context, type
+      rescue ContextError => e
+        sock = nil
+      end
+      
       sock
     end