rufus-scheduler 3.0.0 → 3.0.9

data/lib/rufus/scheduler/util.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013, John Mettraux, jmettraux@gmail.com
+# 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
@@ -31,9 +31,9 @@ module Rufus
     # time and string methods
     #++
 
-    def self.parse(o)
+    def self.parse(o, opts={})
 
-      opts = { :no_error => true }
+      opts[:no_error] = true
 
       parse_cron(o, opts) ||
       parse_in(o, opts) || # covers 'every' schedule strings
@@ -46,12 +46,15 @@ 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={})
 
       return o if o.is_a?(Time)
 
+      # TODO: deal with tz if suffixed to Chronic string?
+      return Chronic.parse(o, opts) if defined?(Chronic)
+
       tz = nil
       s =
         o.to_s.gsub(TZ_REGEX) { |m|
@@ -68,9 +71,7 @@ module Rufus
 
       t = Time.parse(s)
 
-      t = tz.local_to_utc(t) if tz
-
-      t
+      tz ? tz.local_to_utc(t) : t
 
     rescue StandardError => se
 
@@ -133,17 +134,17 @@ module Rufus
     #
     # Some examples:
     #
-    #   Rufus::Scheduler.parse_duration_string "0.5"    # => 0.5
-    #   Rufus::Scheduler.parse_duration_string "500"    # => 0.5
-    #   Rufus::Scheduler.parse_duration_string "1000"   # => 1.0
-    #   Rufus::Scheduler.parse_duration_string "1h"     # => 3600.0
-    #   Rufus::Scheduler.parse_duration_string "1h10s"  # => 3610.0
-    #   Rufus::Scheduler.parse_duration_string "1w2d"   # => 777600.0
+    #   Rufus::Scheduler.parse_duration "0.5"    # => 0.5
+    #   Rufus::Scheduler.parse_duration "500"    # => 0.5
+    #   Rufus::Scheduler.parse_duration "1000"   # => 1.0
+    #   Rufus::Scheduler.parse_duration "1h"     # => 3600.0
+    #   Rufus::Scheduler.parse_duration "1h10s"  # => 3610.0
+    #   Rufus::Scheduler.parse_duration "1w2d"   # => 777600.0
     #
     # Negative time strings are OK (Thanks Danny Fullerton):
     #
-    #   Rufus::Scheduler.parse_duration_string "-0.5"   # => -0.5
-    #   Rufus::Scheduler.parse_duration_string "-1h"    # => -3600.0
+    #   Rufus::Scheduler.parse_duration "-0.5"   # => -0.5
+    #   Rufus::Scheduler.parse_duration "-1h"    # => -3600.0
     #
     def self.parse_duration(string, opts={})
 
@@ -183,13 +184,22 @@ module Rufus
       mod * val
     end
 
+    class << self
+      #-
+      # for compatibility with rufus-scheduler 2.x
+      #+
+      alias parse_duration_string parse_duration
+      alias parse_time_string parse_duration
+    end
+
+
     # Turns a number of seconds into a a time string
     #
-    #   Rufus.to_duration_string 0                    # => '0s'
-    #   Rufus.to_duration_string 60                   # => '1m'
-    #   Rufus.to_duration_string 3661                 # => '1h1m1s'
-    #   Rufus.to_duration_string 7 * 24 * 3600        # => '1w'
-    #   Rufus.to_duration_string 30 * 24 * 3600 + 1   # => "4w2d1s"
+    #   Rufus.to_duration 0                    # => '0s'
+    #   Rufus.to_duration 60                   # => '1m'
+    #   Rufus.to_duration 3661                 # => '1h1m1s'
+    #   Rufus.to_duration 7 * 24 * 3600        # => '1w'
+    #   Rufus.to_duration 30 * 24 * 3600 + 1   # => "4w2d1s"
     #
     # It goes from seconds to the year. Months are not counted (as they
     # are of variable length). Weeks are counted.
@@ -197,16 +207,14 @@ module Rufus
     # For 30 days months to be counted, the second parameter of this
     # method can be set to true.
     #
-    #   Rufus.to_time_string 30 * 24 * 3600 + 1, true   # => "1M1s"
-    #
-    # (to_time_string is an alias for to_duration_string)
+    #   Rufus.to_duration 30 * 24 * 3600 + 1, true   # => "1M1s"
     #
     # If a Float value is passed, milliseconds will be displayed without
     # 'marker'
     #
-    #   Rufus.to_duration_string 0.051                       # => "51"
-    #   Rufus.to_duration_string 7.051                       # => "7s51"
-    #   Rufus.to_duration_string 0.120 + 30 * 24 * 3600 + 1  # => "4w2d1s120"
+    #   Rufus.to_duration 0.051                       # => "51"
+    #   Rufus.to_duration 7.051                       # => "7s51"
+    #   Rufus.to_duration 0.120 + 30 * 24 * 3600 + 1  # => "4w2d1s120"
     #
     # (this behaviour mirrors the one found for parse_time_string()).
     #
@@ -238,7 +246,11 @@ module Rufus
     end
 
     class << self
+      #-
+      # for compatibility with rufus-scheduler 2.x
+      #+
       alias to_duration_string to_duration
+      alias to_time_string to_duration
     end
 
     # Turns a number of seconds (integer or Float) into a hash like in :
@@ -250,8 +262,7 @@ module Rufus
     #   Rufus.to_duration_hash 0.120 + 30 * 24 * 3600 + 1
     #     # => { :w => 4, :d => 2, :s => 1, :ms => "120" }
     #
-    # This method is used by to_duration_string (to_time_string) behind
-    # the scene.
+    # This method is used by to_duration behind the scenes.
     #
     # Options are :
     #

data/lib/rufus/scheduler.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013, John Mettraux, jmettraux@gmail.com
+# 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
@@ -26,7 +26,6 @@ require 'date' if RUBY_VERSION < '1.9.0'
 require 'time'
 require 'thread'
 require 'tzinfo'
-require 'fileutils'
 
 
 module Rufus
@@ -37,16 +36,28 @@ module Rufus
     require 'rufus/scheduler/jobs'
     require 'rufus/scheduler/cronline'
     require 'rufus/scheduler/job_array'
+    require 'rufus/scheduler/locks'
 
-    VERSION = '3.0.0'
+    VERSION = '3.0.9'
+
+    #
+    # A common error class for rufus-scheduler
+    #
+    class Error < StandardError; end
 
     #
     # This error is thrown when the :timeout attribute triggers
     #
-    class TimeoutError < StandardError; end
+    class TimeoutError < Error; end
+
+    #
+    # For when the scheduler is not running
+    # (it got shut down or didn't start because of a lock)
+    #
+    class NotRunningError < Error; end
 
-    #MIN_WORK_THREADS = 7
-    MAX_WORK_THREADS = 35
+    #MIN_WORK_THREADS = 3
+    MAX_WORK_THREADS = 28
 
     attr_accessor :frequency
     attr_reader :started_at
@@ -82,7 +93,17 @@ module Rufus
 
       @thread_key = "rufus_scheduler_#{self.object_id}"
 
-      consider_lockfile || 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
@@ -113,7 +134,9 @@ module Rufus
 
       @started_at = nil
 
-      jobs.each { |j| j.unschedule }
+      #jobs.each { |j| j.unschedule }
+        # provokes https://github.com/jmettraux/rufus-scheduler/issue/98
+      @jobs.array.each { |j| j.unschedule }
 
       @work_queue.clear
 
@@ -123,7 +146,7 @@ module Rufus
         kill_all_work_threads
       end
 
-      @lockfile.flock(File::LOCK_UN) if @lockfile
+      unlock
     end
 
     alias stop shutdown
@@ -140,9 +163,23 @@ module Rufus
 
     def join
 
+      fail NotRunningError.new(
+        'cannot join scheduler that is not running'
+      ) unless @thread
+
       @thread.join
     end
 
+    def down?
+
+      ! @started_at
+    end
+
+    def up?
+
+      !! @started_at
+    end
+
     def paused?
 
       @paused
@@ -214,9 +251,9 @@ module Rufus
 
     def schedule(arg, callable=nil, opts={}, &block)
 
-      # TODO: eventually, spare one parse call
+      opts[:_t] = Scheduler.parse(arg, opts)
 
-      case Scheduler.parse(arg)
+      case opts[:_t]
         when CronLine then schedule_cron(arg, callable, opts, &block)
         when Time then schedule_at(arg, callable, opts, &block)
         else schedule_in(arg, callable, opts, &block)
@@ -225,9 +262,9 @@ module Rufus
 
     def repeat(arg, callable=nil, opts={}, &block)
 
-      # TODO: eventually, spare one parse call
+      opts[:_t] = Scheduler.parse(arg, opts)
 
-      case Scheduler.parse(arg)
+      case opts[:_t]
         when CronLine then schedule_cron(arg, callable, opts, &block)
         else schedule_every(arg, callable, opts, &block)
       end
@@ -297,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
@@ -348,13 +428,39 @@ module Rufus
       jobs(opts.merge(:running => true))
     end
 
+    def occurrences(time0, time1, format=:per_job)
+
+      h = {}
+
+      jobs.each do |j|
+        os = j.occurrences(time0, time1)
+        h[j] = os if os.any?
+      end
+
+      if format == :timeline
+        a = []
+        h.each { |j, ts| ts.each { |t| a << [ t, j ] } }
+        a.sort_by { |(t, j)| t }
+      else
+        h
+      end
+    end
+
+    def timeline(time0, time1)
+
+      occurrences(time0, time1, :timeline)
+    end
+
     def on_error(job, err)
 
       pre = err.object_id.to_s
 
+      ms = {}; mutexes.each { |k, v| ms[k] = v.locked? }
+
       stderr.puts("{ #{pre} rufus-scheduler intercepted an error:")
       stderr.puts("  #{pre}   job:")
       stderr.puts("  #{pre}     #{job.class} #{job.original.inspect} #{job.opts.inspect}")
+      # TODO: eventually use a Job#detail or something like that
       stderr.puts("  #{pre}   error:")
       stderr.puts("  #{pre}     #{err.object_id}")
       stderr.puts("  #{pre}     #{err.class}")
@@ -362,6 +468,34 @@ module Rufus
       err.backtrace.each do |l|
         stderr.puts("  #{pre}       #{l}")
       end
+      stderr.puts("  #{pre}   tz:")
+      stderr.puts("  #{pre}     ENV['TZ']: #{ENV['TZ']}")
+      stderr.puts("  #{pre}     Time.now: #{Time.now}")
+      stderr.puts("  #{pre}   scheduler:")
+      stderr.puts("  #{pre}     object_id: #{object_id}")
+      stderr.puts("  #{pre}     opts:")
+      stderr.puts("  #{pre}       #{@opts.inspect}")
+      stderr.puts("  #{pre}       frequency: #{self.frequency}")
+      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}")
+      stderr.puts("  #{pre}       thread: #{self.thread}")
+      stderr.puts("  #{pre}       thread_key: #{self.thread_key}")
+      stderr.puts("  #{pre}       work_threads: #{work_threads.size}")
+      stderr.puts("  #{pre}         active: #{work_threads(:active).size}")
+      stderr.puts("  #{pre}         vacant: #{work_threads(:vacant).size}")
+      stderr.puts("  #{pre}         max_work_threads: #{max_work_threads}")
+      stderr.puts("  #{pre}       mutexes: #{ms.inspect}")
+      stderr.puts("  #{pre}     jobs: #{jobs.size}")
+      stderr.puts("  #{pre}       at_jobs: #{at_jobs.size}")
+      stderr.puts("  #{pre}       in_jobs: #{in_jobs.size}")
+      stderr.puts("  #{pre}       every_jobs: #{every_jobs.size}")
+      stderr.puts("  #{pre}       interval_jobs: #{interval_jobs.size}")
+      stderr.puts("  #{pre}       cron_jobs: #{cron_jobs.size}")
+      stderr.puts("  #{pre}     running_jobs: #{running_jobs.size}")
+      stderr.puts("  #{pre}     work_queue: #{work_queue.size}")
       stderr.puts("} #{pre} .")
 
     rescue => e
@@ -388,36 +522,6 @@ module Rufus
       end
     end
 
-    def consider_lockfile
-
-      @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
-
     def terminate_all_jobs
 
       jobs.each { |j| j.unschedule }
@@ -502,7 +606,7 @@ module Rufus
 
     def do_schedule(job_type, t, callable, opts, return_job_instance, block)
 
-      raise RuntimeError.new(
+      fail NotRunningError.new(
         'cannot schedule, scheduler is down or shutting down'
       ) if @started_at == nil
 
@@ -512,8 +616,8 @@ module Rufus
       job_class =
         case job_type
           when :once
-            tt = Rufus::Scheduler.parse(t)
-            tt.is_a?(Time) ? AtJob : InJob
+            opts[:_t] ||= Rufus::Scheduler.parse(t, opts)
+            opts[:_t].is_a?(Time) ? AtJob : InJob
           when :every
             EveryJob
           when :interval

data/rufus-scheduler.gemspec

@@ -30,6 +30,7 @@ job scheduler for Ruby (at, cron, in and every jobs).
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec', '>= 2.13.0'
+  s.add_development_dependency 'chronic'
 
   s.require_path = 'lib'
 
@@ -49,7 +50,7 @@ A) Forget it and peg your Gemfile to rufus-scheduler 2.0.24
 and / or
 
 B) Take some time to carefully report the issue at
-   https://github.com/jmettraux/rufus-scheduler/issue
+   https://github.com/jmettraux/rufus-scheduler/issues
 
 For general help about rufus-scheduler, ask via:
 http://stackoverflow.com/questions/ask?tags=rufus-scheduler+ruby

data/spec/basics_spec.rb

@@ -0,0 +1,54 @@
+
+#
+# Specifying rufus-scheduler
+#
+# Sun Jun  1 05:52:24 JST 2014
+#
+
+require 'spec_helper'
+
+
+describe 'basics' do
+
+  def tts(time)
+
+    time.strftime('%Y-%m-%d %H:%M:%S %z') + (time.dst? ? ' dst' : '')
+  end
+
+  describe 'Time.new' do
+
+    it 'accepts a timezone final argument' do
+
+      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
+
+  describe 'Time.local' do
+
+    it 'works as expected' do
+
+      expect(
+        tts(in_zone('Europe/Berlin') { Time.local(2014, 1, 1, 1, 0, 0) })
+      ).to eq('2014-01-01 01:00:00 +0100')
+      expect(
+        tts(in_zone('Europe/Berlin') { Time.local(2014, 8, 1, 1, 0, 0) })
+      ).to eq('2014-08-01 01:00:00 +0200 dst')
+    end
+  end
+end
+