README.md in rufus-scheduler-3.0.6 vs README.md in rufus-scheduler-3.0.7
- old
+ new
@@ -1,9 +1,10 @@
# rufus-scheduler
[](http://travis-ci.org/jmettraux/rufus-scheduler)
+[](http://badge.fury.io/rb/rufus-scheduler)
Job scheduler for Ruby (at, cron, in and every jobs).
**Note**: maybe are you looking for the [README of rufus-scheduler 2.x](https://github.com/jmettraux/rufus-scheduler/blob/two/README.rdoc)?
@@ -111,10 +112,12 @@
### faq
* [It doesn't work...](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html)
* [I want a refund](http://blog.nodejitsu.com/getting-refunds-on-open-source-projects)
* [Passenger and rufus-scheduler](http://stackoverflow.com/questions/18108719/debugging-rufus-scheduler/18156180#18156180)
+* [Passenger and rufus-scheduler (2)](http://stackoverflow.com/questions/21861387/rufus-cron-job-not-working-in-apache-passenger#answer-21868555)
+* [Unicorn and rufus-scheduler](https://jkraemer.net/running-rufus-scheduler-in-a-unicorn-rails-app)
## scheduling
Rufus-scheduler supports five kinds of jobs. in, at, every, interval and cron jobs.
@@ -247,10 +250,29 @@
The second argument is "time", it's the time when the job got cleared for triggering (not Time.now).
Note that time is the time when the job got cleared for triggering. If there are mutexes involved, now = mutex_wait_time + time...
+#### "every" jobs and changing the next_time in-flight
+
+It's OK to change the next_time of an every job in-flight:
+
+```ruby
+scheduler.every '10m' do |job|
+
+ # ...
+
+ status = determine_pie_status
+
+ job.next_time = Time.now + 30 * 60 if status == 'burnt'
+ #
+ # if burnt, wait 30 minutes for the oven to cool a bit
+end
+```
+
+It should work as well with cron jobs, not so with interval jobs whose next_time is computed after their block ends its current run.
+
### scheduling handler instances
It's OK to pass any object, as long as it respond to #call(), when scheduling:
```ruby
@@ -589,11 +611,10 @@
# => #<Method: MyHandler#call>
job.callable
# => #<MyHandler:0x0000000163ae88 @counter=0>
```
-
### scheduled_at
Returns the Time instance when the job got created.
```ruby
@@ -611,10 +632,16 @@
# ...
job.scheduled_at
# => 2013-07-17 23:48:54 +0900
```
+### last_work_time, mean_work_time
+
+The job keeps track of how long its work was in the `last_work_time` attribute. For a one time job (in, at) it's probably not very useful.
+
+The attribute `mean_work_time` contains a computed mean work time. It's recomputed after every run (if it's a repeat job).
+
### unschedule
Unschedule the job, preventing it from firing again and removing it from the schedule. This doesn't prevent a running thread for this job to run until its end.
### threads
@@ -751,10 +778,14 @@
### next_time
Returns the next time the job will trigger (hopefully).
+### count
+
+Returns how many times the job fired.
+
## EveryJob methods
### frequency
It returns the scheduling frequency. For a job scheduled "every 20s", it's 20.
@@ -876,10 +907,20 @@
### Scheduler#down?
Returns true if the scheduler has been shut down.
+### Scheduler#started_at
+
+Returns the Time instance at which the scheduler got started.
+
+### Scheduler #uptime / #uptime_s
+
+Returns since the count of seconds for which the scheduler has been running.
+
+```#uptime_s``` returns this count in a String easier to grasp for humans, like ```"3d12m45s123"```.
+
### Scheduler#join
Let's the current thread join the scheduling thread in rufus-scheduler. The thread comes back when the scheduler gets shut down.
### Scheduler#threads
@@ -898,11 +939,21 @@
### Scheduler#scheduled?(job_or_job_id)
Returns true if the arg is a currently scheduled job (see Job#scheduled?).
+### Scheduler#occurrences(time0, time1)
+Returns a hash ```{ job => [ t0, t1, ... ] }``` mapping jobs to their potential trigger time within the ```[ time0, time1 ]``` span.
+
+Please note that, for interval jobs, the ```#mean_work_time``` is used, so the result is only a prediction.
+
+### Scheduler#timeline(time0, time1)
+
+Like `#occurrences` but returns a list ```[ [ t0, job0 ], [ t1, job1 ], ... ]``` of time + job pairs.
+
+
## dealing with job errors
The easy, job-granular way of dealing with errors is to rescue and deal with them immediately. The two next sections show examples. Skip them for explanations on how to deal with errors at the scheduler level.
### block jobs
@@ -1042,11 +1093,11 @@
If the lockfile mechanism here is not sufficient, you can plug your custom mechanism. It's explained in [advanced lock schemes](#advanced-lock-schemes) below.
### :max_work_threads
-In rufus-scheduler 2.x, by default, each job triggering received its own, new, hthread of execution. In rufus-scheduler 3.x, execution happens in a work thread and the max work thread count defaults to 28.
+In rufus-scheduler 2.x, by default, each job triggering received its own, brand new, thread of execution. In rufus-scheduler 3.x, execution happens in a pooled work thread. The max work thread count (the pool size) defaults to 28.
One can set this maximum value when starting the scheduler.
```ruby
scheduler = Rufus::Scheduler.new(:max_work_threads => 77)
@@ -1258,9 +1309,60 @@
```
Unknown timezones, typos, will be rejected by tzinfo thus rufus-scheduler.
On its own tzinfo derives the timezones from the system's information. On some system it needs some help, one can install the 'tzinfo-data' gem to provide the missing information.
+
+
+## so Rails?
+
+Yes, I know, all of the above is boring and you're only looking for a snippet to paste in your Ruby-on-Rails application to schedule...
+
+Here is an example initializer:
+
+```ruby
+#
+# config/initializers/scheduler.rb
+
+require 'rufus-scheduler'
+
+# Let's use the rufus-scheduler singleton
+#
+s = Rufus::Scheduler.singleton
+
+
+# Stupid recurrent task...
+#
+s.every '1m' do
+
+ Rails.logger.info "hello, it's #{Time.now}"
+end
+```
+
+And now you tell me that this is good, but you want to schedule stuff from your controller.
+
+Maybe:
+
+```ruby
+class ScheController < ApplicationController
+
+ # GET /sche/
+ #
+ def index
+
+ job_id =
+ Rufus::Scheduler.singleton.in '5s' do
+ Rails.logger.info "time flies, it's now #{Time.now}"
+ end
+
+ render :text => "scheduled job #{job_id}"
+ end
+end
+```
+
+The rufus-scheduler singleton is instantiated in the ```config/initializers/scheduler.rb``` file, it's then available throughout the webapp via ```Rufus::Scheduler.singleton```.
+
+*Warning*: this works well with single-process Ruby servers like Webrick and Thin. Using rufus-scheduler with Passenger or Unicorn requires a bit more knowledge and tuning, gently provided by a bit of googling and reading, see [Faq](#faq) above.
## support
see [getting help](#getting-help) above.