ffi-rzmq 0.9.0 → 0.9.2

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+
+*.rbc
+.redcar/

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/History.txt

@@ -1,3 +1,34 @@
+== 0.9.2 / 20111115
+  * Removed all references to the version4 API.
+  
+  * Dropped support for 3.0.x and added support for 3.1.x. The 0mq
+    community has pretty much voted to abandon the path taken in 3.0
+    so the 3.1 branch is the API that will be supported.
+    
+  * Fixed a bug in Poller#delete where it would erroneously return
+    false even when it successfully deleted a socket. Issue 46.
+    
+  * All specs pass for 2.1.x API.
+  
+  * 3 specs fail when run with 3.1 API; these are due to bugs in the
+    0mq library and are *not* ffi-rzmq bugs.
+    
+  * Rescue LoadErrors when loading libzmq. Print a warning about
+    adding libzmq.dll to the Windows PATH for that platform. Print
+    the search paths where the gem looks for libzmq.
+
+== 0.9.1 / 20111027
+  * Moved LibC and LibZMQ into the ZMQ module namespace. Necessary to
+    avoid namespace collisions with other libraries that also use
+    the constants LibC and/or LibZMQ.
+    
+  * Fixed a bug where file descriptors registered on Poll were never 
+    returned as readable or writable.
+    
+  * Added Socket#recv_multipart. This returns the message body and
+    return address envelope as separate arrays. Only to be used with
+    XREQ/XREP/DEALER/ROUTER sockets.
+
 == 0.9.0 / 20110930
   * Changed the behavior of every method that used to produce exceptions.
     The methods now behave more like the C API functions. They return

data/README.rdoc

@@ -9,10 +9,11 @@ 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.
 
-This single gem supports 0mq 2.x and 3.x 0mq APIs. The 0mq project started
-making backward-incompatible changes to the API with the 3.x release.
+This single gem supports 0mq 2.x and 3.1.x 0mq APIs. The 0mq project started
+making backward-incompatible changes to the API with the 3.1.x release.
 The gem auto-configures itself to expose the API conforming to the loaded
-C library.
+C library. 0mq API 3.0 is *not* supported; the 0mq community voted to
+abandon it. 
 
 The impetus behind this library was to provide support for ZeroMQ in
 JRuby which has native threads. Unlike MRI, which has a GIL, JRuby and
@@ -25,9 +26,12 @@ JRuby and Rubinius will likely be the best environments to run this library.
 There has been a major change in API from the 0.8.x series to 0.9.0. 
 Previously the Socket#send and Socket#recv methods could raise exceptions
 when there was an error. They also returned true or false depending on
-the success of failure of the operation. Mixing and matching return codes
-and exceptions is a terrible idea in practice, so all of the exception
-code from Socket has been removed.
+the success or failure of the operation. The exceptions were also used
+for managing flow control when doing non-blocking send/recv.
+
+Mixing and matching return codes and exceptions is a terrible idea in 
+practice. Using them for flow control is an even worse sin. So all of 
+the exception code from Socket has been removed.
 
 The Poller and Message class have also had their exceptions removed for
 returning errors on instance methods.
@@ -42,9 +46,11 @@ constructed object or nil. Code should check for nil returns before using
 the object.
 
 This is a *breaking* change. I'm sorry but the old API's inconsistency was
-causing too many problems. It now more closely mimics the 0mq C API. If you
-prefer the original API, it should be relatively simple to wrap these
-classes up to provide the original API.
+causing too many problems. It now more closely mimics the 0mq C API. IF YOU
+PREFER THE ORIGINAL API WHICH WAS CLOSER TO IDIOMATIC RUBY, IT SHOULD BE
+EASY TO WRAP THESE CLASSES UP TO PROVIDE A MORE IDIOMATIC API. I SUGGEST
+YOU CREATE A PATCH *OR* CREATE A SEPARATE GEM TO WRAP THIS ONE. Sorry for
+shouting but I wanted to make sure this stood out.
 
 All example code has been updated to use the new Ruby API.
 
@@ -135,7 +141,7 @@ I highly recommend visiting the Learn Ruby 0mq project for a bunch of good code
 
 == REQUIREMENTS:
 
-  * 0mq 2.1.x or later; 2.0.x is no longer supported
+  * 0mq 2.1.x, 3.1.x or later; 2.0.x and 3.0.x are no longer supported
   
 The ZeroMQ library must be installed on your system in a well-known location
 like /usr/local/lib. This is the default for new ZeroMQ installs.
@@ -167,7 +173,11 @@ To build from git master:
  % gem build ffi-rzmq.gemspec
  % gem install ffi-rzmq-*.gem
  
- 
+
+NOTE for Windows users!
+In order for this gem to find the libzmq.dll, it *must* be on the Windows PATH. Google
+for "modify windows path" for instructions on how to do that if you are unfamiliar with
+that activity.
 
 == LICENSE:
 

data/Rakefile

@@ -1,38 +1,6 @@
-begin
-  require 'bones'
-rescue LoadError
-  abort '### Please install the "bones" gem ###'
-end
-
-namespace :win do
-
-  desc 'Build and install gem under Windows. Mr Bones just has to break things using tar.'
-  task :install do
-    PKG_PATH = File.join(File.dirname(__FILE__), 'pkg')
-    NAME = File.basename(File.dirname(__FILE__))
-    rm_rf PKG_PATH
-    system "gem build #{NAME}.gemspec"
-    mkdir_p PKG_PATH
-    mv "#{NAME}-*.gem", PKG_PATH
-    system "gem install #{PKG_PATH}/#{NAME}-*.gem"
-  end
-end
+require 'bundler/gem_tasks'
 
 require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new
 
 task :default => :spec
-
-Bones {
-  name 'ffi-rzmq'
-  authors 'Chuck Remes'
-  email 'cremes@mac.com'
-  url 'http://github.com/chuckremes/ffi-rzmq'
-  readme_file 'README.rdoc'
-  ruby_opts.clear # turn off warnings
-  
-  # necessary for MRI; unnecessary for JRuby and RBX
-  # can't enable this until JRuby & RBX have a way of dealing with it cleanly
-  #depend_on 'ffi', '>= 1.0.0'
-}
-

data/examples/README.rdoc

@@ -10,7 +10,7 @@ All of the examples assume the lib directory containing the gem sources is two d
 
 The ZeroMQ C libraries need to be downloaded, compiled and installed separately from the gem. Please see http://www.zeromq.org/area:download for links to the downloadable files along with some simple installation instructions. Also, be sure to check the FAQ if you run into problems with compiling.
 
-This gem auto-configures itself to conform to the API for 0mq 2.1.x, 3.x and 4.x. The 0mq project started making backward-incompatible changes with the 3.x branch. Rather than create separate gems, this one handles all of them.
+This gem auto-configures itself to conform to the API for 0mq 2.1.x and 3.1.x. The 0mq project started making backward-incompatible changes with the 3.x branch. Rather than create separate gems, this one handles all of them.
 
 It is possible to install the libzmq* files directly into the gem in the ext/ directory. This directory is checked for loadable libraries first before it falls back to checking the system paths.
 

data/examples/v2api/latency_measurement.rb

@@ -0,0 +1,139 @@
+
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'ffi-rzmq')
+
+
+# Within a single process, we start up two threads. One thread has a REQ (request)
+# socket and the second thread has a REP (reply) socket. We measure the
+# *round-trip* latency between these sockets. Only *one* message is in flight at
+# any given moment.
+#
+# 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 latency_measurement.rb tcp://127.0.0.1:5555 1024 1_000_000
+#
+#  % ruby latency_measurement.rb inproc://lm_sock 1024 1_000_000
+#
+
+if ARGV.length < 3
+  puts "usage: ruby latency_measurement.rb <connect-to> <message-size> <roundtrip-count>"
+  exit
+end
+
+link = ARGV[0]
+message_size = ARGV[1].to_i
+roundtrip_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
+    @context = context
+    @link = link
+    @size = size
+    @count = count
+
+    begin
+      @socket = @context.socket(ZMQ::REP)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate REP socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(ZMQ::LINGER, 100))
+
+    assert(@socket.setsockopt(ZMQ::HWM, 100))
+
+    assert(@socket.bind(@link))
+  end
+
+  def run
+    @count.times do
+      string = ''
+      assert(@socket.recv_string(string, 0))
+
+      raise "Message size doesn't match, expected [#{@size}] but received [#{string.size}]" if @size != string.size
+
+      assert(@socket.send_string(string, 0))
+    end
+
+    assert(@socket.close)
+  end
+end
+
+class Transmitter
+  def initialize context, link, size, count
+    @context = context
+    @link = link
+    @size = size
+    @count = count
+
+    begin
+      @socket = @context.socket(ZMQ::REQ)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate REP socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(ZMQ::LINGER, 100))
+
+    assert(@socket.setsockopt(ZMQ::HWM, 100))
+
+    assert(@socket.connect(@link))
+  end
+
+  def run
+    msg = "#{ '3' * @size }"
+
+    elapsed = elapsed_microseconds do
+      @count.times do
+        assert(@socket.send_string(msg, 0))
+        assert(@socket.recv_string(msg, 0))
+
+        raise "Message size doesn't match, expected [#{@size}] but received [#{msg.size}]" if @size != msg.size
+      end
+    end
+
+    latency = elapsed / @count / 2
+
+    puts "message size: %i [B]" % @size
+    puts "roundtrip count: %i" % @count
+    puts "throughput (msgs/s): %i" % (@count / (elapsed / 1_000_000))
+    puts "mean latency: %.3f [us]" % latency
+    assert(@socket.close)
+  end
+
+  def elapsed_microseconds(&blk)
+    start = Time.now
+    yield
+    value = ((Time.now - start) * 1_000_000)
+  end
+end
+
+threads = []
+threads << Thread.new do
+  receiver = Receiver.new(master_context, link, message_size, roundtrip_count)
+  receiver.run
+end
+
+sleep 1
+
+threads << Thread.new do
+  transmitter = Transmitter.new(master_context, link, message_size, roundtrip_count)
+  transmitter.run
+end
+
+threads.each {|t| t.join}
+
+master_context.terminate

data/examples/v2api/xreqxrep_poll.rb

@@ -0,0 +1,93 @@
+
+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::XREQ)
+  s2 = ctx.socket(ZMQ::XREP)
+rescue ContextError => e
+  STDERR.puts "Failed to allocate context or socket"
+  raise
+end
+
+s1.identity = 'socket1.xreq'
+s2.identity = 'socket2.xrep'
+
+assert(s1.setsockopt(ZMQ::LINGER, 100))
+assert(s2.setsockopt(ZMQ::LINGER, 100))
+
+assert(s1.bind(link))
+assert(s2.connect(link))
+
+poller = ZMQ::Poller.new
+poller.register_readable(s2)
+poller.register_writable(s1)
+
+start_time = Time.now
+@unsent = true
+
+until @done do
+  assert(poller.poll_nonblock)
+
+  # send the message after 5 seconds
+  if Time.now - start_time > 5 && @unsent
+    puts "sending payload nonblocking"
+
+    5.times do |i|
+      payload = "#{ i.to_s * 40 }"
+      assert(s1.send_string(payload, ZMQ::NOBLOCK))
+    end
+    @unsent = false
+  end
+
+  # check for messages after 1 second
+  if Time.now - start_time > 1
+    poller.readables.each do |sock|
+
+      if sock.identity =~ /xrep/
+        routing_info = ''
+        assert(sock.recv_string(routing_info, ZMQ::NOBLOCK))
+        puts "routing_info received [#{routing_info}] on socket.identity [#{sock.identity}]"
+      else
+        routing_info = nil
+        received_msg = ''
+        assert(sock.recv_string(received_msg, ZMQ::NOBLOCK))
+
+        # skip to the next iteration if received_msg is nil; that means we got an EAGAIN
+        next unless received_msg
+        puts "message received [#{received_msg}] on socket.identity [#{sock.identity}]"
+      end
+
+      while sock.more_parts? do
+        received_msg = ''
+        assert(sock.recv_string(received_msg, ZMQ::NOBLOCK))
+
+        puts "message received [#{received_msg}]"
+      end
+
+      puts "kick back a reply"
+      assert(sock.send_string(routing_info, ZMQ::SNDMORE | ZMQ::NOBLOCK)) if routing_info
+      time = Time.now.strftime "%Y-%m-%dT%H:%M:%S.#{Time.now.usec}"
+      reply = "reply " + sock.identity.upcase + " #{time}"
+      puts "sent reply [#{reply}], #{time}"
+      assert(sock.send_string(reply))
+      @done = true
+      poller.register_readable(s1)
+    end
+  end
+end
+
+puts "executed in [#{Time.now - start_time}] seconds"
+
+assert(s1.close)
+assert(s2.close)
+
+ctx.terminate

data/examples/v3api/latency_measurement.rb

@@ -0,0 +1,139 @@
+
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'ffi-rzmq')
+
+
+# Within a single process, we start up two threads. One thread has a REQ (request)
+# socket and the second thread has a REP (reply) socket. We measure the
+# *round-trip* latency between these sockets. Only *one* message is in flight at
+# any given moment.
+#
+# 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 latency_measurement.rb tcp://127.0.0.1:5555 1024 1_000_000
+#
+#  % ruby latency_measurement.rb inproc://lm_sock 1024 1_000_000
+#
+
+if ARGV.length < 3
+  puts "usage: ruby latency_measurement.rb <connect-to> <message-size> <roundtrip-count>"
+  exit
+end
+
+link = ARGV[0]
+message_size = ARGV[1].to_i
+roundtrip_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
+    @context = context
+    @link = link
+    @size = size
+    @count = count
+
+    begin
+      @socket = @context.socket(ZMQ::REP)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate REP socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(ZMQ::LINGER, 100))
+    assert(@socket.setsockopt(ZMQ::RCVHWM, 100))
+    assert(@socket.setsockopt(ZMQ::SNDHWM, 100))
+
+    assert(@socket.bind(@link))
+  end
+
+  def run
+    @count.times do
+      string = ''
+      assert(@socket.recv_string(string, 0))
+
+      raise "Message size doesn't match, expected [#{@size}] but received [#{string.size}]" if @size != string.size
+
+      assert(@socket.send_string(string, 0))
+    end
+
+    assert(@socket.close)
+  end
+end
+
+class Transmitter
+  def initialize context, link, size, count
+    @context = context
+    @link = link
+    @size = size
+    @count = count
+
+    begin
+      @socket = @context.socket(ZMQ::REQ)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate REP socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(ZMQ::LINGER, 100))
+    assert(@socket.setsockopt(ZMQ::RCVHWM, 100))
+    assert(@socket.setsockopt(ZMQ::SNDHWM, 100))
+
+    assert(@socket.connect(@link))
+  end
+
+  def run
+    msg = "#{ '3' * @size }"
+
+    elapsed = elapsed_microseconds do
+      @count.times do
+        assert(@socket.send_string(msg, 0))
+        assert(@socket.recv_string(msg, 0))
+
+        raise "Message size doesn't match, expected [#{@size}] but received [#{msg.size}]" if @size != msg.size
+      end
+    end
+
+    latency = elapsed / @count / 2
+
+    puts "message size: %i [B]" % @size
+    puts "roundtrip count: %i" % @count
+    puts "throughput (msgs/s): %i" % (@count / (elapsed / 1_000_000))
+    puts "mean latency: %.3f [us]" % latency
+    assert(@socket.close)
+  end
+
+  def elapsed_microseconds(&blk)
+    start = Time.now
+    yield
+    value = ((Time.now - start) * 1_000_000)
+  end
+end
+
+threads = []
+threads << Thread.new do
+  receiver = Receiver.new(master_context, link, message_size, roundtrip_count)
+  receiver.run
+end
+
+sleep 1
+
+threads << Thread.new do
+  transmitter = Transmitter.new(master_context, link, message_size, roundtrip_count)
+  transmitter.run
+end
+
+threads.each {|t| t.join}
+
+master_context.terminate