README.md in clockwork-0.5.4 vs README.md in clockwork-0.5.5
- old
+ new
@@ -14,55 +14,67 @@
Quickstart
----------
Create clock.rb:
- require 'clockwork'
- include Clockwork
+```ruby
+require 'clockwork'
+include Clockwork
- handler do |job|
- puts "Running #{job}"
- end
+handler do |job|
+ puts "Running #{job}"
+end
- every(10.seconds, 'frequent.job')
- every(3.minutes, 'less.frequent.job')
- every(1.hour, 'hourly.job')
+every(10.seconds, 'frequent.job')
+every(3.minutes, 'less.frequent.job')
+every(1.hour, 'hourly.job')
- every(1.day, 'midnight.job', :at => '00:00')
+every(1.day, 'midnight.job', :at => '00:00')
+```
Run it with the clockwork binary:
- $ clockwork clock.rb
- Starting clock for 4 events: [ frequent.job less.frequent.job hourly.job midnight.job ]
- Triggering frequent.job
+```
+$ clockwork clock.rb
+Starting clock for 4 events: [ frequent.job less.frequent.job hourly.job midnight.job ]
+Triggering frequent.job
+```
If you would not like to taint the namespace with `include Clockwork`, you can use
it as the module (thanks to [hoverlover](https://github.com/hoverlover/clockwork/)).
- require 'clockwork'
+As reported in [issue #41](https://github.com/tomykaira/clockwork/issues/41#issuecomment-22073609),
+this technique is necessary when you use Clockwork with Sinatra,
+because both Sinatra and Clockwork add `register()` method into global namespace.
- module Clockwork
+```ruby
+require 'clockwork'
- configure do |config|
- config[:tz] = "America/Chicago"
- end
+module Clockwork
- handler do |job|
- puts "Running #{job}"
- end
+ configure do |config|
+ config[:tz] = "America/Chicago"
+ end
- every(10.seconds, 'frequent.job')
- every(3.minutes, 'less.frequent.job')
- every(1.hour, 'hourly.job')
+ handler do |job|
+ puts "Running #{job}"
+ end
- every(1.day, 'midnight.job', :at => '00:00')
- end
+ every(10.seconds, 'frequent.job')
+ every(3.minutes, 'less.frequent.job')
+ every(1.hour, 'hourly.job')
+ every(1.day, 'midnight.job', :at => '00:00')
+end
+```
+
If you need to load your entire environment for your jobs, simply add:
- require './config/boot'
- require './config/environment'
+```ruby
+require './config/boot'
+require './config/environment'
+```
under the `require 'clockwork'` declaration.
Quickstart for Heroku
---------------------
@@ -87,75 +99,92 @@
simple clock process with no locks, but also offers near infinite horizontal
scalability.
For example, if you're using Beanstalk/Staker:
- require 'stalker'
+```ruby
+require 'stalker'
- handler { |job| Stalker.enqueue(job) }
+handler { |job| Stalker.enqueue(job) }
- every(1.hour, 'feeds.refresh')
- every(1.day, 'reminders.send', :at => '01:30')
+every(1.hour, 'feeds.refresh')
+every(1.day, 'reminders.send', :at => '01:30')
+```
Using a queueing system which doesn't require that your full application be
loaded is preferable, because the clock process can keep a tiny memory
footprint. If you're using DJ or Resque, however, you can go ahead and load
your full application enviroment, and use per-event blocks to call DJ or Resque
enqueue methods. For example, with DJ/Rails:
- require 'config/boot'
- require 'config/environment'
+```ruby
+require 'config/boot'
+require 'config/environment'
- every(1.hour, 'feeds.refresh') { Feed.send_later(:refresh) }
- every(1.day, 'reminders.send', :at => '01:30') { Reminder.send_later(:send_reminders) }
+every(1.hour, 'feeds.refresh') { Feed.send_later(:refresh) }
+every(1.day, 'reminders.send', :at => '01:30') { Reminder.send_later(:send_reminders) }
+```
Parameters
----------
### :at
`:at` parameter the hour and minute specifies when the event occur.
The simplest example:
- every(1.day, 'reminders.send', :at => '01:30')
+```ruby
+every(1.day, 'reminders.send', :at => '01:30')
+```
You can omit 0 of the hour:
- every(1.day, 'reminders.send', :at => '1:30')
+```ruby
+every(1.day, 'reminders.send', :at => '1:30')
+```
The wildcard for hour is supported:
- every(1.hour, 'reminders.send', :at => '**:30')
+```ruby
+every(1.hour, 'reminders.send', :at => '**:30')
+```
You can set more than one timing:
- every(1.hour, 'reminders.send', :at => ['12:00', '18:00'])
- # send reminders at noon and evening
+```ruby
+every(1.hour, 'reminders.send', :at => ['12:00', '18:00'])
+# send reminders at noon and evening
+```
You can also specify a timezone (default is the local timezone):
- every(1.day, 'reminders.send', :at => '00:00', :tz => 'UTC')
- # Runs the job each day at midnight, UTC.
- # The value for :tz can be anything supported by [TZInfo](http://tzinfo.rubyforge.org/)
+```ruby
+every(1.day, 'reminders.send', :at => '00:00', :tz => 'UTC')
+# Runs the job each day at midnight, UTC.
+# The value for :tz can be anything supported by [TZInfo](http://tzinfo.rubyforge.org/)
+```
### :if
`:if` parameter is invoked every time the task is ready to run, and run if the
return value is true.
Run on every first day of month.
- Clockwork.every(1.day, 'myjob', :if => lambda { |t| t.day == 1 })
+```ruby
+Clockwork.every(1.day, 'myjob', :if => lambda { |t| t.day == 1 })
+```
The argument is an instance of `ActiveSupport::TimeWithZone` if the `:tz` option is set. Otherwise, it's an instance of `Time`.
This argument cannot be omitted. Please use _ as placeholder if not needed.
- Clockwork.every(1.second, 'myjob', :if => lambda { |_| true })
+```ruby
+Clockwork.every(1.second, 'myjob', :if => lambda { |_| true })
+```
-
### :thread
A handler with `:thread` parameter runs in a different thread.
If a job is long running or IO-intensive, this option will be useful to keep the clock precise.
@@ -186,16 +215,18 @@
Clockwork runs handlers in threads. If it exceeds `max_threads`, it will warn you about missing
jobs.
### Configuration example
- Clockwork.configure do |config|
- config[:sleep_timeout] = 5
- config[:logger] = Logger.new(log_file_path)
- config[:tz] = 'EST'
- config[:max_threads] = 15
- end
+```ruby
+Clockwork.configure do |config|
+ config[:sleep_timeout] = 5
+ config[:logger] = Logger.new(log_file_path)
+ config[:tz] = 'EST'
+ config[:max_threads] = 15
+end
+```
Anatomy of a clock file
-----------------------
clock.rb is standard Ruby. Since we include the Clockwork module (the
@@ -203,40 +234,48 @@
exposes a small DSL ("handler" and "every") to define the handler for events,
and then the events themselves.
The handler typically looks like this:
- handler { |job| enqueue_your_job(job) }
+```ruby
+handler { |job| enqueue_your_job(job) }
+```
This block will be invoked every time an event is triggered, with the job name
passed in. In most cases, you should be able to pass the job name directly
through to your queueing system.
The second part of the file are the events, which roughly resembles a crontab:
- every(5.minutes, 'thing.do')
- every(1.hour, 'otherthing.do')
+```ruby
+every(5.minutes, 'thing.do')
+every(1.hour, 'otherthing.do')
+```
In the first line of this example, an event will be triggered once every five
minutes, passing the job name 'thing.do' into the handler. The handler shown
above would thus call enqueue_your_job('thing.do').
You can also pass a custom block to the handler, for job queueing systems that
rely on classes rather than job names (i.e. DJ and Resque). In this case, you
need not define a general event handler, and instead provide one with each
event:
- every(5.minutes, 'thing.do') { Thing.send_later(:do) }
+```ruby
+every(5.minutes, 'thing.do') { Thing.send_later(:do) }
+```
If you provide a custom handler for the block, the job name is used only for
logging.
You can also use blocks to do more complex checks:
- every(1.day, 'check.leap.year') do
- Stalker.enqueue('leap.year.party') if Time.now.year % 4 == 0
- end
+```ruby
+every(1.day, 'check.leap.year') do
+ Stalker.enqueue('leap.year.party') if Time.now.year % 4 == 0
+end
+```
In production
-------------
Only one clock process should ever be running across your whole application
@@ -257,10 +296,12 @@
You need `daemons` gem to use `clockworkd`. It is not automatically installed, please install by yourself.
Then,
- clockworkd -c YOUR_CLOCK.rb start
+```
+clockworkd -c YOUR_CLOCK.rb start
+```
For more details, see help shown by `clockworkd`.
Meta
----