later 0.1.2 → 0.1.3

data/README.md

@@ -1,37 +1,37 @@
 # Later
 
-[**Later**](erol.github.com/later) is a Redis-backed event scheduling library for Ruby.
+[**Later**](erol.github.com/later) is a lightweight Redis-backed event scheduling library for Ruby.
 
 ## Usage
 
-Later allows you to manage schedule sets:
+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
+
+Rescheduling an event is simple:
+
+    Later[:reservations].set 'event-1', Time.now + 240
+
+And an event can also be unset:
+
+    Later[key].unset 'event-1'
+
+You can manage multiple schedules using different keys:
+
     Later[:reservations]
     Later[:appointments]
 
-The schedule sets are referenced based on the default Redis instance. If you need a schedule set which resides on a different Redis instance, you can pass a [Nest](github.com/soveran/nest) object when referencing a schedule set.
+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
 
     Later[key]
 
-Setting an event schedule is simple:
-
-    Later[key].set 'my-unique-event', Time.now + 60
-	
-And can be reschedule with equal simplicity:
-
-    Later[key].set 'my-unique-event', Time.now + 120
-
-An event schedule can also be unset:
-
-    Later[key].unset 'my-unique-event'
-	
-Note that event names should be unique in the scope of its schedule set.
-	
 ### Workers
 
 Workers are Ruby processes that run forever. They allow you to process event schedules in the background:
@@ -49,10 +49,10 @@ If for some reason, a worker has to stop itself from running:
     Later[:reservations].each do |event|
       # Do something with the event.
 
-      Later[:reservations].stop if stop?
+      Later[:reservations].stop! if stop?
     end
 
-    # This line is reached if stop? is true.
+    # This line is reached when stop? is true and Later[:reservations].stop! is called.
 
 ## Installation
 

data/later.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'redis'
   gem.add_dependency 'nest'
   gem.add_dependency 'json'
+  gem.add_dependency 'predicates'
 
   gem.add_development_dependency 'minitest'
 end

data/lib/later.rb

@@ -2,9 +2,14 @@ require 'later/version'
 require 'redis'
 require 'nest'
 require 'json'
+require 'predicates'
 
 module Later
   class Schedule
+    extend Predicates
+
+    predicate :stop?
+
     def initialize(key)
       if key.is_a?(Nest)
         @key = key
@@ -13,46 +18,86 @@ module Later
       end
     end
 
+    # Get the Nest key of the schedule.
+    #
+    #   Later[:reservations].key #=> Later::reservations
+
     def key
       @key
     end
 
+    # Get the Nest key of the schedule exception list.
+    #
+    #   Later[:reservations].exceptions #=> Later::reservations::exceptions
+
     def exceptions
       @exceptions ||= key[:exceptions]
     end
 
+    # Get the schedule time of a 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.
+    #
+    #   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.
+    #
+    #   Later[:reservations].set 'event-1', Time.now + 60
+
     def set(event, time)
       key[:schedule].zadd time.to_i, event
     end
 
+    # Unset a unique event from the schedule.
+    #
+    #   Later[:reservations].unset 'event-2'
+
     def unset(event)
       key[:schedule].zrem event
     end
 
-    def stop
+    # When called inside an `each` block, `stop!` signals the block to halt processing of the 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.
+    #
+    #   Later[:reservations].each do |event|
+    #     # Do something with the event
+    #   end
+
     def each(&block)
       @stop = false
 
       loop do
-        break if @stop
+        break if stop?
 
         time = Time.now.to_i
 
-        schedule.redis.multi
-        schedule.zrangebyscore '-inf', time
-        schedule.zremrangebyscore '-inf', time
-        ids = schedule.redis.exec.first
+        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 }

data/lib/later/version.rb

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

data/test/lib/later.rb

@@ -59,7 +59,7 @@ class LaterTest < MiniTest::Unit::TestCase
 
     Thread.new do
       sleep 2 + 10 + (start - Time.now).to_i
-      Later[@key].stop
+      Later[@key].stop!
     end
 
     Later[@key].each do |event|
@@ -81,7 +81,7 @@ class LaterTest < MiniTest::Unit::TestCase
 
     Thread.new do
       sleep 2 + 3 + (start - Time.now).to_i
-      Later[@key].stop
+      Later[@key].stop!
     end
 
     Later[@key].each do |event|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: later
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-23 00:00:00.000000000 Z
+date: 2012-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -59,6 +59,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: predicates
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement