rufus-scheduler 3.0.8 → 3.0.9

data/CHANGELOG.txt

@@ -2,6 +2,12 @@
 = rufus-scheduler CHANGELOG.txt
 
 
+== rufus-scheduler - 3.0.9    released 2014/08/30
+
+- fix TZ with underscores, thanks https://github.com/gnilrets
+- integrate https://github.com/ecin Lock mecha
+
+
 == rufus-scheduler - 3.0.8    released 2014/06/09
 
 - handle TZInfo errors on DST transitions, thanks https://github.com/junhanamaki

data/CREDITS.txt

@@ -4,6 +4,8 @@
 
 == Contributors
 
+- Sterling Paramore (https://github.com/gnilrets) underscore TZ fix
+- ecin (https://github.com/ecin) new lock mecha
 - Adam Jonas (https://github.com/adamjonas) migrate specs to "expect"
 - Yassen Bantchev (https://github.com/yassenb) CronLine#previous_time rewrite
 - Eric Lindvall (https://github.com/eric) Zookeeper locked example

data/README.md

@@ -89,6 +89,8 @@ There is no EventMachine-based scheduler anymore.
 
 So you need help. People can help you, but first help them help you, and don't waste their time. Provide a complete description of the issue. If it works on A but not on B and others have to ask you: "so what is different between A and B" you are wasting everyone's time.
 
+"hello" and "thanks" are not swear words.
+
 Go read [how to report bugs effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html), twice.
 
 Update: [help_help.md](https://gist.github.com/jmettraux/310fed75f568fd731814) might help help you.
@@ -1097,6 +1099,57 @@ This is useful in environments where the Ruby process holding the scheduler gets
 
 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.
 
+### :scheduler_lock
+
+(since rufus-scheduler 3.0.9)
+
+The scheduler lock is an object that responds to `#lock` and `#unlock`. The scheduler calls `#lock` when starting up. If the answer is `false`, the scheduler stops its initialization work and won't schedule anything.
+
+Here is a sample of a scheduler lock that only lets the scheduler on host "coffee.example.com" start:
+```ruby
+class HostLock
+  def initialize(lock_name)
+    @lock_name = lock_name
+  end
+  def lock
+    @lock_name == `hostname -f`.strip
+  end
+  def unlock
+    true
+  end
+end
+
+scheduler =
+  Rufus::Scheduler.new(:scheduler_lock => HostLock.new('coffee.example.com'))
+```
+
+By default, the scheduler_lock is an instance of `Rufus::Scheduler::NullLock`, with a `#lock` that returns true.
+
+### :trigger_lock
+
+(since rufus-scheduler 3.0.9)
+
+The trigger lock in an object that responds to `#lock`. The scheduler calls that method on the job lock right before triggering any job. If the answer is false, the trigger doesn't happen, the job is not done (at least not in this scheduler).
+
+Here is a (stupid) PingLock example, it'll only trigger if an "other host" is not responding to ping. Do not use that in production, you don't want to fork a ping process for each trigger attempt...
+```ruby
+class PingLock
+  def initialize(other_host)
+    @other_host = other_host
+  end
+  def lock
+    ! system("ping -c 1 #{@other_host}")
+  end
+end
+
+scheduler =
+  Rufus::Scheduler.new(:trigger_lock => PingLock.new('main.example.com'))
+```
+
+By default, the trigger_lock is an instance of `Rufus::Scheduler::NullLock`, with a `#lock` that always returns true.
+
+As explained in [advanced lock schemes](#advanced-lock-schemes), another way to tune that behaviour is by overriding the scheduler's `#confirm_lock` method. (You could also do that with an `#on_pre_trigger` callback).
+
 ### :max_work_threads
 
 In rufus-scheduler 2.x, by default, each job triggering received its own, brand new, thread of execution. In rufus-scheduler 3.x, execution happens in a pooled work thread. The max work thread count (the pool size) defaults to 28.
@@ -1183,6 +1236,20 @@ 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.
 
+### :scheduler_lock and :trigger_lock
+
+(introduced in rufus-scheduler 3.0.9).
+
+Another way of prodiving `#lock`, `#unlock` and `#confirm_lock` to a rufus-scheduler is by using the `:scheduler_lock` and `:trigger_lock` options.
+
+See [:trigger_lock](#trigger_lock) and [:scheduler_lock](#scheduler_lock).
+
+The scheduler lock may be used to prevent a scheduler from starting, while a trigger lock prevents individual jobs from triggering (the scheduler goes on scheduling).
+
+One has to be careful with what goes in `#confirm_lock` or in a trigger lock, as it gets called before each trigger.
+
+Warning: you may think you're heading towards "high availability" by using a trigger lock and having lots of schedulers at hand. It may be so if you limit yourself to scheduling the same set of jobs at scheduler startup. But if you add schedules at runtime, they stay local to their scheduler. There is no magic that propagates the jobs to all the schedulers in your pack.
+
 
 ## parsing cronlines and time strings
 

data/lib/rufus/scheduler.rb

@@ -26,7 +26,6 @@ require 'date' if RUBY_VERSION < '1.9.0'
 require 'time'
 require 'thread'
 require 'tzinfo'
-require 'fileutils'
 
 
 module Rufus
@@ -37,8 +36,9 @@ module Rufus
     require 'rufus/scheduler/jobs'
     require 'rufus/scheduler/cronline'
     require 'rufus/scheduler/job_array'
+    require 'rufus/scheduler/locks'
 
-    VERSION = '3.0.8'
+    VERSION = '3.0.9'
 
     #
     # A common error class for rufus-scheduler
@@ -93,7 +93,17 @@ module Rufus
 
       @thread_key = "rufus_scheduler_#{self.object_id}"
 
-      lock || return
+      @scheduler_lock =
+        if lockfile = opts[:lockfile]
+          Rufus::Scheduler::FileLock.new(lockfile)
+        else
+          opts[:scheduler_lock] || Rufus::Scheduler::NullLock.new
+        end
+
+      @trigger_lock = opts[:trigger_lock] || Rufus::Scheduler::NullLock.new
+
+      # If we can't grab the @scheduler_lock, don't run.
+      @scheduler_lock.lock || return
 
       start
     end
@@ -324,6 +334,49 @@ module Rufus
       @jobs[job_id]
     end
 
+    # 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 (the 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, the scheduler
+    # accepts :scheduler_lock => lock_object. lock_object only needs to respond
+    # to #lock
+    # and #unlock, and both of these methods should be idempotent.
+    #
+    # Look at rufus/scheduler/locks.rb for an example.
+    #
+    def lock
+
+      @scheduler_lock.lock
+    end
+
+    # Sister method to #lock, is called when the scheduler shuts down.
+    #
+    def unlock
+
+      @trigger_lock.unlock
+      @scheduler_lock.unlock
+    end
+
+    # Callback called when a job is triggered. If the lock cannot be acquired,
+    # the job won't run (though it'll still be scheduled to run again if
+    # necessary).
+    #
+    def confirm_lock
+
+      @trigger_lock.lock
+    end
+
     # Returns true if this job is currently scheduled.
     #
     # Takes extra care to answer true if the job is a repeat job
@@ -423,7 +476,8 @@ module Rufus
       stderr.puts("  #{pre}     opts:")
       stderr.puts("  #{pre}       #{@opts.inspect}")
       stderr.puts("  #{pre}       frequency: #{self.frequency}")
-      stderr.puts("  #{pre}       lockfile: #{@lockfile.inspect}")
+      stderr.puts("  #{pre}       scheduler_lock: #{@scheduler_lock.inspect}")
+      stderr.puts("  #{pre}       trigger_lock: #{@trigger_lock.inspect}")
       stderr.puts("  #{pre}     uptime: #{uptime} (#{uptime_s})")
       stderr.puts("  #{pre}     down?: #{down?}")
       stderr.puts("  #{pre}     threads: #{self.threads.size}")
@@ -468,61 +522,6 @@ module Rufus
       end
     end
 
-    # 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
-
-      return true unless f = @opts[:lockfile]
-
-      raise ArgumentError.new(
-        ":lockfile argument must be a string, not a #{f.class}"
-      ) unless f.is_a?(String)
-
-      FileUtils.mkdir_p(File.dirname(f))
-
-      f = File.new(f, File::RDWR | File::CREAT)
-      locked = f.flock(File::LOCK_NB | File::LOCK_EX)
-
-      return false unless locked
-
-      now = Time.now
-
-      f.print("pid: #{$$}, ")
-      f.print("scheduler.object_id: #{self.object_id}, ")
-      f.print("time: #{now}, ")
-      f.print("timestamp: #{now.to_f}")
-      f.flush
-
-      @lockfile = f
-
-      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/jobs.rb

@@ -117,15 +117,16 @@ module Rufus
 
       def trigger(time)
 
-        set_next_time(false, time)
+        set_next_time(time)
 
-        return if opts[:overlap] == false && running?
-
-        r =
+        return if (
+          opts[:overlap] == false &&
+          running?
+        )
+        return if (
           callback(:confirm_lock, time) &&
           callback(:on_pre_trigger, time)
-
-        return if r == false
+        ) == false
 
         @count += 1
 
@@ -272,7 +273,7 @@ module Rufus
 
       def post_trigger(time)
 
-        set_next_time(true, time)
+        set_next_time(time, true)
 
         callback(:on_post_trigger, time)
       end
@@ -356,7 +357,7 @@ module Rufus
 
       # There is no next_time for one time jobs, hence the false.
       #
-      def set_next_time(is_post, trigger_time)
+      def set_next_time(trigger_time, is_post=false)
 
         @next_time = is_post ? nil : false
       end
@@ -527,12 +528,12 @@ module Rufus
           "of #{@frequency.inspect} (#{@original.inspect})"
         ) if @frequency <= 0
 
-        set_next_time(false, nil)
+        set_next_time(nil)
       end
 
       protected
 
-      def set_next_time(is_post, trigger_time)
+      def set_next_time(trigger_time, is_post=false)
 
         return if is_post
 
@@ -567,12 +568,12 @@ module Rufus
           "of #{@interval.inspect} (#{@original.inspect})"
         ) if @interval <= 0
 
-        set_next_time(false, nil)
+        set_next_time(nil)
       end
 
       protected
 
-      def set_next_time(is_post, trigger_time)
+      def set_next_time(trigger_time, is_post=false)
 
         @next_time =
           if is_post
@@ -616,7 +617,7 @@ module Rufus
 
       protected
 
-      def set_next_time(is_post, trigger_time)
+      def set_next_time(trigger_time, is_post=false)
 
         @next_time = @cron_line.next_time
       end

data/lib/rufus/scheduler/locks.rb

@@ -0,0 +1,95 @@
+#--
+# Copyright (c) 2006-2014, 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+require 'fileutils'
+
+
+class Rufus::Scheduler
+
+  #
+  # A lock that can always be acquired
+  #
+  class NullLock
+
+    # Locking is always successful.
+    #
+    def lock; true; end
+
+    def locked?; true; end
+    def unlock; true; end
+  end
+
+  #
+  # The standard flock mecha, with its own class thanks to @ecin
+  #
+  class FileLock
+
+    attr_reader :path
+
+    def initialize(path)
+
+      @path = path.to_s
+    end
+
+    # Locking is successful if this Ruby process can create and lock
+    # its lockfile (at the given path).
+    #
+    def lock
+
+      return true if locked?
+
+      @lockfile = nil
+
+      FileUtils.mkdir_p(::File.dirname(@path))
+
+      file = File.new(@path, File::RDWR | File::CREAT)
+      locked = file.flock(File::LOCK_NB | File::LOCK_EX)
+
+      return false unless locked
+
+      now = Time.now
+
+      file.print("pid: #{$$}, ")
+      file.print("scheduler.object_id: #{self.object_id}, ")
+      file.print("time: #{now}, ")
+      file.print("timestamp: #{now.to_f}")
+      file.flush
+
+      @lockfile = file
+
+      true
+    end
+
+    def unlock
+
+      !! (@lockfile && @lockfile.flock(File::LOCK_UN))
+    end
+
+    def locked?
+
+      !! (@lockfile && @lockfile.flock(File::LOCK_NB | File::LOCK_EX))
+    end
+  end
+end
+

data/lib/rufus/scheduler/util.rb

@@ -46,7 +46,7 @@ module Rufus
       o.is_a?(String) ? parse_duration(o, opts) : o
     end
 
-    TZ_REGEX = /\b((?:[a-zA-Z][a-zA-z0-9\-+]+)(?:\/[a-zA-Z0-9\-+]+)?)\b/
+    TZ_REGEX = /\b((?:[a-zA-Z][a-zA-z0-9\-+]+)(?:\/[a-zA-Z0-9_\-+]+)?)\b/
 
     def self.parse_at(o, opts={})
 

data/spec/basics_spec.rb

@@ -19,17 +19,22 @@ describe 'basics' do
 
     it 'accepts a timezone final argument' do
 
-      pending if jruby? or ruby18?
-
-      expect(
-        tts(Time.new(2014, 1, 1, 1, 0, 0, '+01:00'))
-      ).to eq('2014-01-01 01:00:00 +0100')
-      expect(
-        tts(Time.new(2014, 8, 1, 1, 0, 0, '+01:00'))
-      ).to eq('2014-08-01 01:00:00 +0100')
-      expect(
-        tts(Time.new(2014, 8, 1, 1, 0, 0, '+01:00'))
-      ).to eq('2014-08-01 01:00:00 +0100')
+      if jruby? or ruby18?
+
+        expect(true).to be(true)
+
+      else
+
+        expect(
+          tts(Time.new(2014, 1, 1, 1, 0, 0, '+01:00'))
+        ).to eq('2014-01-01 01:00:00 +0100')
+        expect(
+          tts(Time.new(2014, 8, 1, 1, 0, 0, '+01:00'))
+        ).to eq('2014-08-01 01:00:00 +0100')
+        expect(
+          tts(Time.new(2014, 8, 1, 1, 0, 0, '+01:00'))
+        ).to eq('2014-08-01 01:00:00 +0100')
+      end
     end
   end
 

data/spec/lock_flock_spec.rb

@@ -0,0 +1,47 @@
+
+#
+# Specifying rufus-scheduler
+#
+# Sat Aug 16 05:43:06 JST 2014
+# added by @ecin
+#
+
+require 'spec_helper'
+
+
+describe Rufus::Scheduler::FileLock do
+
+  before :each do
+
+    @lock_path = '.rufus-scheduler.lock'
+    @lock = Rufus::Scheduler::FileLock.new(@lock_path)
+  end
+
+  after :each do
+
+    FileUtils.rm_f(@lock_path)
+    FileUtils.rm_f('lock.txt')
+  end
+
+  context ':scheduler_lock => Rufus::Scheduler::FileLock.new(path)' do
+
+    it 'writes down a .rufus-scheduler.lock file' do
+
+      @lock.lock
+
+      line = File.read(@lock_path)
+
+      expect(line).to match(/pid: #{$$}/)
+    end
+
+    it '"flocks" the lock file' do
+
+      @lock.lock
+
+      f = File.new(@lock_path, 'a')
+
+      expect(f.flock(File::LOCK_NB | File::LOCK_EX)).to eq(false)
+    end
+  end
+end
+

data/spec/lock_spec.rb

@@ -0,0 +1,59 @@
+
+#
+# Specifying rufus-scheduler
+#
+# Sat Aug 16 05:42:11 JST 2014
+# added by @ecin
+#
+
+require 'spec_helper'
+
+
+describe Rufus::Scheduler do
+
+  context "when running multiple schedulers side-by-side" do
+
+    class AlwaysLock
+      def lock; true; end
+      def unlock; true; end
+      def locked?; true; end
+    end
+
+    class NeverLock
+      def lock; false; end
+      def unlock; true; end
+      def locked?; true; end
+    end
+
+    it "only starts if it can acquire a scheduler lock" do
+
+      main = Rufus::Scheduler.new :scheduler_lock => AlwaysLock.new
+      backup = Rufus::Scheduler.new :scheduler_lock => NeverLock.new
+
+      expect(main).to be_up
+      expect(backup).to be_down
+    end
+
+    it "only triggers jobs when it can acquire a trigger lock" do
+
+      main = Rufus::Scheduler.new(:trigger_lock => AlwaysLock.new)
+      backup = Rufus::Scheduler.new(:trigger_lock => NeverLock.new)
+
+      expect(main).to be_up
+      expect(backup).to be_up
+
+      counter = 0
+      job = proc { counter += 1 }
+      main.schedule_in(0, job)
+      backup.schedule_in(0, job)
+
+      sleep 0.5
+
+      expect(main.jobs).to be_empty
+      expect(backup.jobs.count).to eq(1)
+      expect(backup.jobs.first.next_time).to be(false)
+      expect(counter).to eq(1)
+    end
+  end
+end
+

data/spec/parse_spec.rb

@@ -47,6 +47,10 @@ describe Rufus::Scheduler do
       expect(parse('Japan Sun Nov 18 16:01:00 2012').getutc.strftime('%c')).to eq(
         'Sun Nov 18 07:01:00 2012'
       )
+
+      expect(parse('Sun Nov 18 16:01:00 2012 America/New_York').getutc.strftime('%c')).to eq(
+        'Sun Nov 18 21:01:00 2012'
+      )
     end
 
     it 'parses datetimes with named timezones' do

data/spec/scheduler_spec.rb

@@ -540,7 +540,7 @@ describe Rufus::Scheduler do
         sleep 3
       end
 
-      sleep 0.4
+      sleep 0.49
 
       expect(@scheduler.running_jobs(:tag => 't0').map(&:original)).to eq(
         %w[ 0.1s ]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rufus-scheduler
 version: !ruby/object:Gem::Version
-  version: 3.0.8
+  version: 3.0.9
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-08 00:00:00.000000000 Z
+date: 2014-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -85,6 +85,7 @@ files:
 - Rakefile
 - lib/rufus-scheduler.rb
 - lib/rufus/scheduler.rb
+- lib/rufus/scheduler/locks.rb
 - lib/rufus/scheduler/cronline.rb
 - lib/rufus/scheduler/util.rb
 - lib/rufus/scheduler/jobs.rb
@@ -97,20 +98,22 @@ files:
 - spec/job_at_spec.rb
 - spec/schedule_at_spec.rb
 - spec/error_spec.rb
+- spec/lock_spec.rb
 - spec/schedule_cron_spec.rb
 - spec/job_interval_spec.rb
 - spec/job_repeat_spec.rb
-- spec/lockfile_spec.rb
 - spec/schedule_every_spec.rb
 - spec/threads_spec.rb
 - spec/cronline_spec.rb
+- spec/lock_lockfile_spec.rb
 - spec/job_in_spec.rb
 - spec/parse_spec.rb
 - spec/scheduler_spec.rb
-- spec/custom_locks_spec.rb
+- spec/lock_custom_spec.rb
 - spec/basics_spec.rb
 - spec/job_cron_spec.rb
 - spec/job_every_spec.rb
+- spec/lock_flock_spec.rb
 - rufus-scheduler.gemspec
 - CHANGELOG.txt
 - TODO.txt
@@ -120,7 +123,7 @@ files:
 homepage: http://github.com/jmettraux/rufus-scheduler
 licenses:
 - MIT
-post_install_message: ! "\n***\n\nThanks for installing rufus-scheduler 3.0.8\n\nIt
+post_install_message: ! "\n***\n\nThanks for installing rufus-scheduler 3.0.9\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