rufus-scheduler 2.0.24 → 3.1.0

data/Rakefile

@@ -1,12 +1,8 @@
 
-$:.unshift('.') # 1.9.2
-
 require 'rubygems'
-require 'rubygems/user_interaction' if Gem::RubyGemsVersion == '1.5.0'
 
 require 'rake'
 require 'rake/clean'
-#require 'rake/rdoctask'
 require 'rdoc/task'
 
 
@@ -42,7 +38,7 @@ desc %{
 task :build do
 
   sh "gem build #{GEMSPEC_FILE}"
-  sh "mkdir pkg" rescue nil
+  sh "mkdir -p pkg"
   sh "mv #{GEMSPEC.name}-#{GEMSPEC.version}.gem pkg/"
 end
 

data/TODO.txt

@@ -1,57 +1,151 @@
 
-[o] spec for jobs in the past (in and at)
-[o] :discard_past
-
-[o] every
-[o] cron
-
-[o] CHECK every and unschedule !!!
-
-[o] :tags
-[o] timeout feature (at/in/every/cron) in Job class
-
-[o] :first_in, :first_at
-
-[x] :dont_reschedule (or block returns false ?)
-
-[o] [get_]jobs methods
-[o] find methods
-
-[x] CTRL-C during tests : allow, trap_int...
-
-[o] 1.9
-[o] j1.2.0
-
-[o] revise trigger block arity
-    use a compatibility switch ? yes
-
-[o] synchronize @cron_jobs ?
-
-[o] why not : make it work even if EM is not present
-    EmScheduler < Scheduler
-    FiberScheduler < Scheduler
-
-[x] :blocking => 'blockname' idea, mutex = @mutexes['blockname'] ...
-[o] eventually, make sleep frequency customizable
-
-[o] PlainScheduler : name thread
-
-[o] document :blocking
-
-[o] README.rdoc
-[o] fix jruby120 --em
-
-[o] handle_exception (job, e)
-
-[o] Schedulable
-
-[o] Rufus::Scheduler.start_new() : autodetect EM ?
-[o] check :blocking and every (reschedule blocking...)
-[o] document :thread_name scheduler option
-
-[o] unify cron_jobs#trigger_matching_jobs(now) and jobs#job_to_trigger
-[o] pluggable job queues
-
-[ ] Joel's complaint about timeout jobs gone ballistic
-[x] move trigger_job out of the scheduler
+[o] merge schedule_queue and unschedule_queue (and merge [un]schedule steps)
+[x] OR stop using queue, since we've got the thread-safe JobArray
+[x] if possible, drop the mutex in JobArray
+    NO, that mutex is necessary for Scheduler#jobs (on JRuby an co)...
+[o] named mutexes
+[o] drop the schedule queue, rely on the mutex in JobArray
+[o] def jobs; (@jobs.to_a + running_jobs).uniq; end
+[o] replace @unscheduled by @unscheduled_at
+[o] make sure #jobs doesn't return unscheduled jobs
+[o] job tags and find_by_tag(t) (as in rs 2.x)
+[o] require tzinfo anyway (runtime dep)
+[o] document frequency
+[o] accept :frequency => '5s'
+[o] timeout (as in rufus-scheduler 2.x)
+[o] Rufus::Scheduler#running_jobs (as in rufus-scheduler 2.x)
+[o] Rufus::Scheduler#terminate_all_jobs
+[o] Rufus::Scheduler::Job#kill
+[x] Rufus::Scheduler#kill_all_jobs
+[o] Rufus::Scheduler#shutdown(:terminate or :kill (or nothing))
+[o] RepeatJob #pause / #resume (think about discard past)
+[o] Rufus::Scheduler.start_new (backward comp) (with deprec note?)
+[o] pass job to scheduled block? What does rs 2.x do?
+[o] :first[_in|_at] for RepeatJob
+[o] :last[_in|_at] for RepeatJob
+[o] :times for RepeatJob (how many recurrences)
+[o] fix issue #39 (first_at parses as UTC)
+[o] about issue #43, raise if cron/every job frequency < scheduler frequency
+[o] unlock spec/parse_spec.rb:30 "parse datimes with timezones"
+[o] some kind of Schedulable (Xyz#call(job, time))
+[o] add Jruby and Rubinius to Travis
+[o] make Job #first_at= / #last_at= automatically parse strings?
+[o] bring in Kratob's spec about mutex vs timeout and adapt 3.0 to it,
+    https://github.com/jmettraux/rufus-scheduler/pull/67
+[x] :unschedule_if => lambda { |job| ... }
+[o] OR look at how it was done in rs 2.0.x, some return value?
+    no, pass the job as arg to the block, then let the block do job.unschedule
+    so, document schedule.every('10d') { |j| j.unschedule if x?() }
+[x] remove the time in job.trigger(time)
+[o] add spec for job queued then unscheduled
+[o] add spec for Scheduler#shutdown and work threads
+[o] at some point, bring back rbx19 to Travis
+[o] move the parse/util part of scheduler.rb to util.rb
+[o] rescue KillSignal in job thread loop to kill just the job
+[o] add spec for raise if scheduling a job while scheduler is shutting down
+[o] schedule_in(2.days.from_now) {}
+    at and in could understand each others time parameter, ftw...
+    use the new #parse_to_time? no
+[o] do repeat jobs reschedule after timing out? yes
+[o] schedule_interval('20s')?
+[x] Scheduler#reschedule(job) (new copy of the job)
+[x] #free_all_work_threads is missing an implementation
+[x] rescue StandardError
+    :on_error => :crash[_scheduler]
+    :on_error => :ignore
+    :on_error => ...
+[o] on_error: what about TimeoutError in that scheme?
+    TimeoutError goes to $stderr, like a normal error
+[o] link to SO for support
+    - sublink to "how to report bugs effectively"
+[o] link to #ruote for support
+[x] lockblock? pass a block to teach the scheduler how to lock?
+    is not necessary, @scheduler = Scheduler.new if should_start?
+    the surrounding Ruby code checks
+[o] introduce job "vars", as in
+    http://stackoverflow.com/questions/18202848/how-to-have-a-variable-that-will-available-to-particular-scheduled-task-whenever
+    or job['key'] Job #[] and #[]=, as with Thread #[] #[]=
+    job-local variables #keys #key?
+[o] thread-safety for job-local variables?
+[x] discard past? discard_past => true or => "1d"
+    default would be discard_past => "1m" or scheduler freq * 2 ?
+    jobs would adjust their next_time until it fits the window...
+    ~~ discard past by default
+[o] expanded block/schedulable (it's "callable")
+    ```
+      scheduler.every '10m' do
+        def pre
+          return false if Backend.down?
+          # ...
+        end
+        def post
+          # ...
+        end
+        def trigger
+          puts "oh hai!"
+        end
+      end
+    ```
+    or something like that...
+    ...
+    OR accept a class (and instantiate it the first time)
+    ```
+      scheduler.every '10m', Class.new do
+        def call(job, time)
+          # ...
+        end
+      end
+    ```
+    the job contains the instance in its @callable
+[x] add spec case for corner case in Job#trigger (overlap vs reschedule) !!!
+[o] rethink job array vs job set for #scheduled?
+[x] introduce common parent class for EveryJob and IntervalJob
+[o] create spec/ at_job_spec.rb, repeat_job_spec.rb, cron_job_spec.rb, ...
+[x] ensure EveryJob do not schedule in the past (it's already like that)
+[o] CronLine#next_time should return a time with subseconds chopped off
+[o] drop min work threads setting?
+[o] thread pool something? Thread upper limit?
+[o] Rufus::Scheduler.singleton, Rufus::Scheduler.s
+[o] EveryJob#first_at= and IntervalJob#first_at= should alter @next_time
+[o] scheduler.schedule duration/time/cron ... for at/in/cron
+    (not every, nor interval)
+    scheduler.repeat time/cron ... for every/cron
+
+[o] :lockfile => x, timestamp, process_id, thread_id...
+    warning: have to clean up that file on exit... or does the scheduler
+    timestamps it?
+[ ] develop lockfile timestamp thinggy
+    ~ if the timestamp is too old (twice the default frequency?) then
+    lock [file] take over...
+    Is that really what we want all the time?
+
+[ ] idea: :mutex => x and :skip_on_mutex => true ?
+    would prevent blocking/waiting for the mutex to get available
+    :mutex => [ "mutex_name", true ]
+    :mutex => [ [ "mutex_name", true ], [ "other_mutex_name", false ] ]
+
+[ ] bring back EM (but only EM.defer ?) :defer => true (Job or Scheduler
+    or both option?)
+
+[ ] prepare a daemon, trust daemon-kit for that
+
+[ ] :if => lambda { |job, time| ... } why not?
+    :unless => lambda { ...
+    :block => lambda { ...
+    can help get the block themselves leaner
+    #
+    investigate guards for schedulables... def if_guard; ...; end
+
+[ ] scheduler.every '10', Class.new do
+      def call(job, time)
+        # might fail...
+      end
+      def on_error(err, job)
+        # catches...
+      end
+    end
+
+~~~
+
+[ ] scheduler.at('chronic string', chronic_options...)
 

data/lib/rufus/{sc → scheduler}/cronline.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2006-2015, 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
@@ -22,10 +22,10 @@
 # Made in Japan.
 #++
 
-require 'tzinfo'
+require 'set'
 
 
-module Rufus
+class Rufus::Scheduler
 
   #
   # A 'cron line' is a line in the sense of a crontab
@@ -33,9 +33,6 @@ module Rufus
   #
   class CronLine
 
-    DAY_S = 24 * 3600
-    WEEK_S = 7 * DAY_S
-
     # The string used for creating this cronline instance.
     #
     attr_reader :original
@@ -51,14 +48,15 @@ module Rufus
 
     def initialize(line)
 
-      super()
+      raise ArgumentError.new(
+        "not a string: #{line.inspect}"
+      ) unless line.is_a?(String)
 
       @original = line
 
       items = line.split
 
-      @timezone = (TZInfo::Timezone.get(items.last) rescue nil)
-      items.pop if @timezone
+      @timezone = items.pop if ZoTime.is_timezone?(items.last)
 
       raise ArgumentError.new(
         "not a valid cronline : '#{line}'"
@@ -85,9 +83,7 @@ module Rufus
     #
     def matches?(time)
 
-      time = Time.at(time) unless time.kind_of?(Time)
-
-      time = @timezone.utc_to_local(time.getutc) if @timezone
+      time = ZoTime.new(time.to_f, @timezone || ENV['TZ']).time
 
       return false unless sub_match?(time, :sec, @seconds)
       return false unless sub_match?(time, :min, @minutes)
@@ -109,74 +105,99 @@ module Rufus
     # be passed if no start time is specified (search start time set to
     # Time.now))
     #
-    #   Rufus::CronLine.new('30 7 * * *').next_time(
+    #   Rufus::Scheduler::CronLine.new('30 7 * * *').next_time(
     #     Time.mktime(2008, 10, 24, 7, 29))
     #   #=> Fri Oct 24 07:30:00 -0500 2008
     #
-    #   Rufus::CronLine.new('30 7 * * *').next_time(
+    #   Rufus::Scheduler::CronLine.new('30 7 * * *').next_time(
     #     Time.utc(2008, 10, 24, 7, 29))
     #   #=> Fri Oct 24 07:30:00 UTC 2008
     #
-    #   Rufus::CronLine.new('30 7 * * *').next_time(
+    #   Rufus::Scheduler::CronLine.new('30 7 * * *').next_time(
     #     Time.utc(2008, 10, 24, 7, 29)).localtime
     #   #=> Fri Oct 24 02:30:00 -0500 2008
     #
     # (Thanks to K Liu for the note and the examples)
     #
-    def next_time(now=Time.now)
+    def next_time(from=Time.now)
 
-      time = @timezone ? @timezone.utc_to_local(now.getutc) : now
-
-      time = time - time.usec * 1e-6 + 1
-        # small adjustment before starting
+      time = nil
+      zotime = ZoTime.new(from.to_i + 1, @timezone || ENV['TZ'])
 
       loop do
 
+        time = zotime.time
+
         unless date_match?(time)
-          time += (24 - time.hour) * 3600 - time.min * 60 - time.sec; next
+          zotime.add((24 - time.hour) * 3600 - time.min * 60 - time.sec)
+          next
         end
         unless sub_match?(time, :hour, @hours)
-          time += (60 - time.min) * 60 - time.sec; next
+          zotime.add((60 - time.min) * 60 - time.sec)
+          next
         end
         unless sub_match?(time, :min, @minutes)
-          time += 60 - time.sec; next
+          zotime.add(60 - time.sec)
+          next
         end
         unless sub_match?(time, :sec, @seconds)
-          time += 1; next
+          zotime.add(next_second(time))
+          next
         end
 
         break
       end
 
-      if @timezone
-        time = @timezone.local_to_utc(time)
-        time = time.getlocal unless now.utc?
-      end
-
       time
     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(now=Time.now)
+    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)
-
-      start = current = now - 2 * 3600
-      result = nil
+      time = nil
+      zotime = ZoTime.new(from.to_i - 1, @timezone || ENV['TZ'])
 
       loop do
-        nex = next_time(current)
-        return (result ? result : previous_time(start)) if nex > now
-        result = current = nex
+
+        time = zotime.time
+
+        unless date_match?(time)
+          zotime.substract(time.hour * 3600 + time.min * 60 + time.sec + 1)
+          next
+        end
+        unless sub_match?(time, :hour, @hours)
+          zotime.substract(time.min * 60 + time.sec + 1)
+          next
+        end
+        unless sub_match?(time, :min, @minutes)
+          zotime.substract(time.sec + 1)
+          next
+        end
+        unless sub_match?(time, :sec, @seconds)
+          zotime.substract(prev_second(time))
+          next
+        end
+
+        break
       end
 
-      # never reached
+      time
+    end
+
+    if RUBY_VERSION >= '1.9'
+      def toa(item)
+        item == nil ? nil : item.to_a
+      end
+    else
+      def toi(item); item.is_a?(String) ? item.hash.abs : item.to_i; end
+      protected :toi
+      def toa(item)
+        item.is_a?(Set) ? item.to_a.sort_by { |e| toi(e) } : item
+      end
     end
+    protected :toa
 
     # Returns an array of 6 arrays (seconds, minutes, hours, days,
     # months, weekdays).
@@ -185,20 +206,113 @@ module Rufus
     def to_array
 
       [
-        @seconds,
-        @minutes,
-        @hours,
-        @days,
-        @months,
-        @weekdays,
-        @monthdays,
-        @timezone ? @timezone.name : nil
+        toa(@seconds),
+        toa(@minutes),
+        toa(@hours),
+        toa(@days),
+        toa(@months),
+        toa(@weekdays),
+        toa(@monthdays),
+        @timezone
       ]
     end
 
-    private
+    # Returns a quickly computed approximation of the frequency for this
+    # cron line.
+    #
+    # #brute_frequency, on the other hand, will compute the frequency by
+    # examining a whole year, that can take more than seconds for a seconds
+    # level cron...
+    #
+    def frequency
+
+      return brute_frequency unless @seconds && @seconds.length > 1
+
+      delta = 60
+      secs = toa(@seconds)
+      prev = secs[0]
+
+      secs[1..-1].each do |sec|
+        d = sec - prev
+        delta = d if d < delta
+      end
+
+      delta
+    end
+
+    # 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 brute_frequency
+
+      delta = 366 * DAY_S
+
+      t0 = previous_time(Time.local(2000, 1, 1))
+
+      loop do
+
+        break if delta <= 1
+        break if delta <= 60 && @seconds && @seconds.size == 1
+
+        t1 = next_time(t0)
+        d = t1 - t0
+        delta = d if d < delta
+
+        break if @months == nil && t1.month == 2
+        break if t1.year >= 2001
+
+        t0 = t1
+      end
+
+      delta
+    end
+
+    protected
+
+    def next_second(time)
+
+      secs = @seconds.sort
+
+      return secs.last + 60 - time.sec if time.sec > secs.last
+
+      secs.shift while secs.first < time.sec
+
+      secs.first - time.sec
+    end
+
+    def prev_second(time)
+
+      secs = @seconds.sort
+
+      secs.pop while time.sec < secs.last
+
+      time.sec - secs.last
+    end
 
     WEEKDAYS = %w[ sun mon tue wed thu fri sat ]
+    DAY_S = 24 * 3600
+    WEEK_S = 7 * DAY_S
 
     def parse_weekdays(item)
 
@@ -252,7 +366,7 @@ module Rufus
         "found duplicates in #{item.inspect}"
       ) if r.uniq.size < r.size
 
-      r
+      Set.new(r)
     end
 
     RANGE_REGEX = /^(\*|\d{1,2})(?:-(\d{1,2}))?(?:\/(\d{1,2}))?$/
@@ -281,7 +395,7 @@ module Rufus
 
       raise ArgumentError.new(
         "#{item.inspect} is not in range #{min}..#{max}"
-      ) if sta < min or edn > max
+      ) if sta < min || edn > max
 
       r = []
       val = sta

data/lib/rufus/scheduler/job_array.rb

@@ -0,0 +1,92 @@
+#--
+# Copyright (c) 2006-2015, 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.
+#++
+
+
+module Rufus
+
+  class Scheduler
+
+    #
+    # The array rufus-scheduler uses to keep jobs in order (next to trigger
+    # first).
+    #
+    class JobArray
+
+      def initialize
+
+        @mutex = Mutex.new
+        @array = []
+      end
+
+      def push(job)
+
+        @mutex.synchronize { @array << job unless @array.index(job) }
+
+        self
+      end
+
+      def size
+
+        @array.size
+      end
+
+      def each(now, &block)
+
+        to_a.sort_by { |j| j.next_time || (now + 1) }.each do |job|
+
+          break unless job.next_time
+          break if job.next_time > now
+
+          block.call(job)
+        end
+      end
+
+      def delete_unscheduled
+
+        @mutex.synchronize {
+
+          @array.delete_if { |j| j.next_time.nil? || j.unscheduled_at }
+        }
+      end
+
+      def to_a
+
+        @mutex.synchronize { @array.dup }
+      end
+
+      def [](job_id)
+
+        @mutex.synchronize { @array.find { |j| j.job_id == job_id } }
+      end
+
+      # Only used when shutting down, directly yields the underlying array.
+      #
+      def array
+
+        @array
+      end
+    end
+  end
+end
+