timers 0.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format documentation
+--backtrace
+--default_path spec

data/.travis.yml

@@ -0,0 +1,12 @@
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - ree
+  - ruby-head
+  - jruby-18mode
+  - jruby-19mode
+  - jruby-head
+
+# Sporadically failing :(
+#  - rbx-18mode
+#  - rbx-19mode

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in timers.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Tony Arcieri
+
+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.

data/README.md

@@ -0,0 +1,73 @@
+Timers
+======
+[![Build Status](https://secure.travis-ci.org/tarcieri/timers.png?branch=master)](http://travis-ci.org/tarcieri/timers)
+
+Pure Ruby timer collections. Schedule several procs to fire after configurable
+delays or at periodic intervals.
+
+This gem is especially useful when you are faced with an API that accepts a
+single timeout but you want to run multiple timers on top of it. An example of
+such a library is [nio4r](https://github.com/tarcieri/nio4r), a cross-platform
+Ruby library for using system calls like epoll and kqueue.
+
+Usage
+-----
+
+Create a new timer group with `Timers.new`:
+
+```ruby
+require 'timers'
+
+timers = Timers.new
+```
+
+Schedule a proc to run after 5 seconds with `Timers#after`:
+
+```ruby
+five_second_timer = timers.after(5) { puts "Take five" }
+```
+
+The `five_second_timer` variable is now bound to a Timers::Timer object. To
+cancel a timer, use `Timers::Timer#cancel`
+
+Once you've scheduled a timer, you can wait until the next timer fires with `Timers#wait`:
+
+```ruby
+# Waits 5 seconds
+timers.wait
+
+# The script will now print "Take five"
+```
+
+You can schedule a block to run periodically with `Timers#every`:
+
+```ruby
+every_five_seconds = timers.every(5) { puts "Another 5 seconds" }
+
+loop { timers.wait }
+```
+
+If you'd like another method to do the waiting for you, e.g. `Kernel.select`,
+you can use `Timers#wait_interval` to obtain the amount of time to wait. When
+a timeout is encountered, you can fire all pending timers with `Timers#fire`:
+
+```ruby
+loop do
+  interval = timers.wait_interval
+  ready_readers, ready_writers = select readers, writers, nil, interval
+
+  if ready_readers || ready_writers
+    # Handle IO
+    ...
+  else
+    # Timeout!
+    timers.fire
+  end
+end
+```
+
+License
+-------
+
+Copyright (c) 2012 Tony Arcieri. Distributed under the MIT License. See
+LICENSE for further details.

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/lib/timers.rb

@@ -0,0 +1,115 @@
+require "timers/version"
+
+# Low precision timers implemented in pure Ruby
+class Timers
+  def initialize
+    @timers = []
+  end
+
+  # Call the given block after the given interval
+  def after(interval, &block)
+    Timer.new(self, interval, false, block)
+  end
+
+  # Call the given block periodically at the given interval
+  def every(interval, &block)
+    Timer.new(self, interval, true, block)
+  end
+
+  # Wait for the next timer and fire it
+  def wait
+    return if @timers.empty?
+
+    interval = wait_interval
+    sleep interval if interval >= Timer::QUANTUM
+    fire
+  end
+
+  # Interval to wait until when the next timer will fire
+  def wait_interval
+    @timers.first.time - Time.now unless empty?
+  end
+
+  # Fire all timers that are ready
+  def fire
+    return if @timers.empty?
+
+    time = Time.now + Timer::QUANTUM
+    while not empty? and time > @timers.first.time
+      timer = @timers.shift
+      timer.call
+    end
+  end
+
+  # Insert a timer into the active timers
+  def insert(timer)
+    @timers.insert(index(timer), timer)
+  end
+
+  # Remove a given timer from the set we're monitoring
+  def cancel(timer)
+    @timers.delete timer
+  end
+
+  # Are there any timers pending?
+  def empty?
+    @timers.empty?
+  end
+
+  # Index where a timer would be located in the sorted timers array
+  def index(timer)
+    l, r = 0, @timers.size - 1
+
+    while l <= r
+      m = (r + l) / 2
+      if timer < @timers.at(m)
+        r = m - 1
+      else
+        l = m + 1
+      end
+    end
+    l
+  end
+
+  # An individual timer set to fire a given proc at a given time
+  class Timer
+    include Comparable
+
+    # The timer system is guaranteed (at least by the specs) to be this precise
+    # during normal operation. Long blocking calls within actors will delay the
+    # firing of timers
+    QUANTUM = 0.02
+
+    attr_reader :interval, :time, :recurring
+
+    def initialize(timers, interval, recurring, block)
+      @timers, @interval, @recurring = timers, interval, recurring
+      @block = block
+
+      reset
+    end
+
+    def <=>(other)
+      @time <=> other.time
+    end
+
+    # Cancel this timer
+    def cancel
+      @timers.cancel self
+    end
+
+    # Reset this timer
+    def reset
+      @timers.cancel self if defined?(@time)
+      @time = Time.now + @interval
+      @timers.insert self
+    end
+
+    # Fire the block
+    def fire
+      reset if recurring
+      @block.call
+    end
+    alias_method :call, :fire
+  end
+end

data/lib/timers/version.rb

@@ -0,0 +1,3 @@
+class Timers
+  VERSION = "0.0.0"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'bundler/setup'
+require 'timers'

data/spec/timers_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe Timers do
+  Q = Timers::Timer::QUANTUM
+
+  it "sleeps until the next timer" do
+    interval = 0.1
+    started_at = Time.now
+
+    fired = false
+    subject.after(interval) { fired = true }
+    subject.wait
+
+    fired.should be_true
+    (Time.now - started_at).should be_within(Q).of interval
+  end
+
+  it "it calculates the interval until the next timer should fire" do
+    interval = 0.1
+
+    subject.after(interval)
+    subject.wait_interval.should be_within(Q).of interval
+  end
+
+  it "fires timers in the correct order" do
+    result = []
+
+    subject.after(Q * 2) { result << :two }
+    subject.after(Q * 3) { result << :three }
+    subject.after(Q * 1) { result << :one }
+
+    sleep Q * 4
+    subject.fire
+
+    result.should == [:one, :two, :three]
+  end
+
+  describe "recurring timers" do
+    it "should continue to fire the timers at each interval" do
+      result = []
+
+      subject.every(Q * 3) { result << :foo }
+
+      sleep Q * 3
+      subject.fire
+      result.should == [:foo]
+
+      sleep Q * 3
+      subject.fire
+      subject.fire
+      result.should == [:foo, :foo]
+    end
+  end
+end

data/timers.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/timers/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Tony Arcieri"]
+  gem.email         = ["tony.arcieri@gmail.com"]
+  gem.description   = "Pure Ruby one-shot and periodic timers"
+  gem.summary       = "Schedule procs to run after a certain time, or at periodic intervals, using any API that accepts a timeout"
+  gem.homepage      = "https://github.com/tarcieri/timers"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "timers"
+  gem.require_paths = ["lib"]
+  gem.version       = Timers::VERSION
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: timers
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Tony Arcieri
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70212434293540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70212434293540
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70212434292840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70212434292840
+description: Pure Ruby one-shot and periodic timers
+email:
+- tony.arcieri@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/timers.rb
+- lib/timers/version.rb
+- spec/spec_helper.rb
+- spec/timers_spec.rb
+- timers.gemspec
+homepage: https://github.com/tarcieri/timers
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Schedule procs to run after a certain time, or at periodic intervals, using
+  any API that accepts a timeout
+test_files:
+- spec/spec_helper.rb
+- spec/timers_spec.rb
+has_rdoc: