README.md in activejob-scheduler-0.0.1 vs README.md in activejob-scheduler-1.0.0.pre
- old
+ new
@@ -1,90 +1,179 @@
# ActiveJob::Scheduler
+[](http://badge.fury.io/rb/activejob-scheduler)
+[](https://travis-ci.org/tubbo/activejob-scheduler)
+[](https://codeclimate.com/github/tubbo/activejob-scheduler/maintainability)
+[](https://codeclimate.com/github/tubbo/activejob-scheduler/test_coverage)
+
An extension to [ActiveJob][aj] for running background jobs
periodically, according to a schedule. Inspired by its predecessors,
[resque-scheduler][resque] and [sidekiq-scheduler][sidekiq],
`ActiveJob::Scheduler` hopes to bring the power of scheduled jobs into
everyone's hands, by way of the pre-defined ActiveJob API which most
popular queueing backend choices already support.
-Like its predecessors, `ActiveJob::Scheduler` is built with
-[Rufus::Scheduler][rufus], an immensely powerful task scheduling library
-to make sure your jobs get kicked off at *exactly* the right time.
+Like its predecessors, `ActiveJob::Scheduler` uses the same powerful
+syntax for describing when periodic jobs should run as
+[Rufus::Scheduler][rufus]. However, unlike its predecessors,
+`ActiveJob::Scheduler` does not require a separate process to be run.
+Instead, it uses an `after_perform` callback to re-enqueue the job after
+it has been performed.
## Installation
Add this line to your application's Gemfile:
- gem 'activejob-scheduler'
+```ruby
+gem 'activejob-scheduler'
+```
And then execute:
$ bundle
+Or install it yourself as:
+
+ $ gem install activejob-scheduler
+
## Usage
-Run the following command to generate a YAML-based schedule:
+To schedule your jobs, add the `repeat` macro to the job definition:
-```bash
-$ rails generate activejob:schedule
+```ruby
+class GenerateSitemapsJob < ApplicationJob
+ repeat 'every day at 2am'
+
+ def perform
+ SitemapGenerator.generate
+ end
+end
```
-Edit this YAML file the same way you would with resque-scheduler or
-sidekiq-scheduler (they define the same parameters). Then, it's your
-choice as to how you wish to run it, either by the binary:
+This macro can also be used to configure the job event, like its name or
+arguments:
+```ruby
+class GenerateSitemapsJob < ApplicationJob
+ repeat every: '1d', name: 'Sitemap Generator', arguments: %w(foo bar)
+
+ def perform(foo, bar)
+ SitemapGenerator.generate(foo, bar) # => foo == "foo", bar == "bar"
+ end
+end
+```
+
+The DSL also allows you to iterate over a collection and pass in a
+different argument for each item:
+
+```ruby
+class SyncOrdersJob < ApplicationJob
+ repeat 'every day at 11:30am', each: -> { Order.not_synced }
+
+ def perform(order)
+ ExternalSystem.create(order)
+ end
+end
+```
+
+This will trigger the event every day at 11:30am, but enqueue a job for
+each model in the collection, and pass it into the job arguments. You
+can specify static arguments here as well, they will be passed in prior
+to the item argument at the end.
+
+```ruby
+class SyncOrdersJob < ApplicationJob
+ repeat 'every day at 11:30am',
+ arguments: ['synced'],
+ each: -> { Order.not_synced }
+
+ def perform(type, order)
+ ExternalSystem.create(type: type, order: order) # type is "synced"
+ end
+end
+```
+
+Start the schedule by running this command:
+
```bash
-$ bundle exec ajs
+./bin/rails activejob:schedule
```
-Or, with a Rake task:
+### YAML Schedule
+Much like **resque-scheduler**, you can use a YAML schedule file with
+**activejob-scheduler** with a very similar syntax. To generate a new
+one, run:
+
```bash
-$ bundle exec rake activejob:schedule
+$ rails generate activejob:schedule
```
-The schedule must run as a separate process, but it's very light...it
-delegates all the real processing to your queue workers, and simply
-enqueues jobs as the specified time rolls around.
+Then, add your jobs into the YAML like so:
-## Development
+```yaml
+generate_sitemaps:
+ interval:
+ every: '1d'
+```
-Please use GitHub pull requests to contribute bug fixes or features, and
-make sure to include tests with all your work.
+This is entirely optional, however, and both DSL-based jobs and
+YAML-based jobs will be included in the schedule at runtime.
-### License
+### Mailers
-[University of Illinois/NCSA Open Source License][license]
+```ruby
+class AdminMailer < ApplicationMailer
+ repeat :daily_status, 'every day at 8am'
+ def daily_status
+ mail to: User.admins.pluck(:email)
+ end
+end
+```
- Copyright (c) 2014 Tom Scott
- All rights reserved.
+This will send the email every day at **8:00am**. You can also pass all
+the regular fields from `repeat` in the job DSL like arguments and the
+various fugit-parsed intervals.
- Permission is hereby granted, free of charge, to any person obtaining
- a copy of this software and associated documentation files (the "Software"),
- to deal with the Software without restriction, including without limitation
- the rights to use, copy, modify, merge, publish, distribute, sublicense,
- and/or sell copies of the Software, and to permit persons to whom the
- Software is furnished to do so, subject to the following conditions:
+You can also send a different email for each recipient:
- Redistributions of source code must retain the above copyright notice,
- this list of conditions and the following disclaimers.
+```ruby
+class UserMailer < ApplicationMailer
+ repeat :status, 'every day at 8am', each: -> { User.receive_email }
+ def status(user)
+ end
+end
+```
- Redistributions in binary form must reproduce the above copyright notice,
- this list of conditions and the following disclaimers in the documentation
- and/or other materials provided with the distribution.
+This lambda will be called when the event is enqueued, and individual
+mails will be sent out for each user in the collection.
- None of the names of its contributors may be used to endorse or promote
- products derived from this Software without specific prior written permission.
+## Development
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
- PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
- OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
- DEALINGS WITH THE SOFTWARE.
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake rspec` to run the tests. You can also run `bin/console`
+for an interactive prompt that will allow you to experiment.
-[aj]: https://github.com/rails/activejob
+To install this gem onto your local machine, run `bin/rake install`. To
+release a new version, update the version number in `version.rb`, and
+then run `bin/rake release`, which will create a git tag for the version,
+push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/tubbo/activejob-scheduler. This project is intended
+to be a safe, welcoming space for collaboration, and contributors
+are expected to adhere to the
+[Contributor Covenant](contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License][mit].
+
+[aj]: https://github.com/rails/rails/tree/master/activejob
[resque]: https://github.com/resque/resque-scheduler
[sidekiq]: https://github.com/Moove-it/sidekiq-scheduler
[rufus]: https://github.com/jmettraux/rufus-scheduler
-[license]: http://opensource.org/licenses/NCSA
+[mit]: http://opensource.org/licenses/MIT