rufus-scheduler 3.0.2 → 3.0.3

data/CHANGELOG.txt

@@ -2,6 +2,13 @@
 = rufus-scheduler CHANGELOG.txt
 
 
+== rufus-scheduler - 3.0.3    released 2013/12/12
+
+- CronLine#previous_time fix by Yassen Bantchev (https://github.com/yassenb)
+- introduce ZookeptScheduler example in the readme
+- rename #consider_lockfile to #lock and introduce #unlock
+
+
 == rufus-scheduler - 3.0.2    released 2013/10/22
 
 - default :max_work_threads to 28

data/CREDITS.txt

@@ -4,6 +4,8 @@
 
 == Contributors
 
+- Yassen Bantchev (https://github.com/yassenb) CronLine#previous_time rewrite
+- Eric Lindvall (https://github.com/eric) Zookeeper locked example
 - Ted Pennings (https://github.com/tedpennings) typo in post_install_message
 - Tobias Kraze (https://github.com/kratob) timeout vs mutex fix
 - Patrick Farrell (https://github.com/pfarrell) pointing at deprecated start_new

data/README.md

@@ -802,6 +802,10 @@ Shuts down the scheduler, waits (blocks) until all the jobs cease running.
 
 Kills all the job (threads) and then shuts the scheduler down. Radical.
 
+### Scheduler#down?
+
+Returns true if the scheduler has been shut down.
+
 ### Scheduler#join
 
 Let's the current thread join the scheduling thread in rufus-scheduler. The thread comes back when the scheduler gets shut down.
@@ -964,6 +968,8 @@ The idea is to guarantee only one scheduler (in a group of scheduler sharing the
 
 This is useful in environments where the Ruby process holding the scheduler gets started multiple times.
 
+If the lockfile mechanism here is not sufficient, you can plug your custom mechanism. It's explained in [advanced lock schemes](#advanced-lock-schemes) below.
+
 ### :max_work_threads
 
 In rufus-scheduler 2.x, by default, each job triggering received its own, new, hthread of execution. In rufus-scheduler 3.x, execution happens in a work thread and the max work thread count defaults to 28.
@@ -1004,6 +1010,53 @@ Rufus::Scheduler.s.every '10s' { puts "hello, world!" }
 ```
 
 
+## advanced lock schemes
+
+As seen above, rufus-scheduler proposes the :lockfile system out of the box. If in a group of schedulers only one is supposed to run, the lockfile mecha prevents schedulers that have not set/created the lockfile from running.
+
+There are situation where this is not sufficient.
+
+By overriding #lock and #unlock, one can customize how his schedulers lock.
+
+This example was provided by [Eric Lindvall](https://github.com/eric):
+
+```ruby
+class ZookeptScheduler < Rufus::Scheduler
+
+  def initialize(zookeeper, opts={})
+    @zk = zookeeper
+    super(opts)
+  end
+
+  def lock
+    @zk_locker = @zk.exclusive_locker('scheduler')
+    @zk_locker.lock # returns true if the lock was acquired, false else
+  end
+
+  def unlock
+    @zk_locker.unlock
+  end
+
+  def confirm_lock
+    return false if down?
+    @zk_locker.assert!
+  rescue ZK::Exceptions::LockAssertionFailedError => e
+    # we've lost the lock, shutdown (and return false to at least prevent
+    # this job from triggering
+    shutdown
+    false
+  end
+end
+```
+
+This uses a [zookeeper](http://zookeeper.apache.org/) to make sure only one scheduler in a group of distributed schedulers runs.
+
+The methods #lock and #unlock are overriden and #confirm_lock is provided,
+to make sure that the lock is still valid.
+
+The #confirm_lock method is called right before a job triggers (if it is provided). The more generic callback #on_pre_trigger is called right after #confirm_lock.
+
+
 ## parsing cronlines and time strings
 
 Rufus::Scheduler provides a class method ```.parse``` to parse time durations and cron strings. It's what it's using when receiving schedules. One can use it diectly (no need to instantiate a Scheduler).
@@ -1052,6 +1105,58 @@ Rufus::Scheduler.to_duration_hash(62.127, :drop_seconds => true)
   # => { :m => 1 }
 ```
 
+### cronline notations specific to rufus-scheduler
+
+#### first Monday, last Sunday et al
+
+To schedule something at noon every first Monday of the month:
+
+```ruby
+scheduler.cron('00 12 * * mon#1') do
+  # ...
+end
+```
+
+To schedule something at noon the last Sunday of every month:
+
+```ruby
+scheduler.cron('00 12 * * sun#-1') do
+  # ...
+end
+#
+# OR
+#
+scheduler.cron('00 12 * * sun#L') do
+  # ...
+end
+```
+
+Such cronlines can be tested with scripts like:
+
+```ruby
+require 'rufus-scheduler'
+
+Time.now
+  # => 2013-10-26 07:07:08 +0900
+Rufus::Scheduler.parse('* * * * mon#1').next_time
+  # => 2013-11-04 00:00:00 +0900
+```
+
+#### L (last day of month)
+
+L can be used in the "day" slot:
+
+In this example, the cronline is supposed to trigger every last day of the month at noon:
+
+```ruby
+require 'rufus-scheduler'
+Time.now
+  # => 2013-10-26 07:22:09 +0900
+Rufus::Scheduler.parse('00 12 L * *').next_time
+  # => 2013-10-31 12:00:00 +0900
+```
+
+
 ## a note about timezones
 
 Cron schedules and at schedules support the specification of a timezone.

data/lib/rufus/scheduler.rb

@@ -38,7 +38,7 @@ module Rufus
     require 'rufus/scheduler/cronline'
     require 'rufus/scheduler/job_array'
 
-    VERSION = '3.0.2'
+    VERSION = '3.0.3'
 
     #
     # A common error class for rufus-scheduler
@@ -93,7 +93,7 @@ module Rufus
 
       @thread_key = "rufus_scheduler_#{self.object_id}"
 
-      consider_lockfile || return
+      lock || return
 
       start
     end
@@ -134,7 +134,7 @@ module Rufus
         kill_all_work_threads
       end
 
-      @lockfile.flock(File::LOCK_UN) if @lockfile
+      unlock
     end
 
     alias stop shutdown
@@ -158,6 +158,11 @@ module Rufus
       @thread.join
     end
 
+    def down?
+
+      ! @started_at
+    end
+
     def paused?
 
       @paused
@@ -403,7 +408,25 @@ module Rufus
       end
     end
 
-    def consider_lockfile
+    # Returns true if the scheduler has acquired the [exclusive] lock and
+    # thus may run.
+    #
+    # Most of the time, a scheduler is run alone and this method should
+    # return true. It is useful in cases where among a group of applications
+    # only one of them should run the scheduler. For schedulers that should
+    # not run, the method should return false.
+    #
+    # Out of the box, rufus-scheduler proposes the
+    # :lockfile => 'path/to/lock/file' scheduler start option. It makes
+    # it easy for schedulers on the same machine to determine which should
+    # run (to first to write the lockfile and lock it). It uses "man 2 flock"
+    # so it probably won't work reliably on distributed file systems.
+    #
+    # If one needs to use a special/different locking mechanism, providing
+    # overriding implementation for this #lock and the #unlock complement is
+    # easy.
+    #
+    def lock
 
       @lockfile = nil
 
@@ -433,6 +456,13 @@ module Rufus
       true
     end
 
+    # Sister method to #lock, is called when the scheduler shuts down.
+    #
+    def unlock
+
+      @lockfile.flock(File::LOCK_UN) if @lockfile
+    end
+
     def terminate_all_jobs
 
       jobs.each { |j| j.unschedule }

data/lib/rufus/scheduler/cronline.rb

@@ -122,16 +122,13 @@ class Rufus::Scheduler
     #
     def next_time(from=Time.now)
 
-      time = @timezone ? @timezone.utc_to_local(from.getutc) : from
-
-      time = time.respond_to?(:round) ? time.round : time - time.usec * 1e-6
-        # chop off subseconds (and yes, Ruby 1.8 doesn't have #round)
+      time = local_time(from)
+      time = round_to_seconds(time)
 
+      # start at the next second
       time = time + 1
-        # start at the next second
 
       loop do
-
         unless date_match?(time)
           time += (24 - time.hour) * 3600 - time.min * 60 - time.sec; next
         end
@@ -148,34 +145,38 @@ class Rufus::Scheduler
         break
       end
 
-      if @timezone
-        time = @timezone.local_to_utc(time)
-        time = time.getlocal unless from.utc?
-      end
-
-      time
+      global_time(time, from.utc?)
     end
 
-    # Returns the previous the cronline matched. It's like next_time, but
+    # Returns the previous time the cronline matched. It's like next_time, but
     # for the past.
     #
     def previous_time(from=Time.now)
 
-      # looks back by slices of two hours,
-      #
-      # finds for '* * * * sun', '* * 13 * *' and '0 12 13 * *'
-      # starting 1970, 1, 1 in 1.8 to 2 seconds (says Rspec)
+      time = local_time(from)
+      time = round_to_seconds(time)
 
-      start = current = from - 2 * 3600
-      result = nil
+      # start at the previous second
+      time = time - 1
 
       loop do
-        nex = next_time(current)
-        return (result ? result : previous_time(start)) if nex > from
-        result = current = nex
+        unless date_match?(time)
+          time -= time.hour * 3600 + time.min * 60 + time.sec + 1; next
+        end
+        unless sub_match?(time, :hour, @hours)
+          time -= time.min * 60 + time.sec + 1; next
+        end
+        unless sub_match?(time, :min, @minutes)
+          time -= time.sec + 1; next
+        end
+        unless sub_match?(time, :sec, @seconds)
+          time -= 1; next
+        end
+
+        break
       end
 
-      # never reached
+      global_time(time, from.utc?)
     end
 
     # Returns an array of 6 arrays (seconds, minutes, hours, days,
@@ -199,6 +200,27 @@ class Rufus::Scheduler
     # Returns the shortest delta between two potential occurences of the
     # schedule described by this cronline.
     #
+    # .
+    #
+    # For a simple cronline like "*/5 * * * *", obviously the frequency is
+    # five minutes. Why does this method look at a whole year of #next_time ?
+    #
+    # Consider "* * * * sun#2,sun#3", the computed frequency is 1 week
+    # (the shortest delta is the one between the second sunday and the third
+    # sunday). This method takes no chance and runs next_time for the span
+    # of a whole year and keeps the shortest.
+    #
+    # Of course, this method can get VERY slow if you call on it a second-
+    # based cronline...
+    #
+    # Since it's a rarely used method, I haven't taken the time to make it
+    # smarter/faster.
+    #
+    # One obvious improvement would be to cache the result once computed...
+    #
+    # See https://github.com/jmettraux/rufus-scheduler/issues/89
+    # for a discussion about this method.
+    #
     def frequency
 
       delta = 366 * DAY_S
@@ -380,6 +402,24 @@ class Rufus::Scheduler
 
       [ "#{WEEKDAYS[date.wday]}##{pos}", "#{WEEKDAYS[date.wday]}##{neg}" ]
     end
+
+    def local_time(time)
+      time = @timezone ? @timezone.utc_to_local(time.getutc) : time
+    end
+
+    def global_time(time, from_in_utc)
+      if @timezone
+        time = @timezone.local_to_utc(time)
+        time = time.getlocal unless from_in_utc
+      end
+
+      time
+    end
+
+    def round_to_seconds(time)
+      # Ruby 1.8 doesn't have #round
+      time.respond_to?(:round) ? time.round : time - time.usec * 1e-6
+    end
   end
 end
 

data/lib/rufus/scheduler/jobs.rb

@@ -114,7 +114,9 @@ module Rufus
 
         return if opts[:overlap] == false && running?
 
-        r = callback(:pre, time)
+        r =
+          callback(:confirm_lock, time) &&
+          callback(:on_pre_trigger, time)
 
         return if r == false
 
@@ -183,15 +185,14 @@ module Rufus
 
       protected
 
-      def callback(position, time)
+      def callback(meth, time)
 
-        name = position == :pre ? :on_pre_trigger : :on_post_trigger
+        return true unless @scheduler.respond_to?(meth)
 
-        return unless @scheduler.respond_to?(name)
+        arity = @scheduler.method(meth).arity
+        args = [ self, time ][0, (arity < 0 ? 2 : arity)]
 
-        args = @scheduler.method(name).arity < 2 ? [ self ] : [ self, time ]
-
-        @scheduler.send(name, *args)
+        @scheduler.send(meth, *args)
       end
 
       def compute_timeout
@@ -243,7 +244,7 @@ module Rufus
 
         set_next_time(true, time)
 
-        callback(:post, time)
+        callback(:on_post_trigger, time)
       end
 
       def start_work_thread

data/spec/cronline_spec.rb

@@ -322,6 +322,7 @@ describe Rufus::Scheduler::CronLine do
       pt('* * * * sun', lo(1970, 1, 1)).should == lo(1969, 12, 28, 23, 59, 00)
       pt('* * 13 * *', lo(1970, 1, 1)).should == lo(1969, 12, 13, 23, 59, 00)
       pt('0 12 13 * *', lo(1970, 1, 1)).should == lo(1969, 12, 13, 12, 00)
+      pt('0 0 2 1 *', lo(1970, 1, 1)).should == lo(1969, 1, 2, 0, 00)
 
       pt('* * * * * sun', lo(1970, 1, 1)).should == lo(1969, 12, 28, 23, 59, 59)
     end

data/spec/custom_locks_spec.rb

@@ -0,0 +1,47 @@
+
+#
+# Specifying rufus-scheduler
+#
+# Fri Nov  1 05:56:03 JST 2013
+#
+# Ishinomaki
+#
+
+require 'spec_helper'
+
+
+describe Rufus::Scheduler do
+
+  class LosingLockScheduler < Rufus::Scheduler
+
+    attr_reader :counter
+
+    def initialize
+      super
+      @counter = 0
+    end
+
+    def confirm_lock
+      @counter = @counter + 1
+      false
+    end
+  end
+
+  context 'custom locks' do
+
+    it 'does not trigger when #confirm_lock returns false' do
+
+      s = LosingLockScheduler.new
+
+      count = 0
+
+      s.in('0s') { count = count + 1 }
+
+      sleep 0.7
+
+      count.should == 0
+      s.counter.should == 1
+    end
+  end
+end
+

data/spec/scheduler_spec.rb

@@ -693,6 +693,21 @@ describe Rufus::Scheduler do
     end
   end
 
+  describe '#down?' do
+
+    it 'returns true when the scheduler is down' do
+
+      @scheduler.shutdown
+
+      @scheduler.down?.should == true
+    end
+
+    it 'returns false when the scheduler is up' do
+
+      @scheduler.down?.should == false
+    end
+  end
+
   #--
   # job methods
   #++

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rufus-scheduler
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-21 00:00:00.000000000 Z
+date: 2013-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -91,6 +91,7 @@ files:
 - spec/job_in_spec.rb
 - spec/parse_spec.rb
 - spec/scheduler_spec.rb
+- spec/custom_locks_spec.rb
 - spec/job_cron_spec.rb
 - spec/job_every_spec.rb
 - rufus-scheduler.gemspec
@@ -102,7 +103,7 @@ files:
 homepage: http://github.com/jmettraux/rufus-scheduler
 licenses:
 - MIT
-post_install_message: ! "\n***\n\nThanks for installing rufus-scheduler 3.0.2\n\nIt
+post_install_message: ! "\n***\n\nThanks for installing rufus-scheduler 3.0.3\n\nIt
   might not be 100% compatible with rufus-scheduler 2.x.\n\nIf you encounter issues
   with this new rufus-scheduler, especially\nif your app worked fine with previous
   versions of it, you can\n\nA) Forget it and peg your Gemfile to rufus-scheduler