libbackgroundrb-ruby1.8 1.1-1 / usr / share / backgroundrb / doc / content / scheduling / scheduling.txt

<div id="content">

%(entry-title)<a name="timer_scheduling"> Timer Based Scheduling </a>%

Simple tasks in the workers can be scheduled using @add_timer@ or @add_periodic_timer@ methods.
For example:

<pre class="multiline">class HelloWorker < BackgrounDRb::MetaWorker
  set_worker_name :hello_worker

  def create(args = nil)
    # time argument is in seconds
    add_periodic_timer(10) { expire_sessions }
  end

  def expire_sessions
    # expire user sessions
  end
end </pre>

Similarly one can use @add_timer@ to fire oneshot task execution.

%(entry-title)<a name="unix_scheduling"> Unix Scheduler </a>%

_BackgrounDRb_ supports normal unix styled schedules which can be configured
from @backgroundrb.yml@ file. A sample configuration looks like:

<pre class="multiline">:backgroundrb:
  :ip: 0.0.0.0
  :port: 11006
:schedules:
  :foo_worker:
    :foobar:
      :trigger_args:
        :start: <%= Time.now + 5.seconds %>
        :end: <%= Time.now + 10.minutes %>
        :repeat_interval: <%= 1.minute %> </pre>

Above scheduler option schedules method @foobar@ defined inside @foo_worker@ to start
executing by 5 seconds delay and stop after 10 minutes. Method should periodically execute
every 1 minute between that time period. *Never in any scheduling option, you should schedule @create@
method/task*

%(entry-title)<a name="cron_scheduling"> Cron Scheduling </a>%

_BackgrounDRb_ also supports Cron based ccheduling.
You can use a configuration file for cron scheduling of workers. The method specified in the configuration
file would be called periodically. You should accommodate for the fact that the time gap between periodic
invocation of a method should be more than the time that is actually required to execute the method.
If a method takes longer time than the time window specified, your method invocations will lag
perpetually.

A Sample Configuration file for Cron based Scheduling looks like:

<pre class="multiline">
:backgroundrb:
  :ip: 0.0.0.0
  :port: 11006
:schedules:
  :foo_worker:
    :barbar:
      :trigger_args: */10 * * * * *
      :data: Hello World </pre>


Above scheduler will schedule invocation of @barbar@ method inside @foo_worker@ at every 10 seconds.
You can also schedule invocation of multiple methods in same worker at different intervals, just use
following as an example configuration file.

<pre class="multiline">
:backgroundrb:
  :ip: 0.0.0.0
  :port: 11006
:schedules:
  :foo_worker:
    :barbar:
      :trigger_args: */10 * * * * *
      :data: Hello World
    :some_task: # execute some_method in foo_worker every 2nd hour
      :trigger_args: 0 * */2 * * *
      :data: Hello World </pre>


p(sub-title). A Word about Cron Scheduler

Note that the initial field in the BackgrounDRb cron trigger specifies
seconds, not minutes as with Unix-cron.

The fields (which can be an asterisk, meaning all valid patterns) are:

<pre class="boxed">sec[0,59] min[0,59], hour[0,23], day[1,31], month[1,12], weekday[0,6], year</pre>

The syntax pretty much follows Unix-cron. The following will trigger
on the first hour and the thirtieth minute every day:

<pre class="boxed">0 30 1 * * * *</pre>

The following will trigger the specified method every 10 seconds:

<pre class="boxed">*/10 * * * * * *</pre>

The following will trigger the specified method every 1 hour:

<pre class="boxed">0 0 * * * * *</pre>

For each field you can use a comma-separated list. The following would
trigger on the 5th, 16th and 23rd minute every hour:

<pre class="boxed"> 5,16,23 * * * * *</pre>

Fields also support ranges, using a dash between values. The following
triggers from 8th through the 17th hour, at five past the hour:

<pre class="boxed"> 5 8-17 * * * *</pre>

Finally, fields support repeat interval syntax. The following triggers
every five minutes, every other hour after the sixth hour:

<pre class="boxed"> */5 6/2 * * * *</pre>

Here is a more complex example: months 0,2,4,5,6,8,10,12, every day
and hour, minutes 1,2,3,4,6,20, seconds: every 5th second counting
from the 28th second plus the 59th second:


<pre class="boxed">28/5,59 1-4,6,20 */1 * 5,0/2 * *</pre>

Note that if you specify an asterisk in the first field (seconds)
it will trigger every second for the subsequent match.

%(entry-title)<a name="restart_on_schedule"> Restart worker on schedule </a>%

Usually when your worker is scheduled to execute at longer intervals, it
doesn't make sense to have worker around, when its doing nothing. Since, scheduling
via configuration file requires that your worker must be loaded when _BackgrounDRb_ starts,
your worker is always around, even when doing nothing.

You can reuse worker in processing requests from rails, but if its not possible
and you rather want worker to start afresh each time, scheduler detects a firetime, you can use
following syntax to autostart workers on scheduled time:

<pre class="multiline">class HelloWorker < BackgrounDRb::MetaWorker
  set_worker_name :hello_worker
  reload_on_schedule true

  def create(args = nil)
    # this method is called, when worker is loaded for the first time
  end
end </pre>

In above worker @reload_on_schedule true@ makes sure that your worker is restarted on
scheduled time. This feature is only available in version 1.0.3 onwards.

%(entry-title)<a name="schedule_at"> Schedule one shot execution of task at specified time </a>%

<p><b> Only available for tasks persisted to database table </b></p>

If you are using job queue table and want one shot execution of a task scheduled at a particular time. You can use:

<pre class="multiline">MiddleMan(:hello_worker).enq_some_task(:arg => "hello_world",
   :job_key => "boy",:scheduled_at => Time.now + 30.minutes)</pre>

Which will schedule specified task to be executed after 30 minutes from now.


</div>