The Scheduler is used by OpenWFEru for registering ‘at’ and ‘cron’ jobs. ‘at’ jobs to execute once at a given point in time. ‘cron’ jobs execute a specified intervals. The two main methods are thus schedule_at() and schedule().

schedule_at() and schedule() await either a Schedulable instance and params (usually an array or nil), either a block, which is more in the Ruby way.

The gem "rufus-scheduler"

This scheduler was previously known as the "openwferu-scheduler" gem.

To ensure that code tapping the previous gem still runs fine with "rufus-scheduler", this new gem has ‘pointers’ for the old class names.

 require 'rubygems'
 require 'openwfe/util/scheduler'
 s = OpenWFE::Scheduler.new

will still run OK with "rufus-scheduler".

Examples

 require 'rubygems'
 require 'rufus/scheduler'

 scheduler = Rufus::Scheduler.start_new

 scheduler.schedule_in("3d") do
   regenerate_monthly_report()
 end
   #
   # will call the regenerate_monthly_report method
   # in 3 days from now

  scheduler.schedule "0 22 * * 1-5" do
    log.info "activating security system..."
    activate_security_system()
  end

  job_id = scheduler.schedule_at "Sun Oct 07 14:24:01 +0900 2009" do
    init_self_destruction_sequence()
  end

an example that uses a Schedulable class :

 class Regenerator < Schedulable
   def trigger (frequency)
     self.send(frequency)
   end
   def monthly
     # ...
   end
   def yearly
     # ...
   end
 end

 regenerator = Regenerator.new

 scheduler.schedule_in("4d", regenerator)
   #
   # will regenerate the report in four days

 scheduler.schedule_in(
   "5d",
   { :schedulable => regenerator, :scope => :month })
     #
     # will regenerate the monthly report in 5 days

There is also schedule_every() :

  scheduler.schedule_every("1h20m") do
    regenerate_latest_report()
  end

(note : a schedule every isn‘t triggered immediately, thus this example will first trigger 1 hour and 20 minutes after being scheduled)

The scheduler has a "exit_when_no_more_jobs" attribute. When set to ‘true’, the scheduler will exit as soon as there are no more jobs to run. Use with care though, if you create a scheduler, set this attribute to true and start the scheduler, the scheduler will immediately exit. This attribute is best used indirectly : the method join_until_no_more_jobs() wraps it.

The :scheduler_precision can be set when instantiating the scheduler.

  scheduler = Rufus::Scheduler.new(:scheduler_precision => 0.500)
  scheduler.start
    #
    # instatiates a scheduler that checks its jobs twice per second
    # (the default is 4 times per second (0.250))

Note that rufus-scheduler places a constraint on the values for the precision : 0.0 < p <= 1.0 Thus

  scheduler.precision = 4.0

or

  scheduler = Rufus::Scheduler.new :scheduler_precision => 5.0

will raise an exception.

Tags

Tags can be attached to jobs scheduled :

  scheduler.schedule_in "2h", :tags => "backup" do
    init_backup_sequence()
  end

  scheduler.schedule "0 24 * * *", :tags => "new_day" do
    do_this_or_that()
  end

  jobs = find_jobs 'backup'
  jobs.each { |job| job.unschedule }

Multiple tags may be attached to a single job :

  scheduler.schedule_in "2h", :tags => [ "backup", "important" ]  do
    init_backup_sequence()
  end

The vanilla case for tags assume they are String instances, but nothing prevents you from using anything else. The scheduler has no persistence by itself, so no serialization issue.

Cron up to the second

A cron schedule can be set at the second level :

  scheduler.schedule "7 * * * * *" do
    puts "it's now the seventh second of the minute"
  end

The rufus scheduler recognizes an optional first column for second scheduling. This column can, like for the other columns, specify a value ("7"), a list of values ("7,8,9,27") or a range ("7-12").

information passed to schedule blocks

When calling schedule_every(), schedule_in() or schedule_at(), the block expects zero or 3 parameters like in

  scheduler.schedule_every("1h20m") do |job_id, at, params|
      puts "my job_id is #{job_id}"
  end

For schedule(), zero or two parameters can get passed

  scheduler.schedule "7 * * * * *" do |job_id, cron_line, params|
    puts "my job_id is #{job_id}"
  end

In both cases, params corresponds to the params passed to the schedule method (:tags, :first_at, :first_in, :dont_reschedule, …)

Exceptions

The rufus scheduler will output a stacktrace to the STDOUT in case of exception. There are two ways to change that behaviour.

  # 1 - providing a lwarn method to the scheduler instance :

  class << scheduler
    def lwarn (&block)
      puts "oops, something wrong happened : "
      puts block.call
    end
  end

  # 2 - overriding the [protected] method log_exception(e) :

  class << scheduler
    def log_exception (e)
      puts "something wrong happened : "+e.to_s
    end
  end

‘Every jobs’ and rescheduling

Every jobs can reschedule/unschedule themselves. A reschedule example :

  schedule.schedule_every "5h" do |job_id, at, params|

    mails = $inbox.fetch_mails
    mails.each { |m| $inbox.mark_as_spam(m) if is_spam(m) }

    params[:every] = if mails.size > 100
      "1h" # lots of spam, check every hour
    else
      "5h" # normal schedule, every 5 hours
    end
  end

Unschedule example :

  schedule.schedule_every "10s" do |job_id, at, params|
    #
    # polls every 10 seconds until a mail arrives

    $mail = $inbox.fetch_last_mail

    params[:dont_reschedule] = true if $mail
  end

‘Every jobs’, :first_at and :first_in

Since rufus-scheduler 1.0.2, the schedule_every methods recognizes two optional parameters, :first_at and :first_in

  scheduler.schedule_every "2d", :first_in => "5h" do
    # schedule something every two days, start in 5 hours...
  end

  scheduler.schedule_every "2d", :first_at => "5h" do
    # schedule something every two days, start in 5 hours...
  end

job.next_time()

Jobs, be they at, every or cron have a next_time() method, which tells when the job will be fired next time (for at and in jobs, this is also the last time).

For cron jobs, the current implementation is quite brutal. It takes three seconds on my 2006 macbook to reach a cron schedule 1 year away.

When is the next friday 13th ?

  require 'rubygems'
  require 'rufus/scheduler'

  puts Rufus::CronLine.new("* * 13 * fri").next_time

:thread_name option

You can specify the name of the scheduler‘s thread. Should make it easier in some debugging situations.

  scheduler.new :thread_name => "the crazy scheduler"

job.trigger_thread

Since rufus-scheduler 1.0.8, you can have access to the thread of a job currently being triggered.

  job = scheduler.get_job(job_id)
  thread = job.trigger_thread

This new method will return nil if the job is not currently being triggered. Not that in case of an every or cron job, this method will return the thread of the last triggered instance, thus, in case of overlapping executions, you only get the most recent thread.