ffi-rxs 1.0.0 → 1.0.1

data/examples/throughput_measurement.rb

@@ -0,0 +1,169 @@
+# encoding: utf-8
+
+# throughput_measurement.rb
+
+# 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
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+require 'thread'
+
+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 = XS::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(XS::SUB)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate SUB socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(XS::LINGER, 100))
+    assert(@socket.setsockopt(XS::SUBSCRIBE, ""))
+
+    assert(@socket.connect(@link))
+  end
+
+  def run
+    msg = XS::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(XS::PUB)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate PUB socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(XS::LINGER, 100))
+    assert(@socket.bind(@link))
+  end
+
+  def run
+    sleep 1
+    contents = "#{'0' * @size}"
+
+    i = 0
+    while i < @count
+      msg = XS::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/examples/weather_upd_client.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+# weather_upd_client.rb
+
+# This example is used in conjunction with weather_upd_server.rb.
+# Run this program in a terminal/console window and then run
+# weather_upd_server.rb in another terminal/console window and
+# observe the output.
+#
+# This program subscribes to a feed of weather updates published
+# by weather_upd_server.rb, collects the first 100 updates that
+# match the subscription filter and displays the average temperature
+# for that zipcode.
+#
+# Usage: ruby weather_upd_client.rb [zip code (default=10001)]
+#
+# If you supply a zip code argument then the maximum value that will
+# be recognized is 11000.
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+COUNT = 100
+
+context = XS::Context.create()
+
+# Socket to talk to server
+puts "Collecting updates from weather server..."
+subscriber = context.socket(XS::SUB)
+subscriber.connect("tcp://127.0.0.1:5556")
+
+# Subscribe to zipcode, default is NYC, 10001
+filter = ARGV.size > 0 ? ARGV[0] : "10001"
+subscriber.setsockopt(XS::SUBSCRIBE, filter)
+
+# Process 100 updates
+total_temp = 0
+1.upto(COUNT) do |update_nbr|
+  s = ''
+  subscriber.recv_string(s)
+  
+  zipcode, temperature, relhumidity = s.split.map(&:to_i)
+  total_temp += temperature
+  puts "Update #{update_nbr.to_s}: #{temperature.to_s}F"
+end
+
+puts "Average temperature for zipcode '#{filter}' was #{total_temp / COUNT}F"
+

data/examples/weather_upd_server.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+# weather_upd_server.rb
+
+# This example is used in conjunction with weather_upd_client.rb.
+# Run this program in a terminal/console window and then run
+# weather_upd_client.rb in another terminal/console window and
+# observe the output.
+#
+# This program publishes a feed of random weather updates containing
+# random zip codes up to a maximum value of 11000.
+#
+# Usage: ruby weather_upd_server.rb
+#
+# To stop the program terminate the process with Ctrl-C or another
+# method of your choice.
+#
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+context = XS::Context.create()
+publisher = context.socket(XS::PUB)
+publisher.bind("tcp://127.0.0.1:5556")
+
+while true
+  # Get values that will fool the boss
+  zipcode = rand(11000)
+  temperature = rand(215) - 80
+  relhumidity = rand(50) + 10
+
+  update = "%05d %d %d" % [zipcode, temperature, relhumidity]
+  puts update
+  publisher.send_string(update)
+end
+

data/examples/xreq_xrep_poll.rb

@@ -0,0 +1,101 @@
+# encoding: utf-8
+
+# xreq_xrep_poll.rb
+#
+# It illustrates the use of xs_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 XS::NO_BLOCK/XS::DONTWAIT for non-blocking send
+# and receive.
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+def assert(rc)
+  raise "Last API call failed at #{caller(1)}" unless rc >= 0
+end
+
+link = "tcp://127.0.0.1:5555"
+
+
+begin
+  ctx = XS::Context.new
+  s1 = ctx.socket(XS::XREQ)
+  s2 = ctx.socket(XS::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(XS::LINGER, 100))
+assert(s2.setsockopt(XS::LINGER, 100))
+
+assert(s1.bind(link))
+assert(s2.connect(link))
+
+poller = XS::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, XS::NonBlocking))
+    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, XS::NonBlocking))
+        puts "routing_info received [#{routing_info}] on socket.identity [#{sock.identity}]"
+      else
+        routing_info = nil
+        received_msg = ''
+        assert(sock.recv_string(received_msg, XS::NonBlocking))
+
+        # 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, XS::NonBlocking))
+
+        puts "message received [#{received_msg}]"
+      end
+
+      puts "kick back a reply"
+      assert(sock.send_string(routing_info, XS::SNDMORE | XS::NonBlocking)) 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/ffi-rxs.gemspec

@@ -8,13 +8,11 @@ Gem::Specification.new do |s|
   s.authors     = ["Chris Duncan"]
   s.email       = ["celldee@gmail.com"]
   s.homepage    = "http://github.com/celldee/ffi-rxs"
-  s.summary     = %q{This gem wraps the Crossroads I/O networking library using Ruby FFI (foreign function interface).}
-  s.description = %q{This gem wraps the Crossroads I/O 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.summary     = %q{Ruby FFI bindings for Crossroads I/O networking library.}
+  s.description = %q{Ruby FFI bindings for Crossroads I/O networking library.}
 
   s.files         = `git ls-files`.split("\n")
+  s.files         = s.files.reject{ |f| f.include?('ext/libxs.so') }
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]

data/lib/ffi-rxs/constants.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module XS
   # Set up all of the constants
   
@@ -5,7 +7,7 @@ module XS
   MAX_SOCKETS = 1
   IO_THREADS = 2
   
-  #  Socket types
+  # Socket types
   PAIR = 0
   PUB = 1
   SUB = 2
@@ -36,7 +38,7 @@ module XS
     XSUB => "XSUB"
   }
 
-  #  Socket options
+  # Socket options
   AFFINITY = 4
   IDENTITY = 5
   SUBSCRIBE = 6
@@ -59,21 +61,23 @@ module XS
   MULTICAST_HOPS = 25
   RCVTIMEO = 27
   SNDTIMEO = 28
+  IPV4ONLY = 31
+  KEEPALIVE = 32
+  
+  # Message options
+  MORE = 1
 
-  #  Send/recv options
+  # Send/recv options
   DONTWAIT = 1
   SNDMORE = 2
-  SNDLABEL = 4
   NonBlocking = DONTWAIT
 
-  #  I/O multiplexing
-
-  POLL = 1
+  # I/O multiplexing
   POLLIN = 1
   POLLOUT = 2
   POLLERR = 4
 
-  #  Socket errors
+  # Socket errors
   EAGAIN = Errno::EAGAIN::Errno
   EFAULT = Errno::EFAULT::Errno
   EINVAL = Errno::EINVAL::Errno
@@ -88,9 +92,9 @@ module XS
   ENOCOMPATPROTO = (HAUSNUMERO + 52)
   ETERM          = (HAUSNUMERO + 53)
 
-  # Rescue unknown constants and use the Crossroads defined values
-  # Usually only happens on Windows though some don't resolve on
-  # OSX too (ENOTSUP)
+  # Rescue unknown constants and use the Crossroads defined values.
+  # Usually only happens on Windows although some do not resolve on
+  # OSX either _ENOTSUP_
   ENOTSUP         = Errno::ENOTSUP::Errno rescue (HAUSNUMERO + 1)
   EPROTONOSUPPORT = Errno::EPROTONOSUPPORT::Errno rescue (HAUSNUMERO + 2)
   ENOBUFS         = Errno::ENOBUFS::Errno rescue (HAUSNUMERO + 3)

data/lib/ffi-rxs/context.rb

@@ -1,20 +1,9 @@
+# encoding: utf-8
 
 module XS
 
-
-  # 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.
+  # All sockets exist within a context and a context is passed to the
+  # Socket constructor when allocating new sockets.
   #
   # Also, Sockets should *only* be accessed from the thread where they
   # were first created. Do *not* pass sockets between threads; pass
@@ -27,30 +16,29 @@ module XS
   # recommended technique for allowing sockets to communicate between
   # threads.
   #
-  #  context = XS::Context.create
-  #  if context
-  #    socket = context.socket(XS::REQ)
-  #    if socket
-  #      ...
-  #    else
-  #      STDERR.puts "Socket allocation failed"
-  #    end
-  #  else
-  #    STDERR.puts "Context allocation failed"
-  #  end
-  #
-  #
+  # @example Create context and socket
+  #   context = XS::Context.create
+  #   if context
+  #     socket = context.socket(XS::REQ)
+  #     if socket
+  #       ...
+  #     else
+  #       STDERR.puts "Socket allocation failed"
+  #     end
+  #   else
+  #     STDERR.puts "Context allocation failed"
+  #   end
   class Context
     include XS::Util
 
     attr_reader :context, :pointer
 
+    # Factory method to instantiate contexts
     def self.create
       new() rescue nil
     end
     
-    # Use the factory method Context#create to make contexts.
-    #
+    # Initialize context object
     def initialize
       @sockets = []
       @context = LibXS.xs_init()
@@ -60,25 +48,36 @@ module XS
       define_finalizer
     end
     
-    # Set options on this context.
+    # Sets options on a context.
+    #
+    # It is recommended to use the default for +io_threads+
+    # (which is 1) since most programs will not saturate I/O. 
     #
-    # Context options take effect only if set with setctxopt() prior to
-    # creating the first socket in a given context with socket().
+    # The rule of thumb is to make io_threads equal to the number 
+    # of gigabits per second that the application will produce.
     #
-    # Valid +name+ values that take a numeric +value+ are:
-    #  XS::IO_THREADS
-    #  XS::MAX_SOCKETS
+    # The io_threads number specifies the size of the thread pool
+    # allocated by Crossroads for processing incoming/outgoing messages.
     #
-    # Returns 0 when the operation completed successfully.
-    # Returns -1 when this operation failed.
+    # The +max_sockets+ number specifies the number of concurrent
+    # sockets that can be used in the context. The default is 512.
     #
-    # With a -1 return code, the user must check XS.errno to determine the
-    # cause.
+    # Context options take effect only if set with **setctxopt()** prior to
+    # creating the first socket in a given context with **socket()**.
     #
-    #  rc = context.setctxopt(XS::IO_THREADS, 10)
-    #  XS::Util.resultcode_ok?(rc) ? puts("succeeded") : puts("failed")
+    # @param [Constant] name
+    #   One of @XS::IO_THREADS@ or @XS::MAX_SOCKETS@.
+    # @param [Integer] value  
+    #  
+    # @return 0 when the operation completed successfully.
+    # @return -1 when this operation fails.
     #
-    def setctxopt name, value, length = nil
+    # @example Set io_threads context option
+    #   rc = context.setctxopt(XS::IO_THREADS, 10)
+    #   unless XS::Util.resultcode_ok?(rc)
+    #     XS::raise_error('xs_setctxopt', rc)
+    #   end
+    def setctxopt name, value
       length = 4
       pointer = LibC.malloc length
       pointer.write_int value
@@ -88,13 +87,13 @@ module XS
       rc
     end
 
-    # Call to release the context and any remaining data associated
+    # Releases the context and any remaining data associated
     # with past sockets. This will close any sockets that remain
     # open; further calls to those sockets will return -1 to indicate
     # the operation failed.
     #
-    # Returns 0 for success, -1 for failure.
-    #
+    # @return 0 for success
+    # @return -1 for failure
     def terminate
       unless @context.nil? || @context.null?
         remove_finalizer
@@ -107,22 +106,14 @@ module XS
       end
     end
 
-    # Short-cut to allocate a socket for a specific context.
+    # Allocates a socket for context
     #
-    # Takes several +type+ values:
-    #   #XS::REQ
-    #   #XS::REP
-    #   #XS::PUB
-    #   #XS::SUB
-    #   #XS::PAIR
-    #   #XS::PULL
-    #   #XS::PUSH
-    #   #XS::DEALER
-    #   #XS::ROUTER
-    #
-    # Returns a #XS::Socket when the allocation succeeds, nil
-    # if it fails.
+    # @param [Constant] type
+    #   One of @XS::REQ@, @XS::REP@, @XS::PUB@, @XS::SUB@, @XS::PAIR@,
+    #          @XS::PULL@, @XS::PUSH@, @XS::DEALER@, or @XS::ROUTER@
     #
+    # @return [Socket] when the allocation succeeds
+    # @return nil when call fails
     def socket type
       sock = nil
       begin
@@ -137,14 +128,17 @@ module XS
 
     private
 
+    # Deletes native resources after object has been destroyed
     def define_finalizer
       ObjectSpace.define_finalizer(self, self.class.close(@context))
     end
-
+    
+    # Removes all finalizers for object
     def remove_finalizer
       ObjectSpace.undefine_finalizer self
     end
 
+    # Closes the context
     def self.close context
       Proc.new { LibXS.xs_term context unless context.null? }
     end

data/lib/ffi-rxs/exceptions.rb

@@ -1,6 +1,7 @@
+# encoding: utf-8
 
 module XS
-
+  # General Crossroads error class
   class XSError < StandardError
     attr_reader :source, :result_code, :error_code, :message
 
@@ -8,12 +9,13 @@ module XS
       @source = source
       @result_code = result_code
       @error_code = error_code
-      @message = "msg [#{message}], error code [#{error_code}], rc [#{result_code}]"
+      @message = "source [#{source}], msg [#{message}], " +
+                 "error code [#{error_code}],rc [#{result_code}]"
       super message
     end
   end # call XSError
 
-
+  # Context error class
   class ContextError < XSError
     # True when the exception was raised due to the library
     # returning EINVAL.
@@ -33,12 +35,12 @@ module XS
 
   end # class ContextError
 
-
+  # Message error class
   class MessageError < XSError
     # True when the exception was raised due to the library
     # returning ENOMEM.
     #
-    # Only ever raised by the #Message class when it fails
+    # Only ever raised by the Message class when it fails
     # to allocate sufficient memory to send a message.
     #
     def enomem?() ENOMEM == @error_code; end

data/lib/ffi-rxs/libc.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 module LibC
   extend FFI::Library

data/lib/ffi-rxs/libxs.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module XS
 
   # Wraps the libxs library and attaches to the API functions