rufus-scheduler 2.0.11 → 2.0.12

data/CHANGELOG.txt

@@ -2,6 +2,13 @@
 = rufus-scheduler CHANGELOG.txt
 
 
+== rufus-scheduler - 2.0.12    released 2011/10/28
+
+- hardened exception handling. Thanks Sam Gibson
+- accepting #handle_exception, #log_exception or #on_exception
+- scheduler.in '1s', :mutex => 'that_mutex_name'
+
+
 == rufus-scheduler - 2.0.11    released 2011/09/30
 
 - require 'rufus-scheduler' works

data/CREDITS.txt

@@ -14,6 +14,7 @@
 
 == Feedback
 
+- Sam Gibson - https://github.com/samfoo - exception handling hardening
 - sha1dy - https://github.com/sha1dy - every and overlapping exception issue
 - Defusal - unschedule_by_tag
 - pickerel - https://github.com/pickerel

data/README.rdoc

@@ -174,25 +174,82 @@ Jobs scheduled with the :blocking parameter will run in the thread of the schedu
 
 Hence, our espresso will come in 22 minutes instead of 21.
 
+Warning, 'cron' behaves a bit differently than 'in' and 'at', if the scheduler is blocked working on a task, it may skip crons (while ins and ats get scheduled after).
+
+  scheduler.cron '0 16 * * * *' do
+    puts "four o'clock tea"
+  end
+
+If at 4pm the scheduler is in a blocking task, there will be no four o'clock tea.
+
+
+== :mutex => 'that_mutex'
+
+:blocking is nice but it is blocking the whole scheduler. What about something more fine-grained ? And also something that can be used with in, at, every and cron ?
+
+  scheduler.in '20m', :mutex => 'that_mutex' do
+    puts "order ristretto"
+    sleep 2 * 60
+    puts "ah, that was delicious"
+  end
+  scheduler.in '21m' :mutex => 'that_mutex' do
+    puts "order espresso"
+  end
+
+the "order espresso" will only get triggered once the ristretto has been consumed. Rufus-scheduler, will create a 'that_mutex' mutex and keep track of it. Don't go on passing too many different mutex names, rufus-scheduler will keep track of each of them (they won't get garbage collected).
+
+It's OK to use a mutex directly:
+
+  m = Mutex.new
+  # ...
+  scheduler.cron  '0 18 * * *', :mutex => m do
+    # ...
+  end
+  scheduler.in '21m' :mutex => m do
+    # ...
+  end
+
+It can be handy for even more fine-grained control:
+
+  m = Mutex.new
+  # ...
+  scheduler.cron  '0 18 * * *', :mutex => m do
+    # ...
+  end
+  scheduler.in '21m' do
+    # non-critical
+    m.synchronize do
+      # critical
+    end
+    # non-critical
+  end
+
 
 == :allow_overlapping => false
 
-By default, every and cron jobs will "overlap" :
+By default, every and cron jobs will "overlap":
 
   scheduler.every '3s' do
-    4.times do
-      puts "hello!"
+    4.times do |i|
+      puts "hello #{i}"
       sleep 1
     end
   end
 
-This every job, will have overlaps. To prevent that :
+You mind end up with something that looks like
+
+  hello 0
+  hello 1
+  hello 2
+  hello 3
+  hello 3
+  hello 4
+  ...
+
+This every job, will have overlaps. To prevent that:
 
   scheduler.every '3s', :allow_overlapping => false do
-    4.times do
-      puts "hello!"
-      sleep 1
-    end
+    # ...
   end
 
 
@@ -347,6 +404,17 @@ It's easy to customize that behaviour :
     puts "job #{job.job_id} caught exception '#{exception}'"
   end
 
+These are OK too:
+
+  def scheduler.on_exception(job, exception)
+    puts "job #{job.job_id} caught exception '#{exception}'"
+  end
+
+  # or
+
+  def scheduler.on_exception(exception)
+    puts "caught exception '#{exception}'"
+
 For backward compatibility, overriding #log_exception is still OK :
 
   def scheduler.log_exception(exception)
@@ -398,8 +466,7 @@ https://github.com/jmettraux/rufus-scheduler/issues/issue/10
 == tested with
 
 * 1.8.7-p249
-* 1.9.1-p378
-* 1.9.2-p0
+* 1.9.2-p290
 * jruby-1.5.1
 
 on Mac OS X (Snow Leopard).

data/lib/rufus/sc/jobs.rb

@@ -133,7 +133,7 @@ module Scheduler
 
       @running = true
 
-      @scheduler.send(:trigger_job, @params[:blocking]) do
+      @scheduler.send(:trigger_job, @params) do
         #
         # Note that #trigger_job is protected, hence the #send
         # (Only jobs know about this method of the scheduler)
@@ -153,7 +153,7 @@ module Scheduler
 
         rescue Exception => e
 
-          @scheduler.handle_exception(self, e)
+          @scheduler.do_handle_exception(self, e)
         end
 
         @running = false

data/lib/rufus/sc/scheduler.rb

@@ -105,6 +105,8 @@ module Rufus::Scheduler
       @cron_jobs = get_queue(:cron, opts)
 
       @frequency = @options[:frequency] || 0.330
+
+      @mutexes = {}
     end
 
     # Instantiates and starts a new Rufus::Scheduler.
@@ -198,25 +200,42 @@ module Rufus::Scheduler
     # MISC
     #++
 
-    # Feel free to override this method. The default implementation simply
-    # outputs the error message to STDOUT
+    # Determines if there is #log_exception, #handle_exception or #on_exception
+    # method. If yes, hands the exception to it, else defaults to outputting
+    # details to $stderr.
     #
-    def handle_exception(job, exception)
+    def do_handle_exception(job, exception)
 
-      if self.respond_to?(:log_exception)
-        #
-        # some kind of backward compatibility
+      begin
 
-        log_exception(exception)
+        [ :log_exception, :handle_exception, :on_exception ].each do |m|
 
-      else
+          next unless self.respond_to?(m)
+
+          if method(m).arity == 1
+            self.send(m, exception)
+          else
+            self.send(m, job, exception)
+          end
+
+          return
+            # exception was handled successfully
+        end
 
-        puts '=' * 80
-        puts "scheduler caught exception :"
-        puts exception
-        exception.backtrace.each { |l| puts l }
-        puts '=' * 80
+      rescue Exception => e
+
+        $stderr.puts '*' * 80
+        $stderr.puts 'the exception handling method itself had an issue:'
+        $stderr.puts e
+        $stderr.puts *e.backtrace
+        $stderr.puts '*' * 80
       end
+
+      $stderr.puts '=' * 80
+      $stderr.puts 'scheduler caught exception:'
+      $stderr.puts exception
+      $stderr.puts *exception.backtrace
+      $stderr.puts '=' * 80
     end
 
     #--
@@ -339,10 +358,13 @@ module Rufus::Scheduler
     # TODO : clarify, the blocking here blocks the whole scheduler, while
     # EmScheduler blocking triggers for the next tick. Not the same thing ...
     #
-    def trigger_job(blocking, &block)
+    def trigger_job(params, &block)
 
-      if blocking
+      if params[:blocking]
         block.call
+      elsif m = params[:mutex]
+        m = (@mutexes[m.to_s] ||= Mutex.new) unless m.is_a?(Mutex)
+        Thread.new { m.synchronize { block.call } }
       else
         Thread.new { block.call }
       end
@@ -471,14 +493,20 @@ module Rufus::Scheduler
     # If 'blocking' is set to true, the block will get called at the
     # 'next_tick'. Else the block will get called via 'defer' (own thread).
     #
-    def trigger_job(blocking, &block)
+    def trigger_job(params, &block)
 
-      m = blocking ? :next_tick : :defer
-        #
-        # :next_tick monopolizes the EM
-        # :defer executes its block in another thread
+      # :next_tick monopolizes the EM
+      # :defer executes its block in another thread
+      # (if I read the doc carefully...)
 
-      EM.send(m) { block.call }
+      if params[:blocking]
+        EM.next_tick { block.call }
+      elsif m = params[:mutex]
+        m = (@mutexes[m.to_s] ||= Mutex.new) unless m.is_a?(Mutex)
+        EM.defer { m.synchronize { block.call } }
+      else
+        EM.defer { block.call }
+      end
     end
   end
 

data/lib/rufus/sc/version.rb

@@ -26,7 +26,7 @@
 module Rufus
 module Scheduler
 
-  VERSION = '2.0.11'
+  VERSION = '2.0.12'
 end
 end
 

data/lib/rufus/scheduler.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2006-2011, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

data/release.txt

@@ -0,0 +1,9 @@
+Rufus-scheduler is a thread-based scheduler written in Ruby. It lets you write code like
+
+[sourcecode language="ruby"]
+Rufus::Scheduler.start
+
+Rufus::Scheduler.every '10m' do
+end
+[/sourcecode]
+

data/rufus-scheduler.gemspec

@@ -28,7 +28,7 @@ job scheduler for Ruby (at, cron, in and every jobs).
   s.add_runtime_dependency 'tzinfo', '>= 0.3.23'
 
   s.add_development_dependency 'rake'
-  s.add_development_dependency 'rspec', '>= 2.0'
+  s.add_development_dependency 'rspec', '>= 2.7.0'
 
   s.require_path = 'lib'
 end

data/spec/at_in_spec.rb

@@ -5,7 +5,7 @@
 # Sun Mar 22 16:47:28 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe SCHEDULER_CLASS do

data/spec/at_spec.rb

@@ -5,7 +5,7 @@
 # Sat Mar 21 20:19:30 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe "#{SCHEDULER_CLASS}#schedule_at" do

data/spec/blocking_spec.rb

@@ -5,7 +5,7 @@
 # Sat Mar 21 17:36:36 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe SCHEDULER_CLASS do
@@ -29,26 +29,32 @@ describe SCHEDULER_CLASS do
     end
   end
 
-  it "doesn't block when :blocking => nil" do
+  context ':blocking => nil' do
 
-    $var = []
-    @s.in('1s') { JOB.call(1) }
-    @s.in('1s') { JOB.call(2) }
+    it "doesn't block" do
 
-    sleep 5.0
+      $var = []
+      @s.in('1s') { JOB.call(1) }
+      @s.in('1s') { JOB.call(2) }
 
-    [ %w{ a1 a2 b1 b2 }, %w{ a1 a2 b2 b1 } ].should include($var)
+      sleep 5.0
+
+      [ %w{ a1 a2 b1 b2 }, %w{ a1 a2 b2 b1 } ].should include($var)
+    end
   end
 
-  it 'blocks when :blocking => true' do
+  context ':blocking => true' do
 
-    $var = []
-    @s.in('1s', :blocking => true) { JOB.call(8) }
-    @s.in('1s', :blocking => true) { JOB.call(9) }
+    it 'blocks' do
 
-    sleep 4.5
+      $var = []
+      @s.in('1s', :blocking => true) { JOB.call(8) }
+      @s.in('1s', :blocking => true) { JOB.call(9) }
 
-    $var.should == %w[ a8 b8 a9 b9 ]
+      sleep 4.5
+
+      $var.should == %w[ a8 b8 a9 b9 ]
+    end
   end
 end
 

data/spec/cron_spec.rb

@@ -5,7 +5,7 @@
 # Sun Mar 22 19:59:12 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe "#{SCHEDULER_CLASS}#cron" do

data/spec/cronline_spec.rb

@@ -5,7 +5,7 @@
 # Sat Mar 21 12:55:27 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe Rufus::CronLine do

data/spec/every_spec.rb

@@ -5,7 +5,7 @@
 # Sun Mar 22 12:26:07 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe "#{SCHEDULER_CLASS}#every" do

data/spec/exception_spec.rb

@@ -5,7 +5,7 @@
 # Mon May  4 17:07:17 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), '/spec_base')
+require 'spec_base'
 
 
 describe SCHEDULER_CLASS do
@@ -17,13 +17,13 @@ describe SCHEDULER_CLASS do
     stop_scheduler(@s)
   end
 
-  it 'emits exception messages to stdout' do
+  it 'emits exception messages to stderr' do
 
     require 'stringio' unless defined?(StringIO) # ruby 1.9
 
-    stdout = $stdout
+    stderr = $stderr
     s = StringIO.new
-    $stdout = s
+    $stderr = s
 
     @s.in 0.400 do
       raise 'Houston we have a problem'
@@ -31,7 +31,7 @@ describe SCHEDULER_CLASS do
 
     sleep 0.500
     sleep 0.500
-    $stdout = stdout
+    $stderr = stderr
     s.close
 
     s.string.should match(/Houston we have a problem/)
@@ -55,7 +55,7 @@ describe SCHEDULER_CLASS do
     $job.class.should == Rufus::Scheduler::InJob
   end
 
-  it 'accepts overriding #log_exception' do
+  it 'accepts defining #log_exception' do
 
     $e = nil
 
@@ -72,5 +72,26 @@ describe SCHEDULER_CLASS do
 
     $e.to_s.should == 'Houston we have a problem'
   end
+
+  it 'accepts defining #on_exception' do
+
+    $j = nil
+    $e = nil
+
+    def @s.on_exception(j, e)
+      $j = j
+      $e = e
+    end
+
+    @s.in 0.400 do
+      raise 'Houston we have a problem'
+    end
+
+    sleep 0.500
+    sleep 0.500
+
+    $j.class.should == Rufus::Scheduler::InJob
+    $e.to_s.should == 'Houston we have a problem'
+  end
 end
 

data/spec/in_spec.rb

@@ -5,7 +5,7 @@
 # Sat Mar 21 17:36:36 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe "#{SCHEDULER_CLASS}#in" do

data/spec/job_spec.rb

@@ -5,7 +5,7 @@
 # Wed Apr 27 00:51:07 JST 2011
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe 'job classes' do

data/spec/mutex_spec.rb

@@ -0,0 +1,93 @@
+
+#
+# Specifying rufus-scheduler
+#
+# Fri Oct  7 17:30:45 JST 2011
+#
+
+require 'spec_base'
+
+
+describe SCHEDULER_CLASS do
+
+  before(:each) do
+    @s = start_scheduler
+  end
+  after(:each) do
+    stop_scheduler(@s)
+  end
+
+  MJOB = Proc.new do |x|
+    begin
+      $var << "in#{x}"
+      sleep 0.500
+      $var << "out#{x}"
+    rescue Exception => e
+      puts '=' * 80
+      p e
+      puts '=' * 80
+    end
+  end
+
+  context ':mutex => String' do
+
+    it 'prevents overlapping' do
+
+      $var = ''
+
+      @s.in('1s', :mutex => 'toto') { MJOB.call(0) }
+      @s.in('1s', :mutex => 'toto') { MJOB.call(1) }
+
+      sleep 3.0
+
+      %w[ in0out0in1out1 in1out1in0out0 ].should include($var)
+    end
+
+    it 'creates a new mutex when the name is first encountered' do
+
+      @s.instance_variable_get(:@mutexes).size.should == 0
+
+      @s.in('1s', :mutex => 'fruit') { sleep 0.1 }
+
+      sleep 1.5
+
+      @s.instance_variable_get(:@mutexes).size.should == 1
+    end
+
+    it 'creates a unique mutex for a given name' do
+
+      @s.in('1s', :mutex => 'gum') { sleep 0.1 }
+      @s.in('1s', :mutex => 'gum') { sleep 0.1 }
+
+      sleep 1.5
+
+      @s.instance_variable_get(:@mutexes).size.should == 1
+    end
+  end
+
+  context ':mutex => Mutex' do
+
+    it 'prevents overlapping' do
+
+      $var = ''
+      m = Mutex.new
+
+      @s.in('1s', :mutex => m) { MJOB.call(0) }
+      @s.in('1s', :mutex => m) { MJOB.call(1) }
+
+      sleep 3.0
+
+      %w[ in0out0in1out1 in1out1in0out0 ].should include($var)
+    end
+
+    it 'does not register the mutex' do
+
+      @s.in('1s', :mutex => Mutex.new) { sleep 0.1 }
+
+      sleep 1.5
+
+      @s.instance_variable_get(:@mutexes).size.should == 0
+    end
+  end
+end
+

data/spec/rtime_spec.rb

@@ -5,7 +5,7 @@
 # Fri Mar 20 23:46:32 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe 'rufus/otime' do

data/spec/schedulable_spec.rb

@@ -5,7 +5,7 @@
 # Tue May  5 14:47:16 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), '/spec_base')
+require 'spec_base'
 
 
 describe Rufus::Scheduler::Schedulable do

data/spec/scheduler_spec.rb

@@ -5,7 +5,7 @@
 # Sat Mar 21 17:43:23 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), 'spec_base')
+require 'spec_base'
 
 
 describe SCHEDULER_CLASS do

data/spec/spec_base.rb

@@ -5,12 +5,15 @@
 # Fri Mar 20 22:53:33 JST 2009
 #
 
-$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
+$:.unshift(File.expand_path('../../lib', __FILE__))
 
 require 'rubygems'
 require 'fileutils'
 
 
+Thread.abort_on_exception = true
+
+
 #$:.unshift(File.expand_path('~/tmp/bacon/lib')) # my own bacon for a while
 #require 'bacon'
 #puts
@@ -22,7 +25,7 @@ require 'fileutils'
 
 # EM or plain ?
 
-$plain = ! ARGV.include?('--em')
+$plain = ! ENV['EVENTMACHINE']
 
 require 'rufus/scheduler'
 
@@ -64,12 +67,12 @@ def stop_scheduler(s)
 end
 
 def wait_next_tick
-  if defined?(EM)
-    t = Thread.current
-    EM.next_tick { t.wakeup }
-    Thread.stop
-  else
-    sleep 0.500
-  end
+  #if defined?(EM)
+  #  t = Thread.current
+  #  EM.next_tick { t.wakeup }
+  #  Thread.stop
+  #else
+  sleep 0.500
+  #end
 end
 

data/spec/stress_schedule_unschedule_spec.rb

@@ -3,7 +3,7 @@
 # a spec by Klaas Jan Wierenga
 #
 
-require File.join(File.dirname(__FILE__), '/spec_base')
+require 'spec_base'
 
 
 

data/spec/timeout_spec.rb

@@ -5,7 +5,7 @@
 # Sun May  3 15:44:28 JST 2009
 #
 
-require File.join(File.dirname(__FILE__), '/spec_base')
+require 'spec_base'
 
 
 describe "#{SCHEDULER_CLASS} timeouts" do
@@ -94,10 +94,10 @@ describe "#{SCHEDULER_CLASS} timeouts" do
       end
     end
 
-    sleep 5
+    sleep 5.5
 
     timeouts.size.should == 3
-    timeouts.each { |to| (to * 10).to_i.should == 16 }
+    timeouts.each { |to| to.should be_within(0.5).of(1.5) }
   end
 
   it 'points to their "parent" job' do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rufus-scheduler
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: 
   segments: 
   - 2
   - 0
-  - 11
-  version: 2.0.11
+  - 12
+  version: 2.0.12
 platform: ruby
 authors: 
 - John Mettraux
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-30 00:00:00 +09:00
+date: 2011-10-28 00:00:00 +09:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -56,11 +56,12 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
+        hash: 19
         segments: 
         - 2
+        - 7
         - 0
-        version: "2.0"
+        version: 2.7.0
   type: :development
   version_requirements: *id003
 description: job scheduler for Ruby (at, cron, in and every jobs).
@@ -92,6 +93,7 @@ files:
 - spec/exception_spec.rb
 - spec/in_spec.rb
 - spec/job_spec.rb
+- spec/mutex_spec.rb
 - spec/rtime_spec.rb
 - spec/schedulable_spec.rb
 - spec/scheduler_spec.rb
@@ -105,6 +107,7 @@ files:
 - CREDITS.txt
 - dump.txt
 - LICENSE.txt
+- release.txt
 - t.txt
 - TODO.txt
 - README.rdoc