ffi-rzmq 0.5.1 → 0.6.0

data/.gitignore

@@ -0,0 +1,2 @@
+*.rbc
+*.swp

data/History.txt

@@ -1,3 +1,38 @@
+== 0.6.0 / 20100911
+  * API Change! Modified ZMQ::Message by removing automatic memory
+    management. While doing some performance tests I saw that
+    defining/undefining the finalizer added 15-30% processing 
+    overhead on the latency test. So, I split this functionality
+    out to a subclass called ZMQ::ManagedMemory. Any existing code
+    that relies on the default Message class to clean up after itself
+    will now have a memory leak. Explicitly call #close on these
+    received messages *unless* they are sent out again. The #send
+    method automatically closes call on your behalf.
+
+  * Rubinius/rbx compatibility! Requires an rbx code pull from git
+    from 20100911 or later to get the necessary code fixes.
+  
+  * Modify Message to use the @pointer directly rather than indirectly
+    via the @struct object. Provides better compatibility for rbx
+    since rbx does not yet support the FFI pointer protocol for structs
+    like the FFI gem.
+
+  * Modify Message to pass libC's free function for disposing of message
+    data buffers rather than trying to callback into ruby code to
+    do the same thing. External thread callbacks into ruby code will
+    never be supported in rbx; this also improves compatibility and
+    performance with MRI and JRuby. (In particular, MRI enqueues these
+    kinds of callbacks and spawns a *new* thread to execute each one.
+    Avoiding the ruby callback entirely eliminates this extra work
+    for MRI.)
+
+  * Modify FFI wrapper to capture the libC dynamic library to fetch
+    a pointer to the free function.
+
+  * Modify FFI wrapper to remove the FFI::Function callback used
+    by Message. It's no longer necessary since we now use free 
+    directly.
+
 == 0.5.1 / 20100830
   * Works with 0mq 2.0.8 release.
   

data/README.rdoc

@@ -6,8 +6,8 @@ ffi-rzmq
 
 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. Right now that means
-MRI 1.9.x and JRuby.
+and run by any ruby runtime that supports FFI. That's all of them:
+MRI 1.8.7+, 1.9.x, Rubinius and JRuby.
 
 The impetus behind this library was to provide support for ZeroMQ in
 JRuby which has native threads. Unlike MRI, MacRuby, IronRuby and
@@ -18,31 +18,13 @@ environment to run this library.
 
 == PERFORMANCE
 
-Using FFI introduces some minimal overhead. In my latest benchmarks,
-I was unable to detect any measurable performance drop due to FFI
-regardless of which ruby runtime was tested. JRuby had the best overall
-performance (with --server) once it warmed up. MRI behaved quite well 
-too and has a much lower memory footprint than JRuby (use the trunk
-version of the FFI bindings to fix several threading issues affecting
-MRI).
+Check out the latest performance results:
 
-Due to odd interactions between 0mq threads and the GIL (Giant Interpreter
-Lock), I recommend using JRuby 1.5.1 or later. JRuby has no GIL.
-
-The hope is that in a multi-threaded environment that JRuby's native
-threads and lack of GIL will provide the best ZeroMQ performance using
-the ruby language.
-
-Unfortunately, there is really no reasonable way to support zero-copy
-using Ruby. Any time data needs to be accessible by the Ruby runtime,
-it must be copied out of native memory to the Ruby heap. The same is
-true for the reverse. I am investigating ways to "pin" primitive arrays
-in memory for Rubinius and JRuby to achieve zero-copy, but that is
-a ways off.
+  http://www.zeromq.org/bindings:ruby-ffi
 
 == FEATURES/PROBLEMS:
 
-This gem is brand new and has minimal tests. I'm certain there are a
+This gem needs more tests. I'm certain there are a
 ton of bugs, so please open issues for them here or fork this project,
 fix them, and send me a pull request.
 
@@ -52,10 +34,12 @@ in MRI 1.8.x is irrevocably broken (according to the brains behind the
 Ruby FFI project) so tread carefully.
 
 Running this gem with MRI 1.9.x may also exhibit some hangs particularly at
-shutdown. This is due to a threading interaction between the 0mq library
-and MRI's threads. Apparently MRI does not "adopt" external threads when
-they make a call into the MRI runtime so some deadlocks may occur due to
-the GIL not getting released. Fixes for this should be sent to ruby-core.
+shutdown. This is due to a signaling interaction between the 0mq library
+and MRI. If the 0mq library is blocked on a call and the program receives
+a signal (e.g. SIGINT), the Ruby runtime has no opportunity to run its signal
+handler and process it. The 2.1.x branch of 0mq resolves this problem by
+interrupting the blocking call and returning EINTR. The 2.0.x branch will
+not get this fix because the API change breaks backward compatibility.
 
 All features are implemented with the exception of the 0mq devices
 (forwarder, queue, streamer). For implementations of these devices, see
@@ -79,7 +63,7 @@ Client code:
   message_size = ARGV[1].to_i
   roundtrip_count = ARGV[2].to_i
   
-  ctx = ZMQ::Context.new 1
+  ctx = ZMQ::Context.new
   s = ctx.socket ZMQ::REP
   s.setsockopt(ZMQ::HWM, 100)
   s.bind(bind_to)
@@ -107,7 +91,7 @@ Server code:
   message_size = ARGV[1].to_i
   roundtrip_count = ARGV[2].to_i
   
-  ctx = ZMQ::Context.new 1
+  ctx = ZMQ::Context.new
   s = ctx.socket ZMQ::REQ
   s.connect(connect_to)
   
@@ -123,7 +107,7 @@ Server code:
 
 == REQUIREMENTS:
 
-  * 0mq 2.0.7 or 2.0.8
+  * 0mq 2.0.8 or 2.0.9
   
 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.

data/examples/README.rdoc

@@ -0,0 +1,163 @@
+= Examples
+
+== Requirements
+
+1. Installed gem
+
+All of the examples assume the gem has been successfully installed.
+
+2. Installed libzmq library
+
+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.
+
+3. Two terminal windows
+
+ZeroMQ is used to build network applications. At minimum, there is a "client" application and a "server" application that talk to each other over the network, IPC or an internal thread queue. For the sake of code simplicity, these programs are in separate files and need to be executed in different windows.
+
+== Latency Test
+
+The examples include a latency performance test. The example sets up a pair of REQ/REP sockets and send a message back and forth as fast as possible. There is only a single message in flight at any given moment. The time required to send the message the requested number of times determines overall single-message latency for this type of socket.
+
+==== Files
+
+* local_lat.rb
+* remote_lat.rb
+
+==== Arguments
+
+The remote_lat.rb program takes 3 arguments:
+
+  [bind_to]  Requires a transport string of the format "transport"://"endpoint"<:><port>. For example, tcp://127.0.0.1:5555
+  
+  [message size] Size of each message measured in bytes. Allowable range is 1 to 2^(64-1).
+  
+  [message count] The number of round-trips used for the latency measurements. Allowable range is 1 to 2^(64-1).
+
+
+The local_lat.rb program also takes 3 arguments. They should exactly mirror the arguments given to remote_lat.rb.
+
+  
+==== Execution
+
+In one of the terminals, start up the remote_lat.rb program first. It *must* be launched first so that it can be ready and waiting for the first message sent by the local_lat.rb program.
+
+  % ruby remote_lat.rb tcp://127.0.0.1:5555 1024 100_000
+
+In the second terminal window, start up the local_lat.rb program too.
+
+  % ruby local_lat.rb tcp://127.0.0.1:5555 1024 100_000
+  
+On a relatively new system, it can run 100k messages in under 30 seconds. When complete, the remote_lat.rb program prints out a few statistics and exits. The local_lat.rb program does not print any message when it exits.
+
+Running with a larger "message count" will yield a more accurate latency measurement since nearly all Ruby runtimes require a little warm up time to hit their stride. I recommend 100k as a minimum while 10 million is better for determining a true measure.
+
+On a desktop computer purchased in 2007, all of the Ruby runtimes report a latency of approximately 110 microseconds per message. For comparison, the pure C latency test reports approximately 88 microseconds of latency.
+
+
+
+== Zero Copy Latency Test
+
+The examples include a zero copy latency performance test. The example sets up a pair of REQ/REP sockets and send a message back and forth as fast as possible. There is only a single message in flight at any given moment. The time required to send the message the requested number of times determines overall single-message latency for this type of socket.
+
+The difference between this test and the first latency test has to do with the management of the sent and received messages. This test does not examine or copy the contents of the message at all. Instead, its mere presence is sufficient to echo it back to the other program. Therefore, this test is doing a lot less work for each message send & receive than the first latency test. Also, this test more perfectly mirrors the work being performed by the C latency test.
+
+==== Files
+
+* local_lat_zerocopy.rb
+* remote_lat_zerocopy.rb
+
+==== Arguments
+
+The remote_lat_zerocopy.rb program takes 3 arguments:
+
+  [bind_to]  Requires a transport string of the format "transport"://"endpoint"<:><port>. For example, tcp://127.0.0.1:5555
+  
+  [message size] Size of each message measured in bytes. Allowable range is 1 to 2^(64-1).
+  
+  [message count] The number of round-trips used for the latency measurements. Allowable range is 1 to 2^(64-1).
+
+
+The local_lat_zerocopy.rb program also takes 3 arguments. They should exactly mirror the arguments given to remote_lat_zerocopy.rb.
+
+  
+==== Execution
+
+In one of the terminals, start up the remote_lat_zerocopy.rb program first. It *must* be launched first so that it can be ready and waiting for the first message sent by the local_lat_zerocopy.rb program.
+
+  % ruby remote_lat_zerocopy.rb tcp://127.0.0.1:5555 1024 100_000
+
+In the second terminal window, start up the local_lat.rb program too.
+
+  % ruby local_lat_zerocopy.rb tcp://127.0.0.1:5555 1024 100_000
+  
+On a relatively new system, it can run 100k messages in under 30 seconds. When complete, the remote_lat_zerocopy.rb program prints out a few statistics and exits. The local_lat_zerocopy.rb program does not print any message when it exits.
+
+Running with a larger "message count" will yield a more accurate latency measurement since nearly all Ruby runtimes require a little warm up time to hit their stride. I recommend 100k as a minimum while 10 million is better for determining a true measure.
+
+On a desktop computer purchased in 2007, all of the Ruby runtimes report a latency of approximately 95 microseconds per message. For comparison, the pure C latency test reports approximately 88 microseconds of latency.
+
+
+
+== Throughput Test
+
+The examples include a throughput performance test. The example sets up a pair of PUB/SUB sockets and publish messages as fast as possible to a subscriber listening for every message. The publisher can send much faster than the subscriber can retrieve messages. 
+
+Since the publisher completes first, that program contains a "sleep" statement to keep the program alive and active which gives the subscriber more time to consume the queued messages. When the publisher exits, the socket closes and discards all remaining messages.
+
+The subscriber prints some statistics when it exits.
+
+==== Files
+
+* local_throughput.rb
+* remote_throughput.rb
+
+==== Arguments
+
+The local_throughput.rb program takes 3 arguments:
+
+  [bind_to]  Requires a transport string of the format "transport"://"endpoint"<:><port>. For example, tcp://127.0.0.1:5555
+  
+  [message size] Size of each message measured in bytes. Allowable range is 1 to 2^(64-1).
+  
+  [message count] The number of round-trips used for the latency measurements. Allowable range is 1 to 2^(64-1).
+
+
+The remote_throughput.rb program also takes 3 arguments. They should exactly mirror the arguments given to local_throughput.rb.
+
+  
+==== Execution
+
+In one of the terminals, start up the local_throughput.rb program first. It *must* be launched first so that it can be ready and waiting for the first message published by the remote_throughput.rb program.
+
+  % ruby local_throughput.rb tcp://127.0.0.1:5555 1024 100_000
+
+In the second terminal window, start up the second program.
+
+  % ruby remote_throughput.rb tcp://127.0.0.1:5555 1024 100_000
+  
+On a relatively new system, it can run 100k messages in under 10 seconds. When complete, the local_throughput.rb program prints out a few statistics and exits. The remote_throughput.rb program does not print any message when it exits.
+
+Running with a larger "message count" will yield a more accurate latency measurement since nearly all Ruby runtimes require a little warm up time to hit their stride. I recommend 100k as a minimum while 1 million is better for determining a true measure. NOTE! The publisher can send much faster than the subscriber so the publisher's queue will grow very rapidly in RAM. For 1 million messages (or more) this can consume hundreds of megabytes or gigabytes of RAM. On my system, sending 10 million messages requires 10 GB of RAM before the subscriber can catch up.
+
+On a desktop computer purchased in 2007, all of the Ruby runtimes report a throughput of approximately 150k messages per second. For comparison, the pure C throughput test reports approximately 260k messages per second.
+
+
+
+== Poll
+
+For a reasonable example of using zmq_poll(), take a look at the reqrep_poll.rb program. It illustrates the use of zmq_poll(), as wrapped by the Ruby library, for detecting and responding to read and write events recorded on sockets. It also shows how to use ZMQ::NO_BLOCK for non-blocking send and receive.
+
+==== Files
+
+* reqrep_poll.rb
+
+==== Arguments
+
+None.
+
+==== Execution
+
+This program is completely self-contained, so it only requires a single terminal window for execution.
+
+  % ruby reqrep_poll.rb
+

data/examples/local_throughput.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'ffi-rzmq'
+
+if ARGV.length != 3
+  puts "usage: local_thr <bind-to> <message-size> <message-count>"
+  Process.exit
+end
+
+bind_to = ARGV[0]
+message_size = ARGV[1].to_i
+message_count = ARGV[2].to_i
+
+ctx = ZMQ::Context.new
+s = ZMQ::Socket.new ctx.pointer, ZMQ::SUB
+s.setsockopt ZMQ::SUBSCRIBE, ""
+
+s.bind bind_to
+
+msg = ZMQ::Message.new
+rc = s.recv msg
+
+start_time = Time.now
+
+i = 1
+while i < message_count
+  result_code = s.recv msg
+  i += 1
+end
+
+end_time = Time.now
+
+elapsed = (end_time.to_f - start_time.to_f) * 1000000
+if elapsed == 0
+  elapsed = 1
+end
+
+throughput = message_count * 1000000 / elapsed
+megabits = throughput * message_size * 8 / 1000000
+
+puts "message size: %i [B]" % message_size
+puts "message count: %i" % message_count
+puts "mean throughput: %i [msg/s]" % throughput
+puts "mean throughput: %.3f [Mb/s]" % megabits

data/examples/remote_throughput.rb

@@ -0,0 +1,27 @@
+require 'rubygems'
+require 'ffi-rzmq'
+
+if ARGV.length != 3
+	puts "usage: remote_thr <connect-to> <message-size> <message-count>"
+	Process.exit
+end
+    
+connect_to = ARGV[0]
+message_size = ARGV[1].to_i
+message_count = ARGV[2].to_i
+
+ctx = ZMQ::Context.new
+s = ZMQ::Socket.new ctx.pointer, ZMQ::PUB
+
+s.connect connect_to
+
+contents = "#{'0'*message_size}"
+
+i = 0
+while i < message_count
+  msg = ZMQ::Message.new contents
+	s.send msg
+	i += 1
+end
+
+sleep 10

data/examples/xreqxrep_poll.rb

@@ -73,7 +73,7 @@ until @done do
       reply = "reply " + sock.identity.upcase + " #{time}"
       puts "sent reply [#{reply}], #{time}"
       sock.send_string reply
-      #@done = true
+      @done = true
       poller.register_readable s1
     end
   end

data/ffi-rzmq.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{ffi-rzmq}
-  s.version = "0.5.1"
+  s.version = "0.6.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Chuck Remes"]
-  s.date = %q{2010-08-30}
+  s.date = %q{2010-09-21}
   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. Right now that means
-MRI 1.9.x and JRuby.
+and run by any ruby runtime that supports FFI. That's all of them:
+MRI 1.8.7+, 1.9.x, Rubinius and JRuby.
 
 The impetus behind this library was to provide support for ZeroMQ in
 JRuby which has native threads. Unlike MRI, MacRuby, IronRuby and
@@ -19,20 +19,20 @@ code from outside extensions. ZeroMQ is heavily threaded, so until the
 other runtimes remove their GIL, JRuby will likely be the best
 environment to run this library.}
   s.email = %q{cremes@mac.com}
-  s.extra_rdoc_files = ["History.txt", "README.rdoc", "version.txt"]
-  s.files = [".bnsignore", "History.txt", "README.rdoc", "Rakefile", "examples/async_req_rep.rb", "examples/local_lat.rb", "examples/local_lat_zerocopy.rb", "examples/publish_subscribe.rb", "examples/remote_lat.rb", "examples/remote_lat_zerocopy.rb", "examples/reqrep_poll.rb", "examples/request_response.rb", "examples/t", "examples/xreqxrep_poll.rb", "ffi-rzmq.gemspec", "lib/ffi-rzmq.rb", "lib/ffi-rzmq/context.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/reqrep_spec.rb", "spec/socket_spec.rb", "spec/spec_helper.rb", "version.txt"]
+  s.extra_rdoc_files = ["History.txt", "README.rdoc", "examples/README.rdoc", "version.txt"]
+  s.files = [".gitignore", "History.txt", "README.rdoc", "Rakefile", "examples/README.rdoc", "examples/local_lat.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", "examples/xreqxrep_poll.rb", "ffi-rzmq.gemspec", "lib/ffi-rzmq.rb", "lib/ffi-rzmq/context.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/message_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.6}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{This gem wraps the ZeroMQ networking library using the ruby FFI (foreign function interface)}
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<bones>, [">= 3.4.7"])
     else
       s.add_dependency(%q<bones>, [">= 3.4.7"])

data/lib/ffi-rzmq/context.rb

@@ -11,10 +11,12 @@ module ZMQ
 
     attr_reader :context, :pointer
 
-    # Recommended to just pass 1 for +io_threads+
-    # since most programs are not heavily threaded. The rule of thumb
-    # is to make +io_threads+ equal to the number of application
-    # threads that will be accessing 0mq sockets within this context.
+    # 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.
     #
@@ -23,12 +25,19 @@ module ZMQ
     # 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.
+    # transport and set up a 0mq socket between them. This is also the
+    # recommended technique for allowing sockets to communicate between
+    # threads.
     #
-    # May raise a #ContextError.
+    # Will raise a #ContextError when the native library context cannot be
+    # be allocated.
     #
-    def initialize io_threads
+    def initialize io_threads = 1
       @sockets ||= []
       @context = LibZMQ.zmq_init io_threads
       @pointer = @context
@@ -44,7 +53,8 @@ module ZMQ
     #
     # Returns nil.
     #
-    # May raise a #ContextError.
+    # Will raise a #ContextError when the call fails. Failures occur when
+    # the context has somehow become null (indicates a libzmq bug).
     #
     def terminate
       unless @context.nil? || @context.null?