rufus-scheduler 1.0.14 → 2.0.0

data/CHANGELOG.txt

@@ -2,87 +2,7 @@
 = rufus-scheduler CHANGELOG.txt
 
 
-== rufus-scheduler - 1.0.14    released 2009/05/01
+== rufus-scheduler - 2.0.0    released 2009/05/07
 
-- bug   #25746 : at/every/in scheduling stress issue.
-                 Fixed by Klaas Jan Wierenga
-
-
-== rufus-scheduler - 1.0.13    released 2009/02/02
-
-- todo  #23779 : removed lib/openwfe/ and restructured to lib/rufus/scheduler/
-- todo  #23774 : adapted to Ruby 1.9.1
-- todo  #23483 : removed gemspec from Rakefile
-- bug   #23458 : :timeout not working on JRuby (reported by Chris Evans). Fixed.
-- patch #23430 : gemspec patch by Ryan Sonnek
-- patch #23412 : faster CronLine#next_time patch by TobyH
-
-
-== rufus-scheduler - 1.0.12    released 2008/12/18
-
-- todo  #23257 : added :timeout parameter for cron/in/at/every
-- bug   #22546 : added note about CronLine#next_time, K Liu
-- todo  #22489 : find_jobs(tag=nil) patch by Xianhang Zhang
-
-
-== rufus-scheduler - 1.0.11    released 2008/09/03
-
-- todo  #21781 : added lib/rufus-scheduler.rb to make Railsists' lives easier
-
-
-== rufus-scheduler - 1.0.10    released 2008/08/28
-
-- todo  #21357 : added Rufus::Scheduler::VERSION
-- bug   #21358 : start_new() not accepting parameters. Fixed.
-
-
-== rufus-scheduler - 1.0.9    released 2008/07/18
-
-- bug   #21262 : brought back (proxy) duration_to_f to Rufus::Scheduler
-- todo  #21251 : added 'at', 'cron', 'in' and 'every' shortcut methods
-- todo  #21203 : keeping track of At and EveryJob until last trigger is over
-- todo  #20823 : now raising exception in case of bad 'at' parameter
-- todo  #21194 : added trigger_thread to Job class
-- todo  #21193 : spinned CronLine out to rufus/cronline.rb
-- bug   #20893 : sometimes unschedule(every_job) not working when job was
-                 active (performing). Fixed.
-
-
-== rufus-scheduler - 1.0.7    released 2008/06/16
-
-- todo  #20669 : implemented CronJob.next_time()
-- todo  #20667 : now passing params to schedule() blocks as well.
-- bug   #20648 : find_schedulable(tag) broken. Fixed.
-
-
-== rufus-scheduler - 1.0.6    released 2008/05/02
-
-- bug   #20476 : no cron jobs on sundays (wday == 0). Fixed.
-                 (thanks to Manfred Usselmann)
-- todo  #19619 : added :thread_name options to Scheduler.new
-- source moved to http://github.com/jmettraux/rufus-scheduler
-
-
-== rufus-scheduler - 1.0.5    released 2008/03/17
-
-- bug   #18363 : constrained precision to 0.0 < p <= 1.0 - s188
-- todo  #18821 : best effort drift correction integrated - s187
-- bug   #18513 : 0 seconds and :drop_seconds => "0m". Fixed - s186
-
-
-== rufus-scheduler - 1.0.4    released 2008/02/29
-
-- todo  #18474 : implemented to_duration_array() - s183
-- todo  #18472 : added Rufus::to_time_string - s181
-
-
-== rufus-scheduler - 1.0.2    released 2008/01/26
-
-- patch #17505 : added params :first_at and :first_in for schedule_every()
-                 a patch by John Didion - s115
-
-
-== rufus-scheduler - 1.0    released 2008/01/24
-
-- initial release after "openwferu-scheduler" - 0.9.16
+- initial release
 

data/CREDITS.txt

@@ -1,15 +1,16 @@
 
 = CREDITS.txt
 
+
 == Contributors
 
-- Klaas Jan Wierenga, at/every/in stress tests, stress patch
+- Klaas Jan Wierenga, at/every/in stress tests (1.0 and 2.0)
 - TobyH (http://github.com/tobyh), faster and cleaner CronLine#next_time
-- Ryan Sonnek (http://github.com/wireframe), gemspec
 
 
 == Feedback
 
+- Kenneth Kalmer (daemon-kit)
 - Chris Evans, :timeout tests on JRuby
 - Tim Uckun, :timeout concept
 - K Liu, for the note about CronLine#next_time
@@ -23,3 +24,8 @@
 * many people gave feedback previously, see
   http://openwferu.rubyforge.org/svn/trunk/openwfe-ruby/CREDITS.txt
 
+
+== and finally
+
+- many thanks to the EventMachine team (especially Aman Gupta)
+

data/README.rdoc

@@ -0,0 +1,359 @@
+
+= rufus-scheduler
+
+rufus-scheduler is a Ruby gem for scheduling pieces of code (jobs). It understands running a job AT a certain time, IN a certain time, EVERY x time or simply via a CRON statement.
+
+rufus-scheduler is no replacement for cron/at since it runs inside of Ruby.
+
+
+== alternatives / complements
+
+A list of related Ruby projects :
+
+http://github.com/javan/whenever
+http://github.com/yakischloba/em-timers/
+
+More like complements :
+
+http://github.com/mojombo/chronic/
+http://github.com/hpoydar/chronic_duration
+
+
+== installation
+
+  sudo gem install rufus-scheduler
+
+
+== usage
+
+The usage is similar to the one of the old rufus-scheduler. There are a few differences though.
+
+  require 'rubygems'
+  require 'rufus/scheduler'
+
+  scheduler = Rufus::Scheduler.start_new
+
+  scheduler.in '20m' do
+    puts "order ristretto"
+  end
+
+  scheduler.at 'Thu Mar 26 07:31:43 +0900 2009' do
+    puts 'order pizza'
+  end
+
+  scheduler.cron '0 22 * * 1-5' do
+    # every day of the week at 00:22
+    puts 'activate security system'
+  end
+
+  scheduler.every '5m' do
+    puts 'check blood pressure'
+  end
+
+  # ...
+
+  scheduler.stop
+
+
+This code summons a plain version of the scheduler, this can be made more explicit via :
+
+  scheduler = Rufus::Scheduler::PlainScheduler.start_new
+
+This PlainScheduler accepts a :thread_name option :
+
+  scheduler = Rufus::Scheduler::PlainScheduler.start_new(:thread_name => 'my scheduler')
+
+might be helpful when tracking threads.
+
+
+Note that is there is EventMachine present and running,
+
+  scheduler = Rufus::Scheduler.start_new
+
+will return an instance of Rufus::Scheduler::EmScheduler (leveraging EventMachine).
+
+
+== block parameters
+
+Scheduled blocks accept 0 or 1 parameter (this unique parameter is the job
+instance itself).
+
+  scheduler.every '5m' do
+    puts 'check blood pressure'
+  end
+  scheduler.every '1y' do |job|
+    puts "check cholesterol levels (#{job.job_id})"
+  end
+
+See the class Job for more details :
+
+http://rufus.rubyforge.org/rufus-scheduler/classes/Rufus/Scheduler/Job.html
+
+
+== the time strings understood by rufus-scheduler
+
+  require 'rubygems'
+  require 'rufus/scheduler'
+
+  p Rufus.parse_time_string '500'      # => 0.5
+  p Rufus.parse_time_string '1000'     # => 1.0
+  p Rufus.parse_time_string '1h'       # => 3600.0
+  p Rufus.parse_time_string '1h10s'    # => 3610.0
+  p Rufus.parse_time_string '1w2d'     # => 777600.0
+
+  p Rufus.to_time_string 60              # => "1m"
+  p Rufus.to_time_string 3661            # => "1h1m1s"
+  p Rufus.to_time_string 7 * 24 * 3600   # => "1w"
+
+
+== :blocking
+
+Jobs will, by default, trigger in their own thread. This is usually desirable since one expects the scheduler to continue scheduling even if a job is currently running.
+
+Jobs scheduled with the :blocking parameter will run in the thread of the scheduler, blocking it.
+
+  scheduler.in '20m', :blocking => true do
+    puts "order ristretto"
+    sleep 2 * 60
+  end
+  scheduler.in '21m' do
+    puts "order espresso"
+  end
+
+Hence, our espresso wil come in 22 minutes instead of 21.
+
+
+== 'every' jobs and :first_at / :first_in
+
+This job will execute every 3 days, but first time will be in 5 days from now :
+
+  scheduler.every '3d', :first_in => '5d' do
+    # do something
+  end
+
+This job will execute every 3 days, starting from Christmas Eve at noon :
+
+  scheduler.every '3d', :first_at => '2009/12/24 12:00' do
+    # do something
+  end
+
+The chronic gem may help (http://chronic.rubyforge.org/) :
+
+  require 'chronic' # sudo gem install chronic
+
+  scheduler.every '3h', :first_at => Chronic.parse('this tuesday 5:00') do
+    # do something starting this tueday
+  end
+
+
+== self unschedule for 'cron' and 'every' jobs
+
+'at' and 'in' jobs fire once only. 'cron' and 'every' jobs do fire repeatedly, so it might be useful to stop them.
+
+  scheduler.every '3d' do |job|
+    l = determine_crop_maturity_level()
+    if l >= 7
+      puts "crop is ready."
+      job.unschedule
+    else
+      puts "crop not yet ready..."
+    end
+  end
+
+In this example, the 'every' job will unschedule itself when the crop is ready.
+
+
+== schedulables
+
+Sometimes passing a block isn't that convenient :
+
+  class JobThing
+    def initialize (relevant_info)
+      @ri = relevant_info
+    end
+    def call (job)
+      do_something_about_it
+    end
+  end
+
+  # ...
+
+  scheduler.in '3d', JobThing.new('http://news.example.com/data_xyz')
+  scheduler.in '1w', JobThing.new('http://news.example.com/data_abc'), :timeout => '1d'
+
+rufus-scheduler accepts anything that responds to a call method with a unique parameter (it will pass the job) as a 'schedulable'.
+
+
+== looking up jobs
+
+  scheduler.jobs
+    # returns a map job_id => job of at/in/every jobs
+
+  scheduler.cron_jobs
+    # idem for cron jobs
+
+  scheduler.all_jobs
+    # idem but for every/at/in/cron jobs (all of them)
+
+  scheduler.find_by_tag(t)
+    # returns all the jobs with a given tag (passed at schedule time with :tags)
+
+
+== unscheduling jobs
+
+The 'scheduling' methods always return an instance of Rufus::Scheduler::Job. This object can be used for unscheduling :
+
+  job = scheduler.in '2d', :tags => 'admin' do
+    run_backlog_cleaning()
+  end
+
+  # later ...
+
+  job.unschedule
+    # or
+  scheduler.unschedule(job.job_id)
+
+
+== tags
+
+You can specify tags at schedule time :
+
+  scheduler.in '2d', :tags => 'admin' do
+    run_backlog_cleaning()
+  end
+  scheduler.every '3m', :tags => 'production' do
+    check_order_log()
+  end
+
+And later query the scheduler for those jobs :
+
+  admin_jobs = scheduler.find_by_tag('admin')
+  production_jobs = scheduler.find_by_tag('production')
+
+
+== timeout
+
+One can specify a timeout for the triggering of a job.
+
+  scheduler.every '2d', :timeout => '40m' do
+    begin
+      run_backlog_cleaning()
+    rescue Rufus::Scheduler::TimeOutError => toe
+      # timeout occurred
+    end
+  end
+
+This job will run every two days. If a run takes more than 40 minutes it will timeout (its thread will receive a TimeOutError).
+
+This timeout feature relies on an 'in' job scheduled at the moment the main job gets triggered, hence the '40m' time string format.
+
+
+== exceptions in jobs
+
+By default, when exception occur when a job performs, the error message will be output to the STDOUT.
+
+It's easy to customize that behaviour :
+
+  scheduler = Rufus::Scheduler::PlainScheduler.start_new
+    # or
+  #scheduler = Rufus::Scheduler::EmScheduler.start_new
+
+  def scheduler.handle_exception (job, exception)
+    puts "job #{job.job_id} caught exception '#{exception}'"
+  end
+
+For backward compatibility, overriding #log_exception is still OK :
+
+  def scheduler.log_exception (exception)
+    puts "caught exception '#{exception}'"
+  end
+
+Note that an every job or a cron job will stay scheduled even if it experiences an exception.
+
+
+== frequency
+
+The default frequency for the scheduler is 0.330 seconds. This means that the usual scheduler implementation will wake up, trigger jobs that are to be triggered and then go back to sleep for 0.330 seconds. Note that this doesn't mean that the scheduler will wake up very 0.330 seconds (checking and triggering do take time).
+
+You can set a different frequency when starting / initializing the scheduler :
+
+  require 'rubygems'
+  require 'rufus/scheduler'
+
+  scheduler = Rufus::Scheduler.start_new(:frequency => 60.0)
+    # for a lazy scheduler that only wakes up every 60 seconds
+
+
+== usage with EventMachine
+
+rufus-scheduler 2.0 can be used in conjunction with EventMachine (http://github.com/eventmachine/eventmachine/).
+
+More and more ruby applications are using EventMachine. This flavour of the scheduler relies on EventMachine, thus it doesn't require a separate thread like the PlainScheduler does.
+
+  require 'rubygems'
+  require 'eventmachine'
+
+  EM.run {
+
+    scheduler = Rufus::Scheduler::EmScheduler.start_new
+
+    scheduler.in '20m' do
+      puts "order ristretto"
+    end
+  }
+
+
+== tested with
+
+ruby 1.8.6, ruby 1.9.1p0
+on jruby 1.2.0 it has some tiny issues (spec/blocking_spec.rb)
+
+
+== dependencies
+
+the ruby gem 'eventmachine' if you use Rufus::Scheduler::EmScheduler, else no other dependencies.
+
+
+== mailing list
+
+On the rufus-ruby list :
+
+http://groups.google.com/group/rufus-ruby
+
+
+== issue tracker
+
+http://rubyforge.org/tracker/?atid=18584&group_id=4812&func=browse
+
+
+== irc
+
+  irc.freenode.net #ruote
+
+
+== source
+
+http://github.com/jmettraux/rufus-scheduler
+
+  git clone git://github.com/jmettraux/rufus-scheduler.git
+
+
+== credits
+
+http://github.com/jmettraux/rufus-scheduler/blob/master/CREDITS.txt
+
+
+== authors
+
+John Mettraux, jmettraux@gmail.com, http://jmettraux.wordpress.com
+
+
+== the rest of Rufus
+
+http://rufus.rubyforge.org
+
+
+== license
+
+MIT
+