later 0.1.3 → 0.2.0

data/README.md

@@ -1,6 +1,6 @@
 # Later
 
-[**Later**](erol.github.com/later) is a lightweight Redis-backed event scheduling library for Ruby.
+[**Later**](erol.github.com/later) is a lean Redis-backed event scheduling library for Ruby.
 
 ## Usage
 
@@ -8,29 +8,30 @@ Later allows you to set unique events on a schedule and run them in the future:
 
     require 'later'
 
-    Later[:reservations].set 'event-1', Time.now + 60
-    Later[:reservations].set 'event-2', Time.now + 120
-    Later[:reservations].set 'event-3', Time.now + 180
+    schedule = Later[:schedule]
+    schedule.set 'event-1', Time.now + 60
+    schedule.set 'event-2', Time.now + 120
+    schedule.set 'event-3', Time.now + 180
 
 Rescheduling an event is simple:
 
-    Later[:reservations].set 'event-1', Time.now + 240
+    schedule.set 'event-1', Time.now + 240
 
-And an event can also be unset:
+And an event can unset with equal ease:
 
-    Later[key].unset 'event-1'
+    schedule.unset 'event-1'
 
 You can manage multiple schedules using different keys:
 
-    Later[:reservations]
-    Later[:appointments]
+    reservations = Later[:reservations]
+    appointments = Later[:appointments]
 
 The schedules are stored on the default Redis instance. If you need a schedule which must reside on a different Redis instance, you can pass a [Nest](github.com/soveran/nest) object when referencing a schedule set.
 
     redis = Redis.new host: host, port: port
-    key = Nest.new :reservations, redis
+    key = Nest.new 'Reservations', redis
 
-    Later[key]
+    reservations = Later[key]
 
 ### Workers
 
@@ -38,18 +39,34 @@ Workers are Ruby processes that run forever. They allow you to process event sch
 
     require 'later'
 
-    Later[:reservations].each do |event|
+    Later[:schedule].each do |event|
       # Do something with the event.
     end
 
     # This line is never reached.
 
+#### Timeouts, Blocking & Polling
+
+`Later::Schedule#each` accepts an optional `timeout` parameter, which has a default value of `1`. Passing an `Integer` will use Redis' blocking mechanism
+to process the schedule and is therefore more efficient. Passing a `Float` will poll Redis using the given timeout, and should
+only be used for events which need to be triggered with millisecond precision.
+
+See [BLPOP](http://redis.io/commands/blpop) and [BRPOPLPUSH](http://redis.io/commands/brpoplpush) for more information.
+
+The below schedule will be polled every 0.1 seconds:
+
+    Later[:schedule].each(0.1) do |event|
+      # Do something with the event.
+    end
+
+#### Stopping
+
 If for some reason, a worker has to stop itself from running:
 
-    Later[:reservations].each do |event|
+    Later[:schedule].each do |event|
       # Do something with the event.
 
-      Later[:reservations].stop! if stop?
+      Later[:schedule].stop! if stop?
     end
 
     # This line is reached when stop? is true and Later[:reservations].stop! is called.

data/Rakefile

@@ -5,6 +5,6 @@ require 'rake/testtask'
 
 Rake::TestTask.new do |t|
   t.libs << 'test'
-  t.test_files = FileList['test/lib/*.rb']
+  t.test_files = FileList['test/specs/*.rb']
   t.verbose = true
 end

data/later.gemspec

@@ -4,8 +4,8 @@ require File.expand_path('../lib/later/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ['Erol Fornoles']
   gem.email         = ['erol.fornoles@gmail.com']
-  gem.description   = %q{Later is a Redis-backed event scheduling library for Ruby}
-  gem.summary       = %q{Later is a Redis-backed event scheduling library for Ruby}
+  gem.description   = %q{Lean Redis-backed event scheduling library for Ruby}
+  gem.summary       = %q{Lean Redis-backed event scheduling library for Ruby}
   gem.homepage      = 'http://erol.github.com/later'
 
   gem.files         = `git ls-files`.split($\)

data/lib/later.rb

@@ -18,101 +18,111 @@ module Later
       end
     end
 
-    # Get the Nest key of the schedule.
+    # Returns the Nest key of this schedule.
+    #
+    #   Later[:reservations].key #=> Later:reservations
     #
-    #   Later[:reservations].key #=> Later::reservations
-
     def key
       @key
     end
 
-    # Get the Nest key of the schedule exception list.
+    # Returns the Nest key of this schedule's exception list.
+    #
+    #   Later[:reservations].exceptions #=> Later:reservations:exceptions
     #
-    #   Later[:reservations].exceptions #=> Later::reservations::exceptions
-
     def exceptions
       @exceptions ||= key[:exceptions]
     end
 
-    # Get the schedule time of a unique event.
+    # Returns the time of a scheduled unique event.
     #
     #   Later[:reservations].set 'event-1', Time.parse('2012-09-28 11:36:17 +0800')
     #   Later[:reservations]['event-1'] #=> 2012-09-28 11:36:17 +0800
-
+    #
     def [](event)
       Time.at key[:schedule].zscore(event) rescue nil
     end
 
-    # Gets the number of unique scheduled events.
+    # Returns the number of scheduled unique events.
     #
     #   Later[:reservations].set 'event-1', Time.now + 60
     #   Later[:reservations].set 'event-2', Time.now + 120
     #   Later[:reservations].set 'event-3', Time.now + 180
     #   Later[:reservations].count #=> 3
-
+    #
     def count
       key[:schedule].zcard
     end
 
-    # Set a unique event to the schedule.
-    #
+    # Returns `true` if there are no scheduled unique events. Returns `false` otherwise.
     #   Later[:reservations].set 'event-1', Time.now + 60
+    #   Later[:reservations].empty? #=> false
+    #   Later[:reservations].unset 'event-1'
+    #   Later[:reservations].empty? #=> true
+    #
+    def empty?
+      count.zero?
+    end
 
+    # Sets a unique event to this schedule.
+    #
+    #   Later[:reservations].set 'event-1', Time.now + 60
+    #
     def set(event, time)
-      key[:schedule].zadd time.to_i, event
+      key[:schedule].zadd time.to_f, event
     end
 
-    # Unset a unique event from the schedule.
+    # Unsets a unique event from this schedule.
+    #
+    #   Later[:reservations].unset 'event-1'
     #
-    #   Later[:reservations].unset 'event-2'
-
     def unset(event)
       key[:schedule].zrem event
     end
 
-    # When called inside an `each` block, `stop!` signals the block to halt processing of the schedule.
+    # When called inside an `each` block, `stop!` signals the block to halt processing of this schedule.
     #
     #   Later[:reservations].each do |event|
     #     Later[:reservations].stop!
     #   end
-
+    #
     def stop!
       @stop = true
     end
 
-    # Process each event on the schedule. The block only gets called when an event is due to run based on the current time.
+    # Processes each scheduled unique event. The block only gets called when an event is due to run based on the current time.
+    #
+    # Accepts an optional `timeout` parameter with a default value of `1`. Passing an `Integer` will use Redis' blocking mechanism
+    # to process the schedule and is therefore more efficient. Passing a `Float` will poll Redis using the given timeout, and should
+    # only be used for events which need to be triggered with millisecond precision.
     #
     #   Later[:reservations].each do |event|
     #     # Do something with the event
     #   end
-
-    def each(&block)
+    #
+    # The schedule will be polled every 0.1 seconds:
+    #
+    #   Later[:reservations].each(0.1) do |event|
+    #     # Do something with the event
+    #   end
+    #
+    def each(timeout = 1, &block)
       @stop = false
 
       loop do
         break if stop?
 
-        time = Time.now.to_i
+        time = Time.now.to_f
 
-        ids = schedule.redis.multi do
-          schedule.zrangebyscore '-inf', time
-          schedule.zremrangebyscore '-inf', time
-        end.first
-
-        key.redis.multi do
-          ids.each { |id| queue.lpush id }
-        end
-
-        event = queue.brpoplpush(backup, 1)
-
-        next unless event
+        push_to_queue pop_from_schedules(time)
+        next unless event = pop_from_queue(timeout)
 
         begin
           block.call event
         rescue Exception => e
           exceptions.rpush JSON(time: Time.now, event: event, message: e.inspect)
         ensure
-          backup.del
+          local.del
         end
       end
     end
@@ -127,22 +137,49 @@ module Later
       @queue ||= key[:queue]
     end
 
-    def backup
-      @backup ||= queue[Socket.gethostname][Process.pid]
+    def local
+      @local ||= queue[Socket.gethostname][Process.pid]
+    end
+
+    def pop_from_schedules(time)
+      schedule.redis.multi do
+        schedule.zrangebyscore '-inf', time
+        schedule.zremrangebyscore '-inf', time
+      end.first
+    end
+
+    def push_to_queue(ids)
+      key.redis.multi do
+        ids.each { |id| queue.lpush id }
+      end
+    end
+
+    def pop_from_queue(timeout)
+      if timeout.is_a? Integer
+        queue.brpoplpush(local, timeout)
+      else
+        result = queue.rpoplpush(local)
+        sleep timeout unless result
+        result
+      end
     end
   end
 
   @schedules = {}
 
+  # Returns the Nest key of this module.
+  #
+  #   Later[:reservations].key #=> Later::reservations
+  #
   def self.key
     Nest.new('Later')
   end
 
+  # The easiest way to create or reference a schedule. Returns an instance of a Later::Schedule with the given key.
+  #
+  #   Later[:reservations] #=> #<Later::Schedule:0x007faf3b054f50 @key="Later:reservations">
+  #
   def self.[](schedule)
-    if @schedules[schedule.to_sym]
-      @schedules[schedule.to_sym]
-    else
-      @schedules[schedule.to_sym] = Schedule.new schedule
-    end
+    @schedules[schedule.to_sym] ||= Schedule.new schedule
   end
 end

data/lib/later/version.rb

@@ -1,3 +1,3 @@
 module Later
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'
 end

data/test/helper.rb

@@ -1,17 +1,3 @@
 require 'bundler/setup'
 require 'later'
 require 'minitest/autorun'
-
-class MiniTest::Unit::TestCase
-  def setup
-    system 'redis-server', File.join(File.dirname(__FILE__), 'redis.conf')
-    until File.exist? 'redis.pid'
-      sleep 0.1
-    end
-  end
-
-  def teardown
-    system "kill `cat redis.pid`"
-    sleep 0.1
-  end
-end

data/test/specs/later-schedule.rb

@@ -0,0 +1,74 @@
+require_relative '../helper.rb'
+
+describe Later::Schedule do
+  let(:redis) { Redis.new db: 15 }
+  let(:key) { Nest.new 'Events', redis }
+  let(:schedule) { Later::Schedule.new key }
+
+  before do
+    redis.flushdb
+  end
+
+  describe '#set' do
+    it 'sets a unique event schedule' do
+      time = Time.now
+
+      schedule.set 'event', time
+
+      assert_equal 1, schedule.count
+      assert_in_delta time, schedule['event'], 0.1
+    end
+  end
+
+  describe '#unset' do
+    it 'unsets a unique event schedule' do
+      time = Time.now
+
+      schedule.set 'event', time
+      schedule.unset 'event'
+
+      assert_equal 0, schedule.count
+      assert_equal nil, schedule['event']
+    end
+  end
+
+  describe '#count' do
+    it 'counts the number of unique event schedules' do
+      time = Time.now
+
+      1.upto(3) do |i|
+        schedule.set i.to_s, time
+        assert_equal i, schedule.count
+      end
+
+      1.upto(3) do |i|
+        schedule.unset i.to_s
+        assert_equal 3 - i, schedule.count
+      end
+    end
+  end
+
+  describe '#each' do
+    it 'logs exceptions raised within the block' do
+      0.upto(2) do |i|
+        schedule.set i, Time.now
+      end
+
+      Thread.new do
+        sleep 3
+        schedule.stop!
+      end
+
+      schedule.each do |event|
+        raise Exception, "an unknown error for #{event} has occurred"
+      end
+
+      exceptions = schedule.exceptions.lrange(0, -1).map{ |e| JSON(e) }
+
+      0.upto(2) do |i|
+        assert_equal i.to_s, exceptions[i]['event']
+        assert_equal "#<Exception: an unknown error for #{i} has occurred>", exceptions[i]['message']
+      end
+    end
+  end
+end

data/test/specs/later.rb

@@ -0,0 +1,15 @@
+require_relative '../helper.rb'
+
+describe Later do
+  let(:redis) { Redis.new db: 15 }
+  let(:key) { Nest.new 'Events', redis }
+
+  describe '.[]' do
+    it 'returns a schedule with the given key' do
+      schedule = Later[key]
+
+      assert_instance_of Later::Schedule, schedule
+      assert_equal key, schedule.key
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: later
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-28 00:00:00.000000000 Z
+date: 2012-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -91,7 +91,7 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Later is a Redis-backed event scheduling library for Ruby
+description: Lean Redis-backed event scheduling library for Ruby
 email:
 - erol.fornoles@gmail.com
 executables: []
@@ -107,8 +107,9 @@ files:
 - lib/later.rb
 - lib/later/version.rb
 - test/helper.rb
-- test/lib/later.rb
 - test/redis.conf
+- test/specs/later-schedule.rb
+- test/specs/later.rb
 homepage: http://erol.github.com/later
 licenses: []
 post_install_message: 
@@ -132,8 +133,9 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Later is a Redis-backed event scheduling library for Ruby
+summary: Lean Redis-backed event scheduling library for Ruby
 test_files:
 - test/helper.rb
-- test/lib/later.rb
 - test/redis.conf
+- test/specs/later-schedule.rb
+- test/specs/later.rb

data/test/lib/later.rb

@@ -1,103 +0,0 @@
-require_relative '../helper.rb'
-
-class LaterTest < MiniTest::Unit::TestCase
-  def setup
-    super
-
-    @redis = Redis.new host: '127.0.0.1', port: 6666
-    @key = Nest.new 'Events', @redis
-  end
-
-  def test_set_a_unique_event_schedule
-    time = Time.now
-
-    Later[@key].set '1', time
-
-    assert_equal 1, Later[@key].count
-    assert_in_delta time, Later[@key]['1'], 1
-  end
-
-  def test_unset_a_unique_event_schedule
-    time = Time.now
-
-    Later[@key].set '1', time
-    Later[@key].unset '1'
-
-    assert_equal 0, Later[@key].count
-    assert_equal nil, Later[@key]['1']
-  end
-
-  def test_count_set_and_unset_event_schedules
-    time = Time.now
-
-    1.upto(3) do |i|
-      Later[@key].set i.to_s, time
-      assert_equal i, Later[@key].count
-    end
-
-    1.upto(3) do |i|
-      Later[@key].unset i.to_s
-      assert_equal 3 - i, Later[@key].count
-    end
-  end
-
-  def test_process_many_event_schedules
-    start = Time.now + 2
-
-    times = []
-    schedules = Hash.new { |h,k| h[k] = [] }
-
-    1.upto(100) do |i|
-      time = start + i / 10
-      times.unshift time
-      schedules[time].unshift event: i.to_s, time: time
-    end
-
-    times.map{ |time| schedules[time] }.flatten.shuffle.each do |schedule|
-      Later[@key].set schedule[:event], schedule[:time]
-    end
-
-    Thread.new do
-      sleep 2 + 10 + (start - Time.now).to_i
-      Later[@key].stop!
-    end
-
-    Later[@key].each do |event|
-      time = times.pop
-
-      assert_in_delta time, Time.now, 1.2
-      assert_includes schedules[time], {event: event, time: time}
-    end
-
-    assert_equal 0, Later[@key].count
-  end
-
-  def test_exceptions_raised_within_the_worker_loop_are_handled_and_logged
-    start = Time.now + 2
-
-    1.upto(3) do |i|
-      Later[@key].set i.to_s, start + i
-    end
-
-    Thread.new do
-      sleep 2 + 3 + (start - Time.now).to_i
-      Later[@key].stop!
-    end
-
-    Later[@key].each do |event|
-      raise Exception, "an unknown error for #{event} has occurred"
-    end
-
-    assert_equal 0, Later[@key].count
-
-    exceptions = Later[@key].exceptions.lrange 0, -1
-    exceptions = exceptions.map{ |e| JSON(e) }
-
-    assert_equal '1', exceptions[0]['event']
-    assert_equal '#<Exception: an unknown error for 1 has occurred>', exceptions[0]['message']
-    assert_equal '2', exceptions[1]['event']
-    assert_equal '#<Exception: an unknown error for 2 has occurred>', exceptions[1]['message']
-    assert_equal '3', exceptions[2]['event']
-    assert_equal '#<Exception: an unknown error for 3 has occurred>', exceptions[2]['message']
-  end
-end