README.md in clockwork-2.0.3 vs README.md in clockwork-2.0.4

- old
+ new

@@ -1,6 +1,6 @@ -Clockwork - a clock process to replace cron [![Build Status](https://api.travis-ci.org/Rykian/clockwork.png?branch=master)](https://travis-ci.org/Rykian/clockwork) [![Dependency Status](https://gemnasium.com/Rykian/clockwork.png)](https://gemnasium.com/Rykian/clockwork) +Clockwork - a clock process to replace cron [![Build Status](https://api.travis-ci.org/Rykian/clockwork.png?branch=master)](https://travis-ci.org/Rykian/clockwork) =========================================== Cron is non-ideal for running scheduled application tasks, especially in an app deployed to multiple machines. [More details.](http://adam.herokuapp.com/past/2010/4/13/rethinking_cron/) @@ -16,10 +16,12 @@ Create clock.rb: ```ruby require 'clockwork' +require 'active_support/time' # Allow numeric durations (eg: 1.minutes) + module Clockwork handler do |job| puts "Running #{job}" end @@ -56,12 +58,12 @@ Quickstart for Heroku --------------------- Clockwork fits well with heroku's cedar stack. -Consider to use [clockwork-init.sh](https://gist.github.com/1312172) to create -a new project for heroku. +Consider using [clockwork-init.sh](https://gist.github.com/tomykaira/1312172) to create +a new project for Heroku. Use with queueing ----------------- The clock process only makes sense as a place to schedule work to be done, not @@ -78,10 +80,11 @@ For example, if you're using Beanstalk/Stalker: ```ruby require 'stalker' +require 'active_support/time' module Clockwork handler { |job| Stalker.enqueue(job) } every(1.hour, 'feeds.refresh') @@ -148,30 +151,28 @@ ### Your Model Classes `ActiveRecord` models are a perfect candidate for the model class. Having said that, the only requirements are: - 1. the class responds to `all` returning an array of instances from the database +1. the class responds to `all` returning an array of instances from the database - 2. the instances returned respond to: +2. the instances returned respond to: + - `id` returning a unique identifier (this is needed to track changes to event settings) + - `frequency` returning the how frequently (in seconds) the database event should be run - - `id` returning a unique identifier (this is needed to track changes to event settings) + - `attributes` returning a hash of [attribute name] => [attribute value] values (or really anything that we can use store on registering the event, and then compare again to see if the state has changed later) - - `frequency` returning the how frequently (in seconds) the database event should be run + - `at` *(optional)* return any acceptable clockwork `:at` string - - `attributes` returning a hash of [attribute name] => [attribute value] values (or really anything that we can use store on registering the event, and then compare again to see if the state has changed later) + - `name` *(optional)* returning the name for the event (used to identify it in the Clockwork output) - - (optionally) `at` return any acceptable clockwork `:at` string + - `if?`*(optional)* returning either true or false, depending on whether the database event should run at the given time (this method will be passed the time as a parameter, much like the standard clockwork `:if`) - - (optionally) `name` returning the name for the event (used to identify it in the Clockwork output) + - `ignored_attributes` *(optional)* returning an array of model attributes (as symbols) to ignore when determining whether the database event has been modified since our last run - - (optionally) `if?` returning either true or false, depending on whether the database event should run at the given time (this method will be passed the time as a parameter, much like the standard clockwork `:if`) + - `tz` *(optional)* returning the timezone to use (default is the local timezone) - - (optionally) `ignored_attributes` returning an array of model attributes (as symbols) to ignore when determining whether the database event has been modified since our last run - - - (optionally) `tz` returning the timezone to use (default is the local timezone) - #### Example Setup Here's an example of one way of setting up your ActiveRecord models: ```ruby @@ -327,11 +328,12 @@ `:tz` parameter lets you specify a timezone (default is the local timezone): ```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/) +# The value for :tz can be anything supported by [TZInfo](https://github.com/tzinfo/tzinfo) +# Using the 'tzinfo' gem, run TZInfo::Timezone.all_identifiers to get a list of acceptable identifiers. ``` ### :if `:if` parameter is invoked every time the task is ready to run, and run if the @@ -341,11 +343,11 @@ ```ruby Clockwork.every(1.day, 'myjob', :if => lambda { |t| t.day == 1 }) ``` -The argument is an instance of `Time`. If the `:tz` option is set, it has the given time zone. Otherwise, the time zone is the system time zone. +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. ```ruby Clockwork.every(1.second, 'myjob', :if => lambda { |_| true }) @@ -557,9 +559,16 @@ ``` clockworkd -c YOUR_CLOCK.rb start ``` For more details, you can run `clockworkd -h`. + +Integration Testing +------------------- + +You could take a look at: +* [clockwork-mocks](https://github.com/dpoetzsch/clockwork-mocks) that helps with running scheduled tasks during integration testing. +* [clockwork-test](https://github.com/kevin-j-m/clockwork-test) which ensures that tasks are triggered at the right time Issues and Pull requests ------------------------ If you find a bug, please create an issue - [Issues ยท Rykian/clockwork](https://github.com/Rykian/clockwork/issues).