zmqmachine 0.3.0

data/.bnsignore

@@ -0,0 +1,20 @@
+# The list of files that should be ignored by Mr Bones.
+# Lines that start with '#' are comments.
+#
+# A .gitignore file can be used instead by setting it as the ignore
+# file in your Rakefile:
+#
+#   Bones {
+#     ignore_file  '.gitignore'
+#   }
+#
+# For a project with a C extension, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+# *.[oa]
+# *~
+announcement.txt
+coverage
+doc
+pkg
+examples/work
+.DS_Store

data/History.txt

@@ -0,0 +1,21 @@
+== 0.3.0 / 2010-08-15
+  * Added XREQ/XREP socket types
+  * Moved the time functions for ZM::Timers into a pair of
+    class methods. Instead of accessing Time directly, it should
+    be accessed via ZM::Timers.now and ZM::Timers.now_converted.
+    Doing so allows the programmer to reopen the ZM::Timers class and
+    redefine how time is procured if necessary (e.g. every second of
+    wall clock time should translate to 1 minute of time inside the
+    reactor).
+  * Still needs specs!
+
+== 0.2.0 / 2010-06-06
+  * Updated internals to conform to the 0mq api as of
+  release 2.0.7.
+  
+  * Minor api enhancements.
+
+== 0.1.0 / 2010-06-02
+
+* 1 major enhancement
+  * Birthday!

data/README.rdoc

@@ -0,0 +1,85 @@
+zmqmachine
+    by Chuck Remes
+    http://github.com/chuckremes/zmqmachine
+
+== DESCRIPTION:
+
+ZMQMachine is another Ruby implementation of the reactor pattern but this
+time using 0mq sockets rather than POSIX sockets.
+
+Unlike the great Eventmachine ruby project and the Python Twisted
+project which work with POSIX sockets, ZMQMachine is inherently threaded. The
+0mq sockets backing the reactor use a thread pool for performing
+their work so already it is different from most other reactors. Also, a
+single program may create multiple reactor instances which runs in
+its own thread. All activity within the reactor is single-threaded
+and asynchronous.
+
+It is possible to extend the 0mq library to "poll" normal file
+descriptors. This isn't on my roadmap but patches are accepted.
+
+== FEATURES/PROBLEMS:
+
+* No specs yet.
+
+* Documentation is limited. I need to write up a lot more detail on the Handler classes passed
+  to socket instances and how this differs from the Eventmachine way.
+
+* Exceptions and error codes haven't really been implemented yet.
+
+* Some classes are just skeletons.
+
+* Recommended for JRuby since it is the only existing runtime that uses
+  native threads without a GIL. MRI 1.9.x is okay but may have
+  threading problems.
+
+== SYNOPSIS:
+
+Read and execute the examples in the examples directory.
+
+== REQUIREMENTS:
+
+Requires the 0mq library
+
+* 0mq 2.0.7
+
+Depends on 2 external gems.
+
+* ffi-rzmq (>= 0.5.0)
+* ffi (> 0.6.3) (built from master for threading fixes)
+
+== INSTALL:
+
+Make sure the 0MQ library is already installed on your system. Secondly,
+make sure the FFI gem is built from its project master (see Requirements).
+Lastly, verify the ffi-rzmq gem is built from its project master.
+
+  % git clone github.com/chuckremes/zmqmachine.git
+  % cd zmqmachine
+  % gem build zmqmachine.gemspec
+  % gem install zmqmachine-*.gem
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Chuck Remes
+
+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/Rakefile

@@ -0,0 +1,21 @@
+
+begin
+  require 'bones'
+rescue LoadError
+  abort '### Please install the "bones" gem ###'
+end
+
+task :default => 'test:run'
+task 'gem:release' => 'test:run'
+
+Bones {
+  name  'zmqmachine'
+  authors  'Chuck Remes'
+  email    'cremes@mac.com'
+  url      'http://github.com/chuckremes/zmqmachine'
+  ignore_file '.gitignore'
+  readme_file 'README.rdoc'
+  
+  depend_on 'ffi-rzmq', '>= 0.5.0'
+}
+

data/examples/fake_ftp.rb

@@ -0,0 +1,242 @@
+
+require 'rubygems'
+require 'ffi-rzmq'
+require 'json'
+require '../lib/zmqmachine'
+
+# This example shows how to pair up REQ/REP sockets with PUB/SUB
+# sockets for doing an RPC-style request with an out-of-band
+# response. The RPC reply contains information about the out-of-
+# band data so the servers know that the transfer was complete.
+#
+# This is NOT an implementation of a real FTP server; I used
+# the acronym to highlight the role of each component.
+#
+
+
+server_address = ZM::Address.new '127.0.0.1', 6555, :tcp
+
+
+class FTPDataClient
+  include ZM::Deferrable
+
+  def initialize context, address, topic, process
+    @context = context
+    @address = address
+    @topic = topic
+    @process = process
+    @received_count = 0
+    @expected_count = -1
+
+    callback do
+      puts "FTPDataClient#callback fired, received all file chunks"
+      @context.next_tick { @context.stop }
+    end
+  end
+
+  def on_attach socket
+    @socket = socket
+    @socket.bind @address
+    @socket.subscribe @topic
+  end
+
+  def on_readable socket, messages
+    obj = decode strip_topic(messages.first.copy_out_string)
+    puts "#{self.class.name}#on_readable: process obj #{obj.inspect}"
+    @received_count += @process.call(obj)
+    succeed if complete?
+  end
+
+  def on_writable(socket); puts "#{self.class.name}#on_writable, should never be called"; end
+
+  def should_expect count
+    puts "#{self.class.name}#should_expect, set to expect [#{count}], already received [#{@received_count}]"
+    @expected_count = count
+    succeed if complete?
+  end
+
+
+  private
+
+  def strip_topic payload
+    payload.split('|').last
+  end
+
+  def complete?
+    @expected_count > 0 && @expected_count == @received_count
+  end
+
+  def decode string
+    JSON.parse string
+  end
+end
+
+class FTPControlClient
+  def initialize context, address
+    @context = context
+    @address = address
+    @received_count = 0
+  end
+
+  def on_attach socket
+    @socket = socket
+    rc = socket.connect @address
+  end
+
+  def on_readable socket, messages
+    reply = decode messages.first.copy_out_string
+    puts "#{self.class.name}#on_readable: reply from FTPDataServer #{reply.inspect}"
+
+    @data_client.should_expect reply['total_chunks']
+  end
+
+  def get filename, &blk
+    sub_address = ZM::Address.new @address.host, 5556, @address.transport
+    topic = "file.#{filename}|"
+
+    @data_client = FTPDataClient.new @context, sub_address, topic, blk
+    @sub_socket = @context.sub_socket @data_client
+
+    req = {'filename' => filename, 'reply_to' => sub_address.to_s}
+
+    puts "#{self.class.name}#get: send request for the file chunks to be published"
+    @socket.send_message_string encode(req)
+  end
+
+
+  private
+
+  def decode string
+    JSON.parse string
+  end
+
+  def encode obj
+    JSON.generate obj
+  end
+end
+
+class FTPDataServer
+  include ZM::Deferrable
+
+  attr_reader :total_count
+
+  def initialize request
+    @request = request
+    @address_string = request['reply_to']
+    @topic = "file.#{request['filename']}|"
+    @total_count = 0
+  end
+
+  def on_attach socket
+    if open_file
+      @socket = socket
+      @socket.connect @address_string
+    else
+      puts "#{self.class.name}#on_attach: @total_count is 0"
+      succeed @total_count
+    end
+  end
+
+  def on_writable socket
+    if more_file_data?
+      @total_count += 1
+      obj = encode(next_file_chunk)
+      puts "#{self.class.name}#on_writable: send chunk [#{@total_count}], obj #{obj.inspect}"
+      socket.send_message_string obj
+    else
+      puts "#{self.class.name}#on_writable: done [#{@total_count}]"
+      succeed @total_count
+    end
+  end
+
+
+  private
+
+  def open_file
+    @chunks = rand(5) + 5
+    @chunks > 0
+  end
+
+  def more_file_data?
+    @chunks > 0
+  end
+
+  def next_file_chunk
+    @chunks -= 1
+    chunk = rand(999_999_999) + 1_000_000_000
+    {'chunk' => chunk}
+  end
+
+  def encode obj
+    "#{@topic}#{JSON.generate(obj)}"
+  end
+end
+
+class FTPControlServer
+  def initialize context, address
+    @context = context
+    @address = address
+  end
+
+  def on_attach socket
+    @socket = socket
+    rc = socket.bind @address
+  end
+
+  def on_readable socket, messages
+    request = decode messages.first.copy_out_string
+    puts "#{self.class.name}: query #{request.inspect}"
+    @pub_handler = FTPDataServer.new request
+    @pub_socket = @context.pub_socket @pub_handler
+
+    @pub_handler.callback do |total_chunks|
+      puts "FTPDataServer#callback fired, sent all file chunks"
+
+      reply = encode 'total_chunks' => total_chunks
+      socket.send_message_string reply
+
+      # clean up after ourselves
+      @context.close_socket @pub_socket
+      @pub_handler = nil
+    end
+  end
+
+  def on_writable socket
+    puts "#{self.class.name}#on_writable ERROR, should never be called"
+  end
+
+
+  private
+
+  def decode string
+    JSON.parse string
+  end
+
+  def encode obj
+    JSON.generate obj
+  end
+end
+
+
+# Run both handlers within the same reactor context
+ctx1 = ZM::Reactor.new(:test).run do |context|
+
+  @request_server = FTPControlServer.new context, server_address
+  context.rep_socket @request_server
+
+  @request_client = FTPControlClient.new context, server_address
+  context.req_socket @request_client
+
+  @request_client.get('fakeo') do |file_chunk|
+    puts "block: file chunk #{file_chunk.inspect}"
+
+    # the number of chunks processed in this block; this return
+    # value is used by FTPDataClient#on_readable for tallying
+    # the total number of processed chunks.
+    1
+  end
+
+end
+
+
+ctx1.join

data/examples/one_handed_ping_pong.rb

@@ -0,0 +1,74 @@
+
+require 'rubygems'
+require 'ffi-rzmq'
+require '../lib/zmqmachine'
+
+# This example illustrates how a single handler can be used
+# by multiple sockets.
+#
+
+
+
+Allowed_pongs = 100_000
+
+class PingPongHandler
+  attr_reader :sent_count, :received_count
+
+  def initialize context
+    @context = context
+    @sent_count = 0
+    @received_count = 0
+  end
+
+  def on_attach socket
+    address = ZM::Address.new '127.0.0.1', 5555, :tcp
+
+    case socket.kind
+    when :reply
+      rc = socket.bind address
+    when :request
+      rc = socket.connect address
+      rc = socket.send_message_string "#{'a' * 2048}"
+      @sent_count += 1
+    end
+  end
+
+  def on_readable socket, messages
+    @received_count += 1
+
+    case socket.kind
+    when :reply
+      socket.send_message messages.first
+    when :request
+      socket.send_message messages.first
+    end
+
+    @sent_count += 1
+    @context.next_tick { @context.stop } if @sent_count == Allowed_pongs
+  end
+end
+
+handler = nil
+# Run both handlers within the same reactor context
+ctx1 = ZM::Reactor.new(:test).run do |context|
+  handler = PingPongHandler.new context
+
+  context.rep_socket handler
+
+  context.req_socket handler
+
+  start = Time.now
+  timer = context.periodical_timer(2000) do
+    now = Time.now
+    puts "[#{now - start}] seconds have elapsed; it is now [#{now}]"
+  end
+end
+
+ctx1.join
+#puts "Started at [#{Time.now}]"
+#puts "main thread will sleep [#{sleep_time}] seconds before aborting the context threads"
+#sleep sleep_time
+#
+#ctx1.stop
+#ctx2.stop
+puts "received [#{handler.received_count}], sent [#{handler.sent_count}]"

data/examples/ping_pong.rb

@@ -0,0 +1,86 @@
+
+require 'rubygems'
+require 'ffi-rzmq'
+require '../lib/zmqmachine'
+
+# This example illustrates how to write a simple set of 
+# handlers for providing message ping-pong using
+# a REQ/REP socket pair. All activity is asynchronous and
+# relies on non-blocking I/O.
+
+
+Allowed_pongs = 100_000
+
+
+class PongHandler
+  attr_reader :sent_count, :received_count
+
+  def initialize context
+    @context = context
+    @sent_count = 0
+    @received_count = 0
+  end
+
+  def on_attach socket
+    address = ZM::Address.new '127.0.0.1', 5555, :tcp
+    rc = socket.bind address
+  end
+
+  def on_readable socket, messages
+    @received_count += 1
+    socket.send_message messages.first
+    @sent_count += 1
+    
+    @context.next_tick { @context.stop } if @sent_count == Allowed_pongs
+  end
+end
+
+class PingHandler
+  attr_reader :sent_count, :received_count
+
+  def initialize context
+    @context = context
+    @sent_count = 0
+    @received_count = 0
+  end
+
+  def on_attach socket
+    address = ZM::Address.new '127.0.0.1', 5555, :tcp
+    rc = socket.connect address
+    rc = socket.send_message_string "#{'a' * 2048}"
+    @sent_count += 1
+  end
+
+  def on_readable socket, messages
+    @received_count += 1
+    rc = socket.send_message messages.first
+    @sent_count += 1
+  end
+end
+
+# Run both handlers within the same reactor context
+ctx1 = ZM::Reactor.new(:test).run do |context|
+  @pong_handler = PongHandler.new context
+  context.rep_socket @pong_handler
+
+  @ping_handler = PingHandler.new context
+  context.req_socket @ping_handler
+
+  start = Time.now
+  timer = context.periodical_timer(2000) do
+    now = Time.now
+    puts "[#{now - start}] seconds have elapsed; it is now [#{now}]"
+  end
+end
+
+# Or, run each handler in separate contexts each with its
+# own thread.
+#ctx2 = ZM::Reactor.new(:test).run do |context|
+#  @ping_handler = PingHandler.new context
+#  context.req_socket @ping_handler
+#end
+
+
+ctx1.join
+#ctx2.join
+puts "received [#{@pong_handler.received_count}], sent [#{@pong_handler.sent_count}]"