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

- old
+ new

@@ -140,13 +140,13 @@ [other events if you have] end ``` -This tells clockwork to fetch all `ClockworkDatabaseEvent` instances from the database, and create an internal clockwork event for each one. Each clockwork event will be configured based on the instance's `frequency` and, optionally, its `at`, `name`, `if?` and `tz` methods. The code above also says to reload the events from the database every `1.minute`; we need pick up any changes in the database frequently (choose a sensible reload frequency by changing the `every:` option). +This tells clockwork to fetch all `ClockworkDatabaseEvent` instances from the database, and create an internal clockwork event for each one. Each clockwork event will be configured based on the instance's `frequency` and, optionally, its `at`, `if?`, `ignored_attributes`, `name`, and, `tz` methods. The code above also says to reload the events from the database every `1.minute`; we need pick up any changes in the database frequently (choose a sensible reload frequency by changing the `every:` option). -When one of the events is ready to be run (based on it's `frequency`, and possible `at`, `if?` and `tz` methods), clockwork arranges for the block passed to `sync_database_events` to be run. The above example shows how you could use either DelayedJob or Sidekiq to kick off a worker job. This approach is good because the ideal is to use clockwork as a simple scheduler, and avoid making it carry out any long-running tasks. +When one of the events is ready to be run (based on it's `frequency`, and possible `at`, `if?`, `ignored attributes`, and `tz` methods), clockwork arranges for the block passed to `sync_database_events` to be run. The above example shows how you could use either DelayedJob or Sidekiq to kick off a worker job. This approach is good because the ideal is to use clockwork as a simple scheduler, and avoid making it carry out any long-running tasks. ### Your Model Classes `ActiveRecord` models are a perfect candidate for the model class. Having said that, the only requirements are: @@ -164,10 +164,12 @@ - (optionally) `name` returning the name for the event (used to identify it in the Clockwork output) - (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`) + - (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: @@ -243,11 +245,33 @@ ... end ``` +#### Example use of `ignored_attributes` +Clockwork compares all attributes of the model between runs to determine if the model has changed, and if it has, it runs the event if all other conditions are met. + +However, in certain cases, you may want to store additional attributes in your model that you don't want to affect whether a database event is executed prior to its next interval. + +So for example, you may update an attribute of your model named `last_scheduled_at` on each run to track the last time it was successfully scheduled. You can tell Clockwork to ignore that attribute in its comparison as follows: + +```ruby +# app/models/clockwork_database_event.rb +class ClockworkDatabaseEvent < ActiveRecord::Base + + ... + + def ignored_attributes + [ :last_scheduled_at ] + end + + ... +end +``` + + Event Parameters ---------- ### :at @@ -317,11 +341,11 @@ ```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`. +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. This argument cannot be omitted. Please use _ as placeholder if not needed. ```ruby Clockwork.every(1.second, 'myjob', :if => lambda { |_| true }) @@ -339,10 +363,23 @@ Clockwork.every(1.day, 'run.me.in.new.thread', :thread => true) ``` If a job is long-running or IO-intensive, this option helps keep the clock precise. +### :skip_first_run + +Normally, a clockwork process that is defined to run in a specified period will run at startup. +This is sometimes undesired behaviour, if the action being run relies on other processes booting which may be slower than clock. +To avoid this problem, `:skip_first_run` can be used. + +```ruby +Clockwork.every(5.minutes, 'myjob', :skip_first_run => true) +``` + +The above job will not run at initial boot, and instead run every 5 minutes after boot. + + Configuration ----------------------- Clockwork exposes a couple of configuration options: @@ -355,11 +392,10 @@ Clockwork wakes up once a second and performs its duties. To change the number of seconds Clockwork sleeps, set the `sleep_timeout` configuration option as shown below in the example. From 1.1.0, Clockwork does not accept `sleep_timeout` less than 1 seconds. -This restriction is introduced to solve more severe bug [#135](https://github.com/tomykaira/clockwork/pull/135). ### :tz This is the default timezone to use for all events. When not specified this defaults to the local timezone. Specifying :tz in the parameters for an event overrides anything set here. @@ -525,11 +561,11 @@ For more details, you can run `clockworkd -h`. Issues and Pull requests ------------------------ -If you find a bug, please create an issue - [Issues · tomykaira/clockwork](https://github.com/tomykaira/clockwork/issues). +If you find a bug, please create an issue - [Issues · Rykian/clockwork](https://github.com/Rykian/clockwork/issues). For a bug fix or a feature request, please send a pull-request. Do not forget to add tests to show how your feature works, or what bug is fixed. All existing tests and new tests must pass (TravisCI is watching). @@ -541,12 +577,12 @@ Use cases --------- Feel free to add your idea or experience and send a pull-request. -- [Sending errors to Airbrake](https://github.com/tomykaira/clockwork/issues/58) -- [Read events from a database](https://github.com/tomykaira/clockwork/issues/25) +- Sending errors to Airbrake +- Read events from a database Meta ---- Created by Adam Wiggins @@ -557,6 +593,6 @@ Patches contributed by Mark McGranaghan and Lukáš Konarovský Released under the MIT License: http://www.opensource.org/licenses/mit-license.php -http://github.com/tomykaira/clockwork +https://github.com/Rykian/clockwork