ffi-rxs 1.0.0 → 1.0.1

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+notifications:
+  email: false

data/.yardopts

@@ -0,0 +1,9 @@
+--no-private
+--protected
+--markup="textile" lib/**/*.rb
+--main README.textile
+--asset examples:examples
+--hide-tag todo
+-
+LICENSE
+CHANGELOG

data/CHANGELOG

@@ -0,0 +1,11 @@
+= Version 1.0.1
+
+  * Re-working of some ZeroMQ examples for use with Crossroads I/O
+  * Addition of missing socket option XS::IPV4ONLY
+  * Addition of new socket option XS::KEEPALIVE
+  * Editing of inline comments for Yard documentation in Textile
+  * Amended .gemspec to exclude ext/libxs.so from build to accommodate Travis CI in development
+
+= Version 1.0.0
+
+  * Initial release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 - 2012 Chuck Remes, Chris Duncan and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,86 @@
+h1. About ffi-rxs
+
+This gem wraps the "Crossroads I/O":http://crossroads.io 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.
+
+Crossroads I/O is a fork of ZeroMQ. This gem is a re-working of the ffi-rzmq gem created by Chuck Remes to provide bindings for the Crossroads I/O libxs C library instead of the ZeroMQ libzmq library. The gem auto-configures itself to expose the API conforming to the loaded C library. 
+
+h2. Features/Problems
+
+This gem needs to be tested in the wild. Please kick its tyres and give it a good thrashing. It is inevitable that bugs will be discovered, so please open issues for them here or fork this project, fix them, and send me a pull request.
+
+The 'ffi' gem has dropped support for MRI 1.8.x. Since this project relies on that gem to load and run this code, then this project does not support MRI 1.8.x. I recommend JRuby for the best performance and stability.
+
+h2. Requirements
+
+* Crossroads I/O version 1.0.0 or later.
+* ffi (>= 1.0.0)
+  
+The Crossroads I/O library must be installed on your system in a well-known location like /usr/local/lib. This is the default for new Crossroads I/O installs. Future releases may include the library as a C extension built at time of installation.
+  
+Do *not* run this gem under MRI with an old 'ffi' gem. It will crash randomly and you will be sad.
+
+h2. Installation
+
+A full gem has been released to Rubygems.org as of release 1.0.0. Make sure the Crossroads I/O library is already installed on your system.
+
+* gem install ffi-rxs # should grab the latest release
+
+
+To build from git master:
+
+* git clone git://github.com/celldee/ffi-rxs
+* cd ffi-rxs
+* gem build ffi-rxs.gemspec
+* gem install ffi-rxs-*.gem
+ 
+
+*NOTE* for Windows users!
+In order for this gem to find the libxs.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.
+
+h2. Examples
+
+h3. Using Request (REQ) socket -
+
+<pre>
+require 'ffi-rxs'
+
+ctx = XS::Context.create()
+socket = ctx.socket(XS::REQ)
+socket.connect("tcp://127.0.0.1:5000")
+ 
+for i in 1..10
+  msg = "msg #{i.to_s}"
+  socket.send_string(msg)
+  puts "Sending: " + msg
+  socket.recv_string(msg_in = '')
+  puts "Received: " + msg_in
+end
+</pre>
+
+h3. Using Reply (REP) socket -
+
+<pre>
+require 'ffi-rxs'
+
+ctx = XS::Context.create()
+socket = ctx.socket(XS::REP)
+socket.bind("tcp://127.0.0.1:5000")
+ 
+while true do
+  socket.recv_string(msg = '')
+  puts "Got: " + msg
+  socket.send_string(msg)
+end
+</pre>
+
+The above examples and additional ones are available in the repository examples folder.
+
+h2. Links
+
+* "Source code":http://github.com/celldee/ffi-rxs
+* "Crossroads I/O website":http://crossroads.io
+* "Crossroads I/O Discussion Group":http://groups.crossroads.io/
+
+h2. License
+
+This project is licensed under the MIT license. Please see the LICENSE file in the repository.

data/examples/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2010-2012 iMatix Corporation, Chris Duncan and Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/examples/README

@@ -0,0 +1,2 @@
+Contains some Ruby examples reworked from http://github.com/imatix/zguide
+See LICENSE in examples directory

data/examples/durable_pub.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+# Durable publisher to be used in conjunction with durable_sub.rb
+# Justin Case <justin@playelite.com>
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+context = XS::Context.create()
+
+# Subscriber tells us when it's ready here
+sync = context.socket(XS::PULL)
+sync.bind("tcp://127.0.0.1:5564")
+
+# We send updates via this socket
+publisher = context.socket(XS::PUB)
+publisher.bind("tcp://127.0.0.1:5565")
+
+# Wait for synchronization request
+sync.recv_string(sync_request = '')
+
+# Now broadcast exactly 10 updates with pause
+10.times do |update_number|
+  message = sprintf("Update %d", update_number)
+  puts "Sending: " + message
+  publisher.send_string(message)
+  sleep(1)
+end
+  
+publisher.send_string("END")
+
+sync.close
+publisher.close
+context.terminate
+

data/examples/durable_sub.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+# Durable subscriber to be used in conjunction with durable_pub.rb
+# Justin Case <justin@playelite.com>
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+context = XS::Context.create()
+
+# Connect our subscriber socket
+subscriber = context.socket(XS::SUB)
+subscriber.setsockopt(XS::IDENTITY, "Hello")
+subscriber.setsockopt(XS::SUBSCRIBE, "")
+subscriber.connect("tcp://127.0.0.1:5565")
+
+# Synchronize with publisher
+sync = context.socket(XS::PUSH)
+sync.connect("tcp://127.0.0.1:5564")
+sync.send_string("")
+
+# Get updates, exit when told to do so
+loop do
+  subscriber.recv_string(message = '')
+  puts "Received: " + message
+  if message == "END"
+    break
+  end
+end
+

data/examples/latency_measurement.rb

@@ -0,0 +1,140 @@
+# encoding: utf-8
+
+# latency_measurement.rb
+
+# 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
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+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 = XS::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(XS::REP)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate REP socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(XS::LINGER, 100))
+    assert(@socket.setsockopt(XS::RCVHWM, 100))
+    assert(@socket.setsockopt(XS::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(XS::REQ)
+    rescue ContextError => e
+      STDERR.puts "Failed to allocate REP socket!"
+      raise
+    end
+
+    assert(@socket.setsockopt(XS::LINGER, 100))
+    assert(@socket.setsockopt(XS::RCVHWM, 100))
+    assert(@socket.setsockopt(XS::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

data/examples/reply.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+# reply.rb
+
+# This example is used in conjunction with request.rb. Run this program in
+# a terminal/console window and then run request.rb in another terminal/console
+# window and observe the output.
+#
+# Usage: ruby reply.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')
+
+ctx = XS::Context.create()
+socket = ctx.socket(XS::REP)
+socket.bind("tcp://127.0.0.1:5000")
+ 
+while true do
+  socket.recv_string(msg = '')
+  puts "Got: " + msg
+  socket.send_string(msg)
+end

data/examples/req_rep_poll.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+# req_rep_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:5554"
+
+begin
+  ctx = XS::Context.create()
+  s1 = ctx.socket(XS::REQ)
+  s2 = ctx.socket(XS::REP)
+rescue ContextError => e
+  STDERR.puts "Failed to allocate context or socket!"
+  raise
+end
+
+assert(s1.setsockopt(XS::LINGER, 100))
+assert(s2.setsockopt(XS::LINGER, 100))
+
+assert(s1.connect(link))
+assert(s2.bind(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
+    payload = "#{ '3' * 1024 }"
+
+    puts "sending payload nonblocking"
+    assert(s1.send_string(payload, XS::NonBlocking))
+    @unsent = false
+  end
+
+  # check for messages after 1 second
+  if Time.now - start_time > 1
+    poller.readables.each do |sock|
+      received_msg = ''
+      assert(sock.recv_string(received_msg, XS::NonBlocking))
+
+      puts "message received [#{received_msg}]"
+      @done = true
+    end
+  end
+end
+
+puts "executed in [#{Time.now - start_time}] seconds"
+
+assert(s1.close)
+assert(s2.close)
+
+ctx.terminate
+

data/examples/request.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+# request.rb
+
+# This example is used in conjunction with reply.rb. Run this program in
+# a terminal/console window and then run reply.rb in another terminal/console
+# window and observe the output.
+#
+# Usage: ruby request.rb
+#
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+ctx = XS::Context.create()
+socket = ctx.socket(XS::REQ)
+socket.connect("tcp://127.0.0.1:5000")
+ 
+for i in 1..10
+  msg = "msg #{i.to_s}"
+  socket.send_string(msg)
+  puts "Sending: " + msg
+  socket.recv_string(msg_in = '')
+  puts "Received: " + msg_in
+end

data/examples/task_sink.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+# Task sink to be used in conjunction with task_vent.rb
+# and task_worker.rb
+# Binds PULL socket to tcp://localhost:5558
+# Collects results from task_workers via that socket
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+# Prepare our context and socket
+context = XS::Context.create()
+receiver = context.socket(XS::PULL)
+receiver.bind("tcp://*:5558")
+
+# Wait for start of batch
+receiver.recv_string('')
+puts 'Sink started'
+tstart = Time.now
+
+# Process 100 confirmations
+100.times do |task_nbr|
+  receiver.recv_string('')
+  $stdout << ((task_nbr % 10 == 0) ? ':' : '.')
+  $stdout.flush
+end
+
+# Calculate and report duration of batch
+tend = Time.now
+total_msec = (tend-tstart) * 1000
+puts "Total elapsed time: #{total_msec} msec"
+

data/examples/task_vent.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+#   Task vent to be used in conjunction with task_worker.rb
+#   and task_sink.rb
+#   Binds PUSH socket to tcp://localhost:5557
+#   Sends batch of tasks to task_workers via that socket
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+context = XS::Context.create()
+
+# Socket to send messages on
+sender = context.socket(XS::PUSH)
+sender.bind("tcp://*:5557")
+
+puts "Press enter when the workers are ready..."
+$stdin.read(1)
+puts "Sending tasks to workers..."
+
+# The first message is "0" and signals start of batch
+sender.send_string('0')
+
+# Send 100 tasks
+total_msec = 0  # Total expected cost in msecs
+100.times do
+  workload = rand(100) + 1
+  total_msec += workload
+  $stdout << "#{workload}."
+  sender.send_string(workload.to_s)
+end
+
+puts "Total expected cost: #{total_msec} msec"
+Kernel.sleep(1)  # Give Crossroads time to deliver
+

data/examples/task_worker.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+#   Task worker to be used in conjunction with task_vent.rb
+#   and task_sink.rb
+#   Connects PULL socket to tcp://localhost:5557
+#   Collects workloads from task_vent via that socket
+#   Connects PUSH socket to tcp://localhost:5558
+#   Sends results to sink via that socket
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'ffi-rxs')
+
+context = XS::Context.create()
+
+# Socket to receive messages on
+receiver = context.socket(XS::PULL)
+receiver.connect("tcp://localhost:5557")
+
+# Socket to send messages to
+sender = context.socket(XS::PUSH)
+sender.connect("tcp://localhost:5558")
+
+# Process tasks forever
+while true
+  
+  receiver.recv_string(msec = '')
+  # Simple progress indicator for the viewer
+  $stdout << "#{msec}."
+  $stdout.flush
+
+  # Do the work
+  sleep(msec.to_f / 1000)
+
+  # Send results to sink
+  sender.send_string("")
+end
+