zmqmachine 0.3.0

data/lib/zm/timers.rb

@@ -0,0 +1,220 @@
+#--
+#
+# 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
+
+  # Manages the addition and cancellation of all timers. Each #Reactor
+  # maintains its own set of timers; the timer belongs to the 
+  # reactor context.
+  #
+  # This should never be instantiated directly
+  # by user code. A timer must be known to the #Reactor in which it
+  # is running, so use the #Reactor#oneshot_timer and
+  # #Reactor#periodical_timer convenience methods. It ensures that
+  # new timers are installed in the correct #Reactor.
+  #
+  class Timers
+    def initialize
+      @timers = SortedSet.new
+    end
+
+    # Adds a non-periodical, one-shot timer in order of
+    # first-to-fire to last-to-fire.
+    #
+    # Returns nil unless a +timer_proc+ or +blk+ are
+    # provided. There is no point to an empty timer that
+    # does nothing when fired.
+    #
+    def add_oneshot delay, timer_proc = nil, &blk
+      blk ||= timer_proc
+      return nil unless blk
+
+      timer = Timer.new self, delay, false, blk
+      @timers.add timer
+      timer
+    end
+
+    # Adds a periodical timer in order of
+    # first-to-fire to last-to-fire.
+    #
+    # Returns nil unless a +timer_proc+ or +blk+ are
+    # provided. There is no point to an empty timer that
+    # does nothing when fired.
+    #
+    def add_periodical delay, timer_proc = nil, &blk
+      blk ||= timer_proc
+      return nil unless blk
+
+      timer = Timer.new self, delay, true, blk
+      @timers.add timer
+      timer
+    end
+
+    # Cancel the +timer+. 
+    #
+    # Returns +true+ when cancellation succeeds.
+    # Returns +false+ when it fails to find the
+    # given +timer+.
+    #
+    def cancel timer
+      @timers.delete(timer) ? true : false
+    end
+
+    # A convenience method that loops through all known timers
+    # and fires all of the expired timers. 
+    #
+    #--
+    # Internally the list is sorted whenever a timer is added or
+    # deleted. It stops processing this list when the next timer
+    # is not yet expired; it knows all subsequent timers are not
+    # expired too.
+    #
+    def fire_expired
+      # all time is expected as milliseconds
+      now = Timers.now
+      save = []
+
+      # timers should be sorted by expiration time
+      @timers.delete_if do |timer|
+        break unless timer.expired?(now)
+        timer.fire
+        save << timer if timer.periodical?
+        true
+      end
+
+      # reinstate the periodicals; necessary to do in two steps
+      # since changing the timer.fire_time inside the loop would
+      # not retain proper ordering in the sorted set; re-adding it
+      # ensures the timer is in sorted order
+      save.each { |timer| @timers.add timer }
+    end
+    
+    # Returns the current time using the following algo:
+    #
+    #  (Time.now.to_f * 1000).to_i
+    #
+    # Added as a class method so that it can be overridden by a user
+    # who wants to provide their own time source. For example, a user
+    # could use a third-party gem that provides a better performing
+    # time source.
+    #
+    def self.now
+      (Time.now.to_f * 1000).to_i
+    end
+    
+    # Convert Timers.now to a number usable by the Time class.
+    #
+    def self.now_converted
+      now / 1000.0
+    end
+  end # class Timers
+
+
+  # Used to track the specific expiration time and execution
+  # code for each timer. 
+  #
+  # This should never be instantiated directly
+  # by user code. A timer must be known to the #Reactor in which it
+  # is running, so use the #Reactor#oneshot_timer and
+  # #Reactor#periodical_timer convenience methods. It ensures that
+  # new timers are installed in the correct #Reactor.
+  #
+  class Timer
+    include Comparable
+
+    attr_reader :fire_time
+
+    # +time+ is in milliseconds
+    def initialize timers, delay, periodical, timer_proc = nil, &blk
+      @timers = timers
+      @delay = delay.to_i
+      @periodical = periodical
+      @timer_proc = timer_proc || blk
+      schedule_firing_time
+    end
+
+    # Executes the callback.
+    #
+    # Returns +true+ when the timer is a one-shot;
+    # Returns +false+ when the timer is periodical and has rescheduled
+    # itself.
+    #
+    def fire
+      @timer_proc.call
+
+      schedule_firing_time if @periodical
+    end
+
+    def cancel
+      @timers.cancel self
+    end
+
+    def <=>(other)
+      self.fire_time <=> other.fire_time
+    end
+
+    def expired? time
+      time ||= now
+      time > @fire_time
+    end
+
+    def periodical?
+      @periodical
+    end
+
+
+    private
+
+    # calculate the time when this should fire; note that
+    # the use of #now grabs the current time and adds the
+    # delay on top. When this timer is late in firing (due
+    # to a blocking operation or other blocker preventing
+    # this from running on time) then we will see the next
+    # scheduled firing time slowly drift.
+    # e.g. Fire at time 10 + delay 5 = 15
+    # timer late, fires at 17
+    # next timer to fire at, 17 + delay 5 = 22
+    # had it not been late, it would fire at 20
+    def schedule_firing_time
+      @fire_time = now + @delay
+    end
+
+    def now
+      Timers.now
+    end
+  end # class Timer
+
+end # module ZMQMachine

data/lib/zmqmachine.rb

@@ -0,0 +1,76 @@
+
+module ZMQMachine
+
+  # :stopdoc:
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    @version ||= File.read(path('version.txt')).strip
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args, &block )
+    rv =  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+    if block
+      begin
+        $LOAD_PATH.unshift LIBPATH
+        rv = block.call
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args, &block )
+    rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
+    if block
+      begin
+        $LOAD_PATH.unshift PATH
+        rv = block.call
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+    ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module ZMQMachine
+
+require 'singleton'
+require 'set'
+require 'ffi-rzmq'
+
+# the order of files is important
+%w(address exceptions timers deferrable reactor message sockets).each do |file|
+  require ZMQMachine.libpath(['zm', file])
+end
+
+ZMQMachine.require_all_libs_relative_to(__FILE__)
+
+# save some typing
+ZM = ZMQMachine

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib zmqmachine]))
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+

data/spec/zmqmachine_spec.rb

@@ -0,0 +1,6 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe ZMQMachine do
+end
+

data/version.txt

@@ -0,0 +1 @@
+0.3.0

data/zmqmachine.gemspec

@@ -0,0 +1,48 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{zmqmachine}
+  s.version = "0.3.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-15}
+  s.description = %q{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.}
+  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/fake_ftp.rb", "examples/one_handed_ping_pong.rb", "examples/ping_pong.rb", "examples/pub_sub.rb", "examples/throttled_ping_pong.rb", "lib/zm/address.rb", "lib/zm/deferrable.rb", "lib/zm/exceptions.rb", "lib/zm/message.rb", "lib/zm/reactor.rb", "lib/zm/sockets.rb", "lib/zm/sockets/base.rb", "lib/zm/sockets/pair.rb", "lib/zm/sockets/pub.rb", "lib/zm/sockets/rep.rb", "lib/zm/sockets/req.rb", "lib/zm/sockets/sub.rb", "lib/zm/sockets/xrep.rb", "lib/zm/sockets/xreq.rb", "lib/zm/timers.rb", "lib/zmqmachine.rb", "spec/spec_helper.rb", "spec/zmqmachine_spec.rb", "version.txt", "zmqmachine.gemspec"]
+  s.homepage = %q{http://github.com/chuckremes/zmqmachine}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{zmqmachine}
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{ZMQMachine is another Ruby implementation of the reactor pattern but this time using 0mq sockets rather than POSIX sockets}
+
+  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
+      s.add_runtime_dependency(%q<ffi-rzmq>, [">= 0.5.0"])
+      s.add_development_dependency(%q<bones>, [">= 3.4.3"])
+    else
+      s.add_dependency(%q<ffi-rzmq>, [">= 0.5.0"])
+      s.add_dependency(%q<bones>, [">= 3.4.3"])
+    end
+  else
+    s.add_dependency(%q<ffi-rzmq>, [">= 0.5.0"])
+    s.add_dependency(%q<bones>, [">= 3.4.3"])
+  end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification 
+name: zmqmachine
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- Chuck Remes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-15 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ffi-rzmq
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 0
+        version: 0.5.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bones
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 4
+        - 3
+        version: 3.4.3
+  type: :development
+  version_requirements: *id002
+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.
+email: cremes@mac.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- README.rdoc
+- version.txt
+files: 
+- .bnsignore
+- History.txt
+- README.rdoc
+- Rakefile
+- examples/fake_ftp.rb
+- examples/one_handed_ping_pong.rb
+- examples/ping_pong.rb
+- examples/pub_sub.rb
+- examples/throttled_ping_pong.rb
+- lib/zm/address.rb
+- lib/zm/deferrable.rb
+- lib/zm/exceptions.rb
+- lib/zm/message.rb
+- lib/zm/reactor.rb
+- lib/zm/sockets.rb
+- lib/zm/sockets/base.rb
+- lib/zm/sockets/pair.rb
+- lib/zm/sockets/pub.rb
+- lib/zm/sockets/rep.rb
+- lib/zm/sockets/req.rb
+- lib/zm/sockets/sub.rb
+- lib/zm/sockets/xrep.rb
+- lib/zm/sockets/xreq.rb
+- lib/zm/timers.rb
+- lib/zmqmachine.rb
+- spec/spec_helper.rb
+- spec/zmqmachine_spec.rb
+- version.txt
+- zmqmachine.gemspec
+has_rdoc: true
+homepage: http://github.com/chuckremes/zmqmachine
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: zmqmachine
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: ZMQMachine is another Ruby implementation of the reactor pattern but this time using 0mq sockets rather than POSIX sockets
+test_files: []
+