zmqmachine 0.3.0

data/examples/pub_sub.rb

@@ -0,0 +1,195 @@
+
+require 'rubygems'
+require 'ffi-rzmq'
+require '../lib/zmqmachine'
+
+
+# Shows how to use a PUB socket to send messages in a fanout
+# manner. A set of SUB sockets subscribe using different topic
+# matches.
+#
+# The example also shows how to communicate between multiple
+# reactors by running some operations in different contexts.
+# Modify which lines are commented in/out within each context
+# to see how performance changes in different scenarios.
+#
+
+class PublisherHandler
+  attr_reader :sent_count
+
+  def initialize context, port, topics
+    @context = context
+    @port = port
+    @topics = topics
+    @sent_count = 0
+  end
+
+  def on_attach socket
+    address = ZM::Address.new '127.0.0.1', @port, :tcp
+    rc = socket.bind address
+  end
+
+  def on_writable socket
+    topic = @topics[rand(@topics.size)]
+    symbol = topic.split('.').first
+
+    if 'es' == symbol
+      payload = "#{topic}|#{rand(1200) + 1}|#{rand(4400)}"
+    else
+      payload = "#{topic}|#{rand(300) + 1}|#{rand(8000)}"
+    end
+
+    message = ZMQ::Message.new payload
+    socket.send_message message
+    @sent_count += 1
+  end
+end
+
+class SubscriberHandler
+  attr_reader :received_count, :topics
+
+  def initialize context, ports, topic = nil, sleep = false
+    @context = context
+    @received_count = 0
+    @ports = ports
+    (@topics ||= []) << topic.to_s
+    @sleep = sleep
+  end
+
+  def on_attach socket
+    @ports.each do |port|
+      address = ZM::Address.new '127.0.0.1', port, :tcp
+      rc = socket.connect address
+
+      @topics.each do |topic|
+        puts "subscribe to [#{topic}]"
+        socket.subscribe topic
+      end
+    end
+  end
+
+  def on_readable socket, messages
+    @received_count += 1
+    sleep 0.01 if @sleep
+  end
+end
+
+
+# Mix and match the handlers amongst the 5 reactors below. Make sure that a publisher
+# handler is only getting instantiated and run in one reactor at a time. The subscriber
+# handlers can be instantiated multiple times in each reactor if you so choose.
+
+# Run all handlers within the same reactor context
+ctx1 = ZM::Reactor.new(:A).run do |context|
+  @pub1_handler = PublisherHandler.new context, 5555, ['futures.us.es.m.10', 'futures.us.es.u.10']
+  context.pub_socket @pub1_handler
+
+  #  @pub2_handler = PublisherHandler.new context, 5556, ['futures.us.nq.m.10', 'futures.us.nq.u.10']
+  #  context.pub_socket @pub2_handler
+  #
+  #  @sub1_handler = SubscriberHandler.new context, [5555, 5556]
+  #  context.sub_socket @sub1_handler
+  #
+  #  @sub2_handler = SubscriberHandler.new context, [5555], 'futures.us.es.m'
+  #  context.sub_socket @sub2_handler
+  #
+  #  @sub3_handler = SubscriberHandler.new context, [5555], 'futures.us.es.u'
+  #  context.sub_socket @sub3_handler
+  #
+  #  @sub4_handler = SubscriberHandler.new context, [5556], 'futures.us.nq.m'
+  #  context.sub_socket @sub4_handler
+  #
+  #  @sub5_handler = SubscriberHandler.new context, [5555, 5556], 'futures.us.'
+  #  context.sub_socket @sub5_handler
+end
+
+# Or, run each handler in separate contexts each with its
+# own thread.
+ctx2 = ZM::Reactor.new(:B).run do |context|
+  #  @pub1_handler = PublisherHandler.new context, 5555, ['futures.us.es.m.10', 'futures.us.es.u.10']
+  #  context.pub_socket @pub1_handler
+
+  @pub2_handler = PublisherHandler.new context, 5556, ['futures.us.nq.m.10', 'futures.us.nq.u.10']
+  context.pub_socket @pub2_handler
+
+  #  @sub1_handler = SubscriberHandler.new context, [5555, 5556]
+  #  context.sub_socket @sub1_handler
+  #
+  #  @sub2_handler = SubscriberHandler.new context, [5555], 'futures.us.es.m'
+  #  context.sub_socket @sub2_handler
+  #
+  #  @sub3_handler = SubscriberHandler.new context, [5555], 'futures.us.es.u'
+  #  context.sub_socket @sub3_handler
+  #
+  #  @sub4_handler = SubscriberHandler.new context, [5556], 'futures.us.nq.m'
+  #  context.sub_socket @sub4_handler
+  #
+  #  @sub5_handler = SubscriberHandler.new context, [5555, 5556], 'futures.us.'
+  #  context.sub_socket @sub5_handler
+end
+
+ctx3 = ZM::Reactor.new(:C).run do |context|
+  #  @pub1_handler = PublisherHandler.new context, 5555, ['futures.us.es.m.10', 'futures.us.es.u.10']
+  #  context.pub_socket @pub1_handler
+  #
+  #  @pub2_handler = PublisherHandler.new context, 5556, ['futures.us.nq.m.10', 'futures.us.nq.u.10']
+  #  context.pub_socket @pub2_handler
+  #
+  @sub1_handler = SubscriberHandler.new context, [5555, 5556]
+  context.sub_socket @sub1_handler
+
+  @sub2_handler = SubscriberHandler.new context, [5555], 'futures.us.es.m'
+  context.sub_socket @sub2_handler
+
+  @sub3_handler = SubscriberHandler.new context, [5555], 'futures.us.es.u'
+  context.sub_socket @sub3_handler
+
+  @sub4_handler = SubscriberHandler.new context, [5556], 'futures.us.nq.m'
+  context.sub_socket @sub4_handler
+
+  #  @sub5_handler = SubscriberHandler.new context, [5555, 5556], 'futures.us.'
+  #  context.sub_socket @sub5_handler
+end
+
+ctx4 = ZM::Reactor.new(:D).run do |context|
+  #  @pub1_handler = PublisherHandler.new context, 5555, ['futures.us.es.m.10', 'futures.us.es.u.10']
+  #  context.pub_socket @pub1_handler
+  #
+  #  @pub2_handler = PublisherHandler.new context, 5556, ['futures.us.nq.m.10', 'futures.us.nq.u.10']
+  #  context.pub_socket @pub2_handler
+  #
+  #  @sub1_handler = SubscriberHandler.new context, [5555, 5556]
+  #  context.sub_socket @sub1_handler
+  #
+  #  @sub2_handler = SubscriberHandler.new context, [5555], 'futures.us.es.m'
+  #  context.sub_socket @sub2_handler
+  #
+  #  @sub3_handler = SubscriberHandler.new context, [5555], 'futures.us.es.u'
+  #  context.sub_socket @sub3_handler
+  #
+  #  @sub4_handler = SubscriberHandler.new context, [5556], 'futures.us.nq.m'
+  #  context.sub_socket @sub4_handler
+
+  @sub5_handler = SubscriberHandler.new context, [5555, 5556], 'futures.us.'
+  context.sub_socket @sub5_handler
+end
+
+# let's see how many messages we can publish in this many seconds
+sleep_time = 5
+puts "Started at [#{Time.now}]"
+puts "main thread will sleep [#{sleep_time}] seconds before aborting the reactor context threads"
+sleep sleep_time
+
+# Exit each reactor after the sleep time
+ctx1.stop
+ctx2.stop
+ctx3.stop
+ctx4.stop
+
+puts "sent [#{@pub1_handler.sent_count}]"
+puts "sent [#{@pub2_handler.sent_count}]"
+puts "*               [#{@sub1_handler.received_count}]"
+puts "futures.us.ep.m [#{@sub2_handler.received_count}]"
+puts "futures.us.ep.u [#{@sub3_handler.received_count}]"
+puts "futures.us.nq.m [#{@sub4_handler.received_count}]"
+puts "futures.us.nq   [#{@sub5_handler.received_count}]"

data/examples/throttled_ping_pong.rb

@@ -0,0 +1,103 @@
+
+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 PAIR socket pair. All activity is asynchronous and
+# relies on non-blocking I/O.
+#
+# The throttling aspect doesn't really kick in; need to
+# ask the 0mq guys for clarity.
+
+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
+    pong socket, messages.first
+  end
+
+  def on_writable socket
+    #puts "pong on_writable"
+  end
+
+  def pong socket, message
+    socket.send_message message
+    @sent_count += 1
+  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
+  end
+
+  def on_readable socket, messages
+    @received_count += 1
+  end
+
+  def on_writable socket
+    #puts "ping on_writable"
+    ping socket
+  end
+
+  # send as fast as possible until we hit our high water
+  # mark and get EAGAIN; then break
+  def ping socket
+    message = ZMQ::Message.new "#{'b' * 2048}"
+    rc = socket.send_message message
+    @sent_count += 1
+  end
+end
+
+
+
+# Run both handlers within the same reactor context
+ctx1 = ZM::Reactor.new(:pong).run do |context|
+  @pong_handler = PongHandler.new context
+  context.pair_socket @pong_handler
+
+  # If you uncomment these 2 lines, comment out the
+  # +ctx2+ block below.
+  #  @ping_handler = PingHandler.new context
+  #  context.pair_socket @ping_handler
+end
+
+# Or, run each handler in separate contexts each with its
+# own thread.
+ctx2 = ZM::Reactor.new(:ping).run do |context|
+  @ping_handler = PingHandler.new context
+  context.pair_socket @ping_handler
+end
+
+# let's see how many messages we can transfer in this many seconds
+sleep_time = 5
+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 [#{@pong_handler.received_count}], sent [#{@ping_handler.sent_count}]"

data/lib/zm/address.rb

@@ -0,0 +1,70 @@
+#--
+#
+# Author:: Chuck Remes
+# Homepage::  http://github.com/chuckremes/zmqmachine
+# Date:: 20100602
+# 
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2010 by Chuck Remes. All Rights Reserved.
+# Email: cremes at mac dot com
+# 
+# (The MIT License)
+# 
+# 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.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+module ZMQMachine
+
+  #FIXME: needs to handle ipc and inproc transports better, e.g.
+  # there is no port component to either one.
+  #
+  class Address
+    attr_reader :host, :port, :transport
+    
+    # +type+ : :tcp, :pgm or :inprocess
+    def initialize host, port, type = :tcp
+      @host = host
+      @port = port
+      @transport = determine_type type
+    end
+    
+    def to_s
+      "#{@transport}://#{@host}:#{@port}"
+    end
+
+    private
+
+    def determine_type type
+      case type
+      when :inprocess
+        :inproc
+      when :tcp, :pgm
+        type
+      else
+        raise UnknownAddressError, "Unknown address transport type [#{type}]; must be :tcp, :pgm, or :inprocess"
+      end
+    end
+
+  end # class Address
+end # module ZMQMachine

data/lib/zm/deferrable.rb

@@ -0,0 +1,209 @@
+#--
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 16 Jul 2006
+#
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+# Gmail: blackhedd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of either: 1) the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version; or 2) Ruby's License.
+#
+#---------------------------------------------------------------------------
+#
+#
+
+module ZMQMachine
+
+  module Deferrable
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :succeeded. See #set_deferred_status for more information.
+    #
+    # Calling this method on a Deferrable object whose status is not yet known
+    # will cause the callback block to be stored on an internal list.
+    # If you call this method on a Deferrable whose status is :succeeded, the
+    # block will be executed immediately, receiving the parameters given to the
+    # prior #set_deferred_status call.
+    #
+    #--
+    # If there is no status, add a callback to an internal list.
+    # If status is succeeded, execute the callback immediately.
+    # If status is failed, do nothing.
+    #
+    def callback &block
+      return unless block
+      @deferred_status ||= :unknown
+      if @deferred_status == :succeeded
+        block.call(*@deferred_args)
+      elsif @deferred_status != :failed
+        @callbacks ||= []
+        @callbacks.unshift block
+      end
+    end
+
+    # Cancels an outstanding callback to &block if any. Undoes the action of #callback.
+    #
+    def cancel_callback block
+      @callbacks ||= []
+      @callbacks.delete block
+    end
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :failed. See #set_deferred_status for more information.
+    #--
+    # If there is no status, add an errback to an internal list.
+    # If status is failed, execute the errback immediately.
+    # If status is succeeded, do nothing.
+    #
+    def errback &block
+      return unless block
+      @deferred_status ||= :unknown
+      if @deferred_status == :failed
+        block.call(*@deferred_args)
+      elsif @deferred_status != :succeeded
+        @errbacks ||= []
+        @errbacks.unshift block # << block
+      end
+    end
+
+    # Cancels an outstanding errback to &block if any. Undoes the action of #errback.
+    #
+    def cancel_errback block
+      @errbacks ||= []
+      @errbacks.delete block
+    end
+
+    # Sets the "disposition" (status) of the Deferrable object. See also the large set of
+    # sugarings for this method.
+    # Note that if you call this method without arguments,
+    # no arguments will be passed to the callback/errback.
+    # If the user has coded these with arguments, then the
+    # user code will throw an argument exception.
+    # Implementors of deferrable classes <b>must</b>
+    # document the arguments they will supply to user callbacks.
+    #
+    # OBSERVE SOMETHING VERY SPECIAL here: you may call this method even
+    # on the INSIDE of a callback. This is very useful when a previously-registered
+    # callback wants to change the parameters that will be passed to subsequently-registered
+    # ones.
+    #
+    # You may give either :succeeded or :failed as the status argument.
+    #
+    # If you pass :succeeded, then all of the blocks passed to the object using the #callback
+    # method (if any) will be executed BEFORE the #set_deferred_status method returns. All of the blocks
+    # passed to the object using #errback will be discarded.
+    #
+    # If you pass :failed, then all of the blocks passed to the object using the #errback
+    # method (if any) will be executed BEFORE the #set_deferred_status method returns. All of the blocks
+    # passed to the object using # callback will be discarded.
+    #
+    # If you pass any arguments to #set_deferred_status in addition to the status argument,
+    # they will be passed as arguments to any callbacks or errbacks that are executed.
+    # It's your responsibility to ensure that the argument lists specified in your callbacks and
+    # errbacks match the arguments given in calls to #set_deferred_status, otherwise Ruby will raise
+    # an ArgumentError.
+    #
+    #--
+    # We're shifting callbacks off and discarding them as we execute them.
+    # This is valid because by definition callbacks are executed no more than
+    # once. It also has the magic effect of permitting recursive calls, which
+    # means that a callback can call #set_deferred_status and change the parameters
+    # that will be sent to subsequent callbacks down the chain.
+    #
+    # Changed @callbacks and @errbacks from push/shift to unshift/pop, per suggestion
+    # by Kirk Haines, to work around the memory leak bug that still exists in many Ruby
+    # versions.
+    #
+    # Changed 15Sep07: after processing callbacks or errbacks, CLEAR the other set of
+    # handlers. This gets us a little closer to the behavior of Twisted's "deferred,"
+    # which only allows status to be set once. Prior to making this change, it was possible
+    # to "succeed" a Deferrable (triggering its callbacks), and then immediately "fail" it,
+    # triggering its errbacks! That is clearly undesirable, but it's just as undesirable
+    # to raise an exception is status is set more than once on a Deferrable. The latter
+    # behavior would invalidate the idiom of resetting arguments by setting status from
+    # within a callback or errback, but more seriously it would cause spurious errors
+    # if a Deferrable was timed out and then an attempt was made to succeed it. See the
+    # comments under the new method #timeout.
+    #
+    def set_deferred_status status, *args
+      cancel_timeout
+      @errbacks ||= nil
+      @callbacks ||= nil
+      @deferred_status = status
+      @deferred_args = args
+      case @deferred_status
+      when :succeeded
+        if @callbacks
+          while cb = @callbacks.pop
+            cb.call(*@deferred_args)
+          end
+        end
+        @errbacks.clear if @errbacks
+      when :failed
+        if @errbacks
+          while eb = @errbacks.pop
+            eb.call(*@deferred_args)
+          end
+        end
+        @callbacks.clear if @callbacks
+      end
+    end
+
+
+    # Setting a timeout on a Deferrable causes it to go into the failed state after
+    # the Timeout expires (passing no arguments to the object's errbacks).
+    # Setting the status at any time prior to a call to the expiration of the timeout
+    # will cause the timer to be cancelled.
+    def timeout seconds, *args
+      cancel_timeout
+      me = self
+      
+      # we use milliseconds, not seconds, so adjust the passed in time
+      seconds *= 1000
+      @deferred_timeout = ZMQMachine::Timers.add_oneshot seconds {me.fail(*args)}
+    end
+
+    # Cancels an outstanding timeout if any. Undoes the action of #timeout.
+    #
+    def cancel_timeout
+      @deferred_timeout ||= nil
+      if @deferred_timeout
+        @deferred_timeout.cancel
+        @deferred_timeout = nil
+      end
+    end
+
+
+    # Sugar for set_deferred_status(:succeeded, ...)
+    #
+    def succeed *args
+      set_deferred_status :succeeded, *args
+    end
+    alias set_deferred_success succeed
+
+    # Sugar for set_deferred_status(:failed, ...)
+    #
+    def fail *args
+      set_deferred_status :failed, *args
+    end
+    alias set_deferred_failure fail
+  end
+
+
+  # DefaultDeferrable is an otherwise empty class that includes Deferrable.
+  # This is very useful when you just need to return a Deferrable object
+  # as a way of communicating deferred status to some other part of a program.
+  class DefaultDeferrable
+    include Deferrable
+  end
+
+end # module ZMQMachine

data/lib/zm/exceptions.rb

@@ -0,0 +1,45 @@
+#--
+#
+# Author:: Chuck Remes
+# Homepage::  http://github.com/chuckremes/zmqmachine
+# Date:: 20100602
+# 
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2010 by Chuck Remes. All Rights Reserved.
+# Email: cremes at mac dot com
+# 
+# (The MIT License)
+# 
+# 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.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+module ZMQMachine
+  
+  class TimeoutError < StandardError; end
+  
+  class UnknownAddressError < StandardError; end
+  
+  class NotReadyError < StandardError; end
+  
+end # module ZMQMachine

data/lib/zm/message.rb

@@ -0,0 +1,52 @@
+#--
+#
+# Author:: Chuck Remes
+# Homepage::  http://github.com/chuckremes/zmqmachine
+# Date:: 20100602
+# 
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2010 by Chuck Remes. All Rights Reserved.
+# Email: cremes at mac dot com
+# 
+# (The MIT License)
+# 
+# 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.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+module ZMQMachine
+  
+  module Message
+    
+    # A unique identifier for this message
+    def identity
+      
+    end
+    
+    def encode
+      raise NotImplementedError, "You must implement the #encode method in your Message class", caller
+      # FIXME: default to json encoding?
+    end
+    
+  end # module Message
+end # module ZMQMachine