rufus-scheduler 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 02a3bef52f292ce97e4918c53add3f0f6ba7a10c
-  data.tar.gz: '059fec2bf86103a66eb30be091fcd96f4b21abaf'
+SHA256:
+  metadata.gz: c0572c41e8ad285c2de6828cc86ef489122cea65c412514566c08c35713a0523
+  data.tar.gz: 327a0c5e462acc3df68d6c55366a956c9e16b4b4adf208b103568cce4f943dd6
 SHA512:
-  metadata.gz: 8282e8998f735291b30a5dfd8fc0b03ce5b2a5f19a38d747b197ae46b2b8324076af6583eb3c29a49273a066899871d2edd61f1628d6b9df583144a969095afd
-  data.tar.gz: 0d272804d8de32ba93f96b25e9d7be1a6493166c33865a9bfe6ca38ea848db43a89266818d9c0fec3cc37e4a8e83623f88c56566bdb59f2afd85f6c484b0dea6
+  metadata.gz: e3153aa15933ee24cf3a11657fb0b8bd3d58d87e054b20d9d759b52cdd924a418fcf95ef1e14b980b459a501ccce91b285cd85c826e0fa4207fac85f69c77667
+  data.tar.gz: e7af296c9864ffc392ef44eec1bb6ed0331065658b9d9d1225cd2c1f62d1d67302db7075540b0c39a99dcf5f741471f3c38666cb8870165cca23a34f52f1c7df

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 # CHANGELOG.md
 
 
+### rufus-scheduler 3.7.0 - released 2020-12-31
+
+* Implement Job name:/n: #name and #name=, gh-309
+* Add Job #has_key?, #value, and #entries
+* Add #locals access to Job
+* Implement Scheduler#around_trigger, @jjb, gh-310
+* Accept max_worker_threads: for max_work_threads:
+* Clean up Scheduler#shutdwon, thanks @itsaphel and @jjb, gh-304, gh-315
+
+* f59df40 Bring in discard_past: for every jobs, gh-290
+* 7613277 Introduce :discard_past = false for cron, gh-305
+
+
 ### rufus-scheduler 3.6.0 - released 2019-04-22
 
 * Let Scheduler#cron fail if the cron string is invalid, gh-289

data/CREDITS.md

@@ -4,6 +4,9 @@
 
 ## Contributors
 
+* John Bachir https://github.com/jjb gh-310
+* Daniel Berger https://github.com/djberg96 gh-300
+* Ceyhun Onur https://github.com/ceyonur parse_cron no_error: true
 * Darwin Wu https://github.com/dwaxe Rails initializer vs tests change
 * Mike Karolow https://github.com/mike-yesware update Travis target Rubies
 * Jack-Nie https://github.com/jack-nie gh-285 fix broken comment link
@@ -64,6 +67,8 @@
 
 ## Feedback
 
+* aphel (https://github.com/itsaphel) #shutdown vs current thread, gh-304
+* aesyondu (https://github.com/aesyondu) Rails console 4.2.x, gh-186
 * Sasha Hoellger (https://github.com/mitnal) parse_cron and readme, gh-270
 * Gian (https://github.com/snmgian) cron vs :first clarification, gh-266
 * Vito Laurenza (https://github.com/veetow) help debugging tz issues, gh-240

data/LICENSE.txt

@@ -1,5 +1,5 @@
 
-Copyright (c) 2005-2019, John Mettraux, jmettraux@gmail.com
+Copyright (c) 2005-2020, 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/Makefile

@@ -23,5 +23,5 @@ build: gemspec_validate
 	mv $(NAME)-$(VERSION).gem pkg/
 
 push: build
-	gem push pkg/$(NAME)-$(VERSION).gem
+	gem push --otp "$(OTP)" pkg/$(NAME)-$(VERSION).gem
 

data/README.md

@@ -24,7 +24,11 @@ scheduler.in '3s' do
 end
 
 scheduler.join
+  #
   # let the current thread join the scheduler thread
+  #
+  # (please note that this join should be removed when scheduling
+  # in a web application (Rails and friends) initializer)
 ```
 (run with `ruby quickstart.rb`)
 
@@ -73,6 +77,7 @@ A rufus-scheduler instance will go on scheduling while it is present among the o
 ## related and similar gems
 
 * [Whenever](https://github.com/javan/whenever) - let cron call back your Ruby code, trusted and reliable cron drives your schedule
+* [ruby-clock](https://github.com/jjb/ruby-clock) - a clock process / job scheduler for Ruby
 * [Clockwork](https://github.com/Rykian/clockwork) - rufus-scheduler inspired gem
 * [Crono](https://github.com/plashchynski/crono) - an in-Rails cron scheduler
 * [PerfectSched](https://github.com/treasure-data/perfectsched) - highly available distributed cron built on [Sequel](https://sequel.jeremyevans.net) and more
@@ -100,8 +105,8 @@ I'll drive you right to the [tracks](#so-rails).
 * The error_handler is [#on_error](#rufusscheduleron_errorjob-error) (instead of #on_exception), by default it now prints the details of the error to $stderr (used to be $stdout)
 * Rufus::Scheduler::TimeOutError renamed to Rufus::Scheduler::TimeoutError
 * Introduction of "interval" jobs. Whereas "every" jobs are like "every 10 minutes, do this", interval jobs are like "do that, then wait for 10 minutes, then do that again, and so on"
-* Introduction of a :lockfile => true/filename mechanism to prevent multiple schedulers from executing
-* "discard_past" is on by default. If the scheduler (its host) sleeps for 1 hour and a ```every '10m'``` job is on, it will trigger once at wakeup, not 6 times (discard_past was false by default in rufus-scheduler 2.x). No intention to re-introduce ```:discard_past => false``` in 3.0 for now.
+* Introduction of a lockfile: true/filename mechanism to prevent multiple schedulers from executing
+* "discard_past" is on by default. If the scheduler (its host) sleeps for 1 hour and a `every '10m'` job is on, it will trigger once at wakeup, not 6 times (discard_past was false by default in rufus-scheduler 2.x). No intention to re-introduce `discard_past: false` in 3.0 for now.
 * Introduction of Scheduler #on_pre_trigger and #on_post_trigger callback points
 
 
@@ -373,6 +378,23 @@ While paused, the scheduler still accepts schedules, but no schedule will get tr
 
 ## job options
 
+### :name => string
+
+Sets the name of the job.
+
+```ruby
+scheduler.cron '*/15 8 * * *', name: 'Robert' do |job|
+  puts "A, it's #{Time.now} and my name is #{job.name}"
+end
+
+job1 =
+  scheduler.schedule_cron '*/30 9 * * *', n: 'temporary' do |job|
+    puts "B, it's #{Time.now} and my name is #{job.name}"
+  end
+# ...
+job1.name = 'Beowulf'
+```
+
 ### :blocking => true
 
 By default, jobs are triggered in their own, new threads. When `:blocking => true`, the job is triggered in the scheduler thread (a new thread is not created). Yes, while a blocking job is running, the scheduler is not scheduling.
@@ -460,7 +482,6 @@ s.every '3s', :first => :now do
 end
 
 s.join
-
 ```
 
 that'll output something like:
@@ -757,9 +778,9 @@ job.tags
   # => [ 'hello' ]
 ```
 
-### []=, [], key? and keys
+### []=, [], key?, has_key?, keys, values, and entries
 
-Threads have thread-local variables. Rufus-scheduler jobs have job-local variables.
+Threads have thread-local variables, similarly Rufus-scheduler jobs have job-local variables. Those are more like a dict with thread-safe access.
 
 ```ruby
 job =
@@ -774,13 +795,29 @@ sleep 3.6
 job[:counter]
   # => 3
 
-job.key?(:timestamp)
-  # => true
-job.keys
-  # => [ :timestamp, :counter ]
+job.key?(:timestamp) # => true
+job.has_key?(:timestamp) # => true
+job.keys # => [ :timestamp, :counter ]
+```
+
+Locals can be set at schedule time:
+```ruby
+job0 =
+  @scheduler.schedule_cron '*/15 12 * * *', locals: { a: 0 } do
+    # ...
+  end
+job1 =
+  @scheduler.schedule_cron '*/15 13 * * *', l: { a: 1 } do
+    # ...
+  end
 ```
 
-Job-local variables are thread-safe.
+One can fetch the Hash directly with `Job#locals`. Of course, direct manipulation is not thread-safe.
+```ruby
+job.locals.entries do |k, v|
+  p "#{k}: #{v}"
+end
+```
 
 ### call
 
@@ -963,6 +1000,10 @@ Shuts down the scheduler, ceases any scheduler/triggering activity.
 
 Shuts down the scheduler, waits (blocks) until all the jobs cease running.
 
+### Scheduler#shutdown(wait: n)
+
+Shuts down the scheduler, waits (blocks) at most n seconds until all the jobs cease running. (Jobs are killed after n seconds have elapsed).
+
 ### Scheduler#shutdown(:kill)
 
 Kills all the job (threads) and then shuts the scheduler down. Radical.
@@ -985,6 +1026,8 @@ Returns since the count of seconds for which the scheduler has been running.
 
 Lets the current thread join the scheduling thread in rufus-scheduler. The thread comes back when the scheduler gets shut down.
 
+`#join` is mostly used in standalone scheduling script (or tiny one file examples). Calling `#join` from a web application initializer will probably hijack the main thread and prevent the web application from being served. Do not put a `#join` in such a web application initializer file.
+
 ### Scheduler#threads
 
 Returns all the threads associated with the scheduler, including the scheduler thread itself.
@@ -1097,7 +1140,9 @@ def scheduler.on_error(job, error)
 end
 ```
 
-## Rufus::Scheduler #on_pre_trigger and #on_post_trigger callbacks
+## Callbacks
+
+### Rufus::Scheduler #on_pre_trigger and #on_post_trigger callbacks
 
 One can bind callbacks before and after jobs trigger:
 
@@ -1121,6 +1166,21 @@ The ```trigger_time``` is the time at which the job triggers. It might be a bit
 
 Warning: these two callbacks are executed in the scheduler thread, not in the work threads (the threads where the job execution really happens).
 
+### Rufus::Scheduler#around_trigger
+
+One can create an around callback which will wrap a job:
+
+```ruby
+def s.around_trigger(job)
+  t = Time.now
+  puts "Starting job #{job.id}..."
+  yield
+  puts "job #{job.id} finished in #{Time.now-t} seconds."
+end
+```
+
+The around callback is executed in the thread.
+
 ### Rufus::Scheduler#on_pre_trigger as a guard
 
 Returning ```false``` in on_pre_trigger will prevent the job from triggering. Returning anything else (nil, -1, true, ...) will let the job trigger.
@@ -1574,6 +1634,8 @@ require 'rufus-scheduler'
 s = Rufus::Scheduler.singleton
 
 return if defined?(Rails::Console) || Rails.env.test? || File.split($0).last == 'rake'
+# return if $PROGRAM_NAME.include?('spring')
+  # see https://github.com/jmettraux/rufus-scheduler/issues/186
 
 # do not schedule when Rails is run from its console, for a test/spec, or
 # from a Rake task

data/lib/rufus/scheduler.rb

@@ -1,629 +1,722 @@
 
-require 'set'
 require 'date' if RUBY_VERSION < '1.9.0'
-require 'time'
 require 'thread'
 
 require 'fugit'
 
 
-module Rufus
+module Rufus; end
 
-  class Scheduler
+class Rufus::Scheduler
 
-    VERSION = '3.6.0'
+  VERSION = '3.7.0'
 
-    EoTime = ::EtOrbi::EoTime
+  EoTime = ::EtOrbi::EoTime
 
-    require 'rufus/scheduler/util'
-    require 'rufus/scheduler/jobs'
-    require 'rufus/scheduler/job_array'
-    require 'rufus/scheduler/locks'
+  require 'rufus/scheduler/util'
+  require 'rufus/scheduler/jobs_core'
+  require 'rufus/scheduler/jobs_one_time'
+  require 'rufus/scheduler/jobs_repeat'
+  require 'rufus/scheduler/job_array'
+  require 'rufus/scheduler/locks'
 
-    #
-    # A common error class for rufus-scheduler
-    #
-    class Error < StandardError; end
+  #
+  # A common error class for rufus-scheduler
+  #
+  class Error < StandardError; end
 
-    #
-    # This error is thrown when the :timeout attribute triggers
-    #
-    class TimeoutError < Error; end
+  #
+  # This error is thrown when the :timeout attribute triggers
+  #
+  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
+  #
+  # 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 = 3
-    MAX_WORK_THREADS = 28
+  #MIN_WORK_THREADS = 3
+  MAX_WORK_THREADS = 28
 
-    attr_accessor :frequency
-    attr_reader :started_at
-    attr_reader :thread
-    attr_reader :thread_key
-    attr_reader :mutexes
+  attr_accessor :frequency
+  attr_accessor :discard_past
 
-    #attr_accessor :min_work_threads
-    attr_accessor :max_work_threads
+  attr_reader :started_at
+  attr_reader :paused_at
+  attr_reader :thread
+  attr_reader :thread_key
+  attr_reader :mutexes
 
-    attr_accessor :stderr
+  #attr_accessor :min_work_threads
+  attr_accessor :max_work_threads
 
-    attr_reader :work_queue
+  attr_accessor :stderr
 
-    def initialize(opts={})
+  attr_reader :work_queue
 
-      @opts = opts
+  def initialize(opts={})
 
-      @started_at = nil
-      @paused = false
+    @opts = opts
 
-      @jobs = JobArray.new
+    @started_at = nil
+    @paused_at = nil
 
-      @frequency = Rufus::Scheduler.parse(opts[:frequency] || 0.300)
-      @mutexes = {}
+    @jobs = JobArray.new
 
-      @work_queue = Queue.new
+    @frequency = Rufus::Scheduler.parse(opts[:frequency] || 0.300)
+    @discard_past = opts.has_key?(:discard_past) ? opts[:discard_past] : true
 
-      #@min_work_threads = opts[:min_work_threads] || MIN_WORK_THREADS
-      @max_work_threads = opts[:max_work_threads] || MAX_WORK_THREADS
+    @mutexes = {}
 
-      @stderr = $stderr
+    @work_queue = Queue.new
+    @join_queue = Queue.new
 
-      @thread_key = "rufus_scheduler_#{self.object_id}"
+    #@min_work_threads =
+    #  opts[:min_work_threads] || opts[:min_worker_threads] ||
+    #  MIN_WORK_THREADS
+    @max_work_threads =
+      opts[:max_work_threads] || opts[:max_worker_threads] ||
+      MAX_WORK_THREADS
 
-      @scheduler_lock =
-        if lockfile = opts[:lockfile]
-          Rufus::Scheduler::FileLock.new(lockfile)
-        else
-          opts[:scheduler_lock] || Rufus::Scheduler::NullLock.new
-        end
+    @stderr = $stderr
 
-      @trigger_lock = opts[:trigger_lock] || Rufus::Scheduler::NullLock.new
+    @thread_key = "rufus_scheduler_#{self.object_id}"
 
-      # If we can't grab the @scheduler_lock, don't run.
-      lock || return
+    @scheduler_lock =
+      if lockfile = opts[:lockfile]
+        Rufus::Scheduler::FileLock.new(lockfile)
+      else
+        opts[:scheduler_lock] || Rufus::Scheduler::NullLock.new
+      end
 
-      start
-    end
+    @trigger_lock = opts[:trigger_lock] || Rufus::Scheduler::NullLock.new
 
-    # Returns a singleton Rufus::Scheduler instance
-    #
-    def self.singleton(opts={})
+    # If we can't grab the @scheduler_lock, don't run.
+    lock || return
 
-      @singleton ||= Rufus::Scheduler.new(opts)
-    end
+    start
+  end
 
-    # Alias for Rufus::Scheduler.singleton
-    #
-    def self.s(opts={}); singleton(opts); end
+  # Returns a singleton Rufus::Scheduler instance
+  #
+  def self.singleton(opts={})
 
-    # Releasing the gem would probably require redirecting .start_new to
-    # .new and emit a simple deprecation message.
-    #
-    # For now, let's assume the people pointing at rufus-scheduler/master
-    # on GitHub know what they do...
-    #
-    def self.start_new
+    @singleton ||= Rufus::Scheduler.new(opts)
+  end
 
-      fail "this is rufus-scheduler 3.x, use .new instead of .start_new"
-    end
+  # Alias for Rufus::Scheduler.singleton
+  #
+  def self.s(opts={}); singleton(opts); end
 
-    def shutdown(opt=nil)
+  # Releasing the gem would probably require redirecting .start_new to
+  # .new and emit a simple deprecation message.
+  #
+  # For now, let's assume the people pointing at rufus-scheduler/master
+  # on GitHub know what they do...
+  #
+  def self.start_new
 
-      @started_at = nil
+    fail 'this is rufus-scheduler 3.x, use .new instead of .start_new'
+  end
 
-      #jobs.each { |j| j.unschedule }
-        #
-        # which provokes https://github.com/jmettraux/rufus-scheduler/issues/98
-        # using the following instead:
-        #
-      @jobs.array.each { |j| j.unschedule }
+  def uptime
 
-      @work_queue.clear
+    @started_at ? EoTime.now - @started_at : nil
+  end
 
-      if opt == :wait
-        join_all_work_threads
-      elsif opt == :kill
-        kill_all_work_threads
-      end
+  def around_trigger(job)
 
-      unlock
-    end
+    yield
+  end
 
-    alias stop shutdown
+  def uptime_s
 
-    def uptime
+    uptime ? self.class.to_duration(uptime) : ''
+  end
 
-      @started_at ? EoTime.now - @started_at : nil
-    end
+  def join(time_limit=nil)
 
-    def uptime_s
+    fail NotRunningError.new('cannot join scheduler that is not running') \
+      unless @thread
+    fail ThreadError.new('scheduler thread cannot join itself') \
+      if @thread == Thread.current
 
-      uptime ? self.class.to_duration(uptime) : ''
+    if time_limit
+      time_limit_join(time_limit)
+    else
+      no_time_limit_join
     end
+  end
 
-    def join
+  def down?
 
-      fail NotRunningError.new(
-        'cannot join scheduler that is not running'
-      ) unless @thread
+    ! @started_at
+  end
 
-      @thread.join
-    end
+  def up?
 
-    def down?
+    !! @started_at
+  end
 
-      ! @started_at
-    end
+  def paused?
 
-    def up?
+    !! @paused_at
+  end
 
-      !! @started_at
-    end
+  def pause
 
-    def paused?
+    @paused_at = EoTime.now
+  end
 
-      @paused
-    end
+  def resume(opts={})
 
-    def pause
+    dp = opts[:discard_past]
+    jobs.each { |job| job.resume_discard_past = dp }
 
-      @paused = true
-    end
+    @paused_at = nil
+  end
 
-    def resume
+  #--
+  # scheduling methods
+  #++
 
-      @paused = false
-    end
+  def at(time, callable=nil, opts={}, &block)
 
-    #--
-    # scheduling methods
-    #++
+    do_schedule(:once, time, callable, opts, opts[:job], block)
+  end
 
-    def at(time, callable=nil, opts={}, &block)
+  def schedule_at(time, callable=nil, opts={}, &block)
 
-      do_schedule(:once, time, callable, opts, opts[:job], block)
-    end
+    do_schedule(:once, time, callable, opts, true, block)
+  end
 
-    def schedule_at(time, callable=nil, opts={}, &block)
+  def in(duration, callable=nil, opts={}, &block)
 
-      do_schedule(:once, time, callable, opts, true, block)
-    end
+    do_schedule(:once, duration, callable, opts, opts[:job], block)
+  end
 
-    def in(duration, callable=nil, opts={}, &block)
+  def schedule_in(duration, callable=nil, opts={}, &block)
 
-      do_schedule(:once, duration, callable, opts, opts[:job], block)
-    end
+    do_schedule(:once, duration, callable, opts, true, block)
+  end
 
-    def schedule_in(duration, callable=nil, opts={}, &block)
+  def every(duration, callable=nil, opts={}, &block)
 
-      do_schedule(:once, duration, callable, opts, true, block)
-    end
+    do_schedule(:every, duration, callable, opts, opts[:job], block)
+  end
 
-    def every(duration, callable=nil, opts={}, &block)
+  def schedule_every(duration, callable=nil, opts={}, &block)
 
-      do_schedule(:every, duration, callable, opts, opts[:job], block)
-    end
+    do_schedule(:every, duration, callable, opts, true, block)
+  end
 
-    def schedule_every(duration, callable=nil, opts={}, &block)
+  def interval(duration, callable=nil, opts={}, &block)
 
-      do_schedule(:every, duration, callable, opts, true, block)
-    end
+    do_schedule(:interval, duration, callable, opts, opts[:job], block)
+  end
 
-    def interval(duration, callable=nil, opts={}, &block)
+  def schedule_interval(duration, callable=nil, opts={}, &block)
 
-      do_schedule(:interval, duration, callable, opts, opts[:job], block)
-    end
+    do_schedule(:interval, duration, callable, opts, true, block)
+  end
 
-    def schedule_interval(duration, callable=nil, opts={}, &block)
+  def cron(cronline, callable=nil, opts={}, &block)
 
-      do_schedule(:interval, duration, callable, opts, true, block)
-    end
+    do_schedule(:cron, cronline, callable, opts, opts[:job], block)
+  end
 
-    def cron(cronline, callable=nil, opts={}, &block)
+  def schedule_cron(cronline, callable=nil, opts={}, &block)
 
-      do_schedule(:cron, cronline, callable, opts, opts[:job], block)
-    end
+    do_schedule(:cron, cronline, callable, opts, true, block)
+  end
+
+  def schedule(arg, callable=nil, opts={}, &block)
 
-    def schedule_cron(cronline, callable=nil, opts={}, &block)
+    callable, opts = nil, callable if callable.is_a?(Hash)
+    opts = opts.dup
 
-      do_schedule(:cron, cronline, callable, opts, true, block)
+    opts[:_t] = Rufus::Scheduler.parse(arg, opts)
+
+    case opts[:_t]
+    when ::Fugit::Cron then schedule_cron(arg, callable, opts, &block)
+    when ::EtOrbi::EoTime, Time then schedule_at(arg, callable, opts, &block)
+    else schedule_in(arg, callable, opts, &block)
     end
+  end
 
-    def schedule(arg, callable=nil, opts={}, &block)
+  def repeat(arg, callable=nil, opts={}, &block)
 
-      callable, opts = nil, callable if callable.is_a?(Hash)
-      opts = opts.dup
+    callable, opts = nil, callable if callable.is_a?(Hash)
+    opts = opts.dup
 
-      opts[:_t] = Scheduler.parse(arg, opts)
+    opts[:_t] = Rufus::Scheduler.parse(arg, opts)
 
-      case opts[:_t]
-      when ::Fugit::Cron then schedule_cron(arg, callable, opts, &block)
-      when ::EtOrbi::EoTime, Time then schedule_at(arg, callable, opts, &block)
-      else schedule_in(arg, callable, opts, &block)
-      end
+    case opts[:_t]
+    when ::Fugit::Cron then schedule_cron(arg, callable, opts, &block)
+    else schedule_every(arg, callable, opts, &block)
     end
+  end
 
-    def repeat(arg, callable=nil, opts={}, &block)
+  def unschedule(job_or_job_id)
 
-      callable, opts = nil, callable if callable.is_a?(Hash)
-      opts = opts.dup
+    job, job_id = fetch(job_or_job_id)
 
-      opts[:_t] = Scheduler.parse(arg, opts)
+    fail ArgumentError.new("no job found with id '#{job_id}'") unless job
 
-      case opts[:_t]
-      when ::Fugit::Cron then schedule_cron(arg, callable, opts, &block)
-      else schedule_every(arg, callable, opts, &block)
-      end
-    end
+    job.unschedule if job
+  end
+
+  #--
+  # jobs methods
+  #++
 
-    def unschedule(job_or_job_id)
+  # Returns all the scheduled jobs
+  # (even those right before re-schedule).
+  #
+  def jobs(opts={})
 
-      job, job_id = fetch(job_or_job_id)
+    opts = { opts => true } if opts.is_a?(Symbol)
 
-      fail ArgumentError.new("no job found with id '#{job_id}'") unless job
+    jobs = @jobs.to_a
 
-      job.unschedule if job
+    if opts[:running]
+      jobs = jobs.select { |j| j.running? }
+    elsif ! opts[:all]
+      jobs = jobs.reject { |j| j.next_time.nil? || j.unscheduled_at }
     end
 
-    #--
-    # jobs methods
-    #++
+    tags = Array(opts[:tag] || opts[:tags]).collect(&:to_s)
+    jobs = jobs.reject { |j| tags.find { |t| ! j.tags.include?(t) } }
+
+    jobs
+  end
 
-    # Returns all the scheduled jobs
-    # (even those right before re-schedule).
-    #
-    def jobs(opts={})
+  def at_jobs(opts={})
 
-      opts = { opts => true } if opts.is_a?(Symbol)
+    jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::AtJob) }
+  end
 
-      jobs = @jobs.to_a
+  def in_jobs(opts={})
 
-      if opts[:running]
-        jobs = jobs.select { |j| j.running? }
-      elsif ! opts[:all]
-        jobs = jobs.reject { |j| j.next_time.nil? || j.unscheduled_at }
-      end
+    jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::InJob) }
+  end
 
-      tags = Array(opts[:tag] || opts[:tags]).collect(&:to_s)
-      jobs = jobs.reject { |j| tags.find { |t| ! j.tags.include?(t) } }
+  def every_jobs(opts={})
 
-      jobs
-    end
+    jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::EveryJob) }
+  end
 
-    def at_jobs(opts={})
+  def interval_jobs(opts={})
 
-      jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::AtJob) }
-    end
+    jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::IntervalJob) }
+  end
 
-    def in_jobs(opts={})
+  def cron_jobs(opts={})
 
-      jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::InJob) }
-    end
+    jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::CronJob) }
+  end
 
-    def every_jobs(opts={})
+  def job(job_id)
 
-      jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::EveryJob) }
-    end
+    @jobs[job_id]
+  end
 
-    def interval_jobs(opts={})
+  # 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
 
-      jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::IntervalJob) }
-    end
+  # Sister method to #lock, is called when the scheduler shuts down.
+  #
+  def unlock
 
-    def cron_jobs(opts={})
+    @trigger_lock.unlock
+    @scheduler_lock.unlock
+  end
 
-      jobs(opts).select { |j| j.is_a?(Rufus::Scheduler::CronJob) }
-    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
 
-    def job(job_id)
+    @trigger_lock.lock
+  end
 
-      @jobs[job_id]
-    end
+  # Returns true if this job is currently scheduled.
+  #
+  # Takes extra care to answer true if the job is a repeat job
+  # currently firing.
+  #
+  def scheduled?(job_or_job_id)
 
-    # 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
+    job, _ = fetch(job_or_job_id)
 
-    # Sister method to #lock, is called when the scheduler shuts down.
-    #
-    def unlock
+    !! (job && job.unscheduled_at.nil? && job.next_time != nil)
+  end
 
-      @trigger_lock.unlock
-      @scheduler_lock.unlock
-    end
+  # Lists all the threads associated with this scheduler.
+  #
+  def threads
 
-    # 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
+    Thread.list.select { |t| t[thread_key] }
+  end
 
-      @trigger_lock.lock
+  # Lists all the work threads (the ones actually running the scheduled
+  # block code)
+  #
+  # Accepts a query option, which can be set to:
+  # * :all (default), returns all the threads that are work threads
+  #   or are currently running a job
+  # * :active, returns all threads that are currently running a job
+  # * :vacant, returns the threads that are not running a job
+  #
+  # If, thanks to :blocking => true, a job is scheduled to monopolize the
+  # main scheduler thread, that thread will get returned when :active or
+  # :all.
+  #
+  def work_threads(query=:all)
+
+    ts = threads.select { |t| t[:rufus_scheduler_work_thread] }
+
+    case query
+    when :active then ts.select { |t| t[:rufus_scheduler_job] }
+    when :vacant then ts.reject { |t| t[:rufus_scheduler_job] }
+    else ts
     end
+  end
 
-    # Returns true if this job is currently scheduled.
-    #
-    # Takes extra care to answer true if the job is a repeat job
-    # currently firing.
-    #
-    def scheduled?(job_or_job_id)
+  def running_jobs(opts={})
 
-      job, _ = fetch(job_or_job_id)
+    jobs(opts.merge(:running => true))
+  end
 
-      !! (job && job.unscheduled_at.nil? && job.next_time != nil)
-    end
+  def occurrences(time0, time1, format=:per_job)
 
-    # Lists all the threads associated with this scheduler.
-    #
-    def threads
+    h = {}
 
-      Thread.list.select { |t| t[thread_key] }
+    jobs.each do |j|
+      os = j.occurrences(time0, time1)
+      h[j] = os if os.any?
     end
 
-    # Lists all the work threads (the ones actually running the scheduled
-    # block code)
-    #
-    # Accepts a query option, which can be set to:
-    # * :all (default), returns all the threads that are work threads
-    #   or are currently running a job
-    # * :active, returns all threads that are currently running a job
-    # * :vacant, returns the threads that are not running a job
-    #
-    # If, thanks to :blocking => true, a job is scheduled to monopolize the
-    # main scheduler thread, that thread will get returned when :active or
-    # :all.
-    #
-    def work_threads(query=:all)
-
-      ts = threads.select { |t| t[:rufus_scheduler_work_thread] }
-
-      case query
-      when :active then ts.select { |t| t[:rufus_scheduler_job] }
-      when :vacant then ts.reject { |t| t[:rufus_scheduler_job] }
-      else ts
-      end
+    if format == :timeline
+      a = []
+      h.each { |j, ts| ts.each { |t| a << [ t, j ] } }
+      a.sort_by { |(t, _)| t }
+    else
+      h
     end
+  end
 
-    def running_jobs(opts={})
+  def timeline(time0, time1)
 
-      jobs(opts.merge(:running => true))
-    end
+    occurrences(time0, time1, :timeline)
+  end
 
-    def occurrences(time0, time1, format=:per_job)
+  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}")
+    stderr.puts("  #{pre}     #{err}")
+    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}     local_tzone: #{EoTime.local_tzone.inspect}")
+    stderr.puts("  #{pre}   et-orbi:")
+    stderr.puts("  #{pre}     #{EoTime.platform_info}")
+    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}     frequency: #{frequency.inspect}")
+    stderr.puts("  #{pre}     discard_past: #{discard_past.inspect}")
+    stderr.puts("  #{pre}     started_at: #{started_at.inspect}")
+    stderr.puts("  #{pre}     paused_at: #{paused_at.inspect}")
+    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:")
+    stderr.puts("  #{pre}       size: #{@work_queue.size}")
+    stderr.puts("  #{pre}       num_waiting: #{@work_queue.num_waiting}")
+    stderr.puts("  #{pre}     join_queue:")
+    stderr.puts("  #{pre}       size: #{@join_queue.size}")
+    stderr.puts("  #{pre}       num_waiting: #{@join_queue.num_waiting}")
+    stderr.puts("} #{pre} .")
+
+  rescue => e
+
+    stderr.puts("failure in #on_error itself:")
+    stderr.puts(e.inspect)
+    stderr.puts(e.backtrace)
+
+  ensure
+
+    stderr.flush
+  end
 
-      h = {}
+  def shutdown(opt=nil)
 
-      jobs.each do |j|
-        os = j.occurrences(time0, time1)
-        h[j] = os if os.any?
+    opts =
+      case opt
+      when Symbol then { opt => true }
+      when Hash then opt
+      else {}
       end
 
-      if format == :timeline
-        a = []
-        h.each { |j, ts| ts.each { |t| a << [ t, j ] } }
-        a.sort_by { |(t, _)| t }
-      else
-        h
-      end
+    @jobs.unschedule_all
+
+    if opts[:wait] || opts[:join]
+      join_shutdown(opts)
+    elsif opts[:kill]
+      kill_shutdown(opts)
+    else
+      regular_shutdown(opts)
     end
 
-    def timeline(time0, time1)
+    @work_queue.clear
 
-      occurrences(time0, time1, :timeline)
-    end
+    unlock
 
-    def on_error(job, err)
+    @thread.join
+  end
+  alias stop shutdown
 
-      pre = err.object_id.to_s
+  protected
 
-      ms = {}; mutexes.each { |k, v| ms[k] = v.locked? }
+  def join_shutdown(opts)
 
-      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}")
-      stderr.puts("  #{pre}     #{err}")
-      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}     local_tzone: #{EoTime.local_tzone.inspect}")
-      stderr.puts("  #{pre}   et-orbi:")
-      stderr.puts("  #{pre}     #{EoTime.platform_info}")
-      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
-
-      stderr.puts("failure in #on_error itself:")
-      stderr.puts(e.inspect)
-      stderr.puts(e.backtrace)
-
-    ensure
-
-      stderr.flush
-    end
+    limit = opts[:wait] || opts[:join]
+    limit = limit.is_a?(Numeric) ? limit : nil
 
-    protected
+    #@started_at = nil
+      #
+      # when @started_at is nil, the scheduler thread exits, here
+      # we want it to exit when all the work threads have been joined
+      # hence it's set to nil later on
+      #
+    @paused_at = EoTime.now
 
-    # Returns [ job, job_id ]
-    #
-    def fetch(job_or_job_id)
+    (work_threads.size * 2 + 1).times { @work_queue << :shutdown }
 
-      if job_or_job_id.respond_to?(:job_id)
-        [ job_or_job_id, job_or_job_id.job_id ]
-      else
-        [ job(job_or_job_id), job_or_job_id ]
-      end
-    end
+    work_threads
+      .collect { |wt|
+        wt == Thread.current ? nil : Thread.new { wt.join(limit); wt.kill } }
+      .each { |st|
+        st.join if st }
 
-    def terminate_all_jobs
+    @started_at = nil
+  end
 
-      jobs.each { |j| j.unschedule }
+  def kill_shutdown(opts)
 
-      sleep 0.01 while running_jobs.size > 0
-    end
+    @started_at = nil
+    work_threads.each(&:kill)
+  end
+
+  def regular_shutdown(opts)
+
+    @started_at = nil
+  end
 
-    def join_all_work_threads
+  def time_limit_join(limit)
 
-      work_threads.size.times { @work_queue << :sayonara }
+    fail ArgumentError.new("limit #{limit.inspect} should be > 0") \
+      unless limit.is_a?(Numeric) && limit > 0
 
-      work_threads.each { |t| t.join }
+    t0 = monow
+    f = [ limit.to_f / 20, 0.100 ].min
 
-      @work_queue.clear
+    while monow - t0 < limit
+      r =
+        begin
+          @join_queue.pop(true)
+        rescue ThreadError => e
+          # #<ThreadError: queue empty>
+          false
+        end
+      return r if r
+      sleep(f)
     end
 
-    def kill_all_work_threads
+    nil
+  end
+
+  def no_time_limit_join
+
+    @join_queue.pop
+  end
+
+  # Returns [ job, job_id ]
+  #
+  def fetch(job_or_job_id)
 
-      work_threads.each { |t| t.kill }
+    if job_or_job_id.respond_to?(:job_id)
+      [ job_or_job_id, job_or_job_id.job_id ]
+    else
+      [ job(job_or_job_id), job_or_job_id ]
     end
+  end
+
+  def terminate_all_jobs
 
-    #def free_all_work_threads
-    #
-    #  work_threads.each { |t| t.raise(KillSignal) }
-    #end
+    jobs.each { |j| j.unschedule }
 
-    def start
+    sleep 0.01 while running_jobs.size > 0
+  end
+
+  #def free_all_work_threads
+  #
+  #  work_threads.each { |t| t.raise(KillSignal) }
+  #end
 
-      @started_at = EoTime.now
+  def start
 
-      @thread =
-        Thread.new do
+    @started_at = EoTime.now
 
-          while @started_at do
+    @thread =
+      Thread.new do
 
-            unschedule_jobs
-            trigger_jobs unless @paused
-            timeout_jobs
+        while @started_at do
 
-            sleep(@frequency)
-          end
+          unschedule_jobs
+          trigger_jobs unless @paused_at
+          timeout_jobs
+
+          sleep(@frequency)
         end
 
-      @thread[@thread_key] = true
-      @thread[:rufus_scheduler] = self
-      @thread[:name] = @opts[:thread_name] || "#{@thread_key}_scheduler"
-    end
+        rejoin
+      end
+
+    @thread[@thread_key] = true
+    @thread[:rufus_scheduler] = self
+    @thread[:name] = @opts[:thread_name] || "#{@thread_key}_scheduler"
+  end
 
-    def unschedule_jobs
+  def unschedule_jobs
 
-      @jobs.delete_unscheduled
-    end
+    @jobs.delete_unscheduled
+  end
 
-    def trigger_jobs
+  def trigger_jobs
 
-      now = EoTime.now
+    now = EoTime.now
 
-      @jobs.each(now) do |job|
+    @jobs.each(now) do |job|
 
-        job.trigger(now)
-      end
+      job.trigger(now)
     end
+  end
 
-    def timeout_jobs
+  def timeout_jobs
 
-      work_threads(:active).each do |t|
+    work_threads(:active).each do |t|
 
-        job = t[:rufus_scheduler_job]
-        to = t[:rufus_scheduler_timeout]
-        ts = t[:rufus_scheduler_time]
+      job = t[:rufus_scheduler_job]
+      to = t[:rufus_scheduler_timeout]
+      ts = t[:rufus_scheduler_time]
 
-        next unless job && to && ts
-          # thread might just have become inactive (job -> nil)
+      next unless job && to && ts
+        # thread might just have become inactive (job -> nil)
 
-        to = ts + to unless to.is_a?(EoTime)
+      to = ts + to unless to.is_a?(EoTime)
 
-        next if to > EoTime.now
+      next if to > EoTime.now
 
-        t.raise(Rufus::Scheduler::TimeoutError)
-      end
+      t.raise(Rufus::Scheduler::TimeoutError)
     end
+  end
+
+  def rejoin
 
-    def do_schedule(job_type, t, callable, opts, return_job_instance, block)
+    (@join_queue.num_waiting * 2 + 1).times { @join_queue << @thread }
+  end
 
-      fail NotRunningError.new(
-        'cannot schedule, scheduler is down or shutting down'
-      ) if @started_at.nil?
+  def do_schedule(job_type, t, callable, opts, return_job_instance, block)
 
-      callable, opts = nil, callable if callable.is_a?(Hash)
-      opts = opts.dup unless opts.has_key?(:_t)
+    fail NotRunningError.new(
+      'cannot schedule, scheduler is down or shutting down'
+    ) if @started_at.nil?
 
-      return_job_instance ||= opts[:job]
+    callable, opts = nil, callable if callable.is_a?(Hash)
+    opts = opts.dup unless opts.has_key?(:_t)
 
-      job_class =
-        case job_type
-        when :once
-          opts[:_t] ||= Rufus::Scheduler.parse(t, opts)
-          opts[:_t].is_a?(Numeric) ? InJob : AtJob
-        when :every
-          EveryJob
-        when :interval
-          IntervalJob
-        when :cron
-          CronJob
-        end
+    return_job_instance ||= opts[:job]
 
-      job = job_class.new(self, t, opts, block || callable)
-      job.check_frequency
+    job_class =
+      case job_type
+      when :once
+        opts[:_t] ||= Rufus::Scheduler.parse(t, opts)
+        opts[:_t].is_a?(Numeric) ? InJob : AtJob
+      when :every
+        EveryJob
+      when :interval
+        IntervalJob
+      when :cron
+        CronJob
+      end
 
-      @jobs.push(job)
+    job = job_class.new(self, t, opts, block || callable)
+    job.check_frequency
 
-      return_job_instance ? job : job.job_id
-    end
+    @jobs.push(job)
+
+    return_job_instance ? job : job.job_id
   end
+
+  def monow; self.class.monow; end
+  def ltstamp; self.class.ltstamp; end
 end