README.md
# Delayed Job Groups
[][gem]
[][circleci]
[][codeclimate]
[][coveralls]
[gem]: https://rubygems.org/gems/delayed_job_groups_plugin
[circleci]: https://circleci.com/gh/salsify/delayed_job_groups_plugin
[codeclimate]: https://codeclimate.com/github/salsify/delayed_job_groups_plugin
[coveralls]: https://coveralls.io/r/salsify/delayed_job_groups_plugin
A [Delayed Job](https://github.com/collectiveidea/delayed_job) plugin that adds job groups supporting:
* Canceling all jobs in a job group
* Canceling the job group when a job in the job group fails
* Blocking and unblocking all jobs in a job group
* Running additional processing after all jobs in a job group complete or a job group fails
## Installation
Add this line to your application's Gemfile:
gem 'delayed_job_groups_plugin'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install delayed_job_groups_plugin
Run the required database migrations:
$ rails generate delayed_job_groups_plugin:install
$ rake db:migrate
## Upgrading from 0.1.2
run the following generator to create a migration for the new configuration column.
$ rails generate migration add_failure_cancels_group_to_delayed_job_groups failure_cancels_group:boolean
# add `default: true, null: false` to the generated migration for the failure_cancels_group column
$ rake db:migrate
## Usage
Creating a job group and queueing some jobs:
```ruby
job_group = Delayed::JobGroups::JobGroup.create!
# JobGroup#enqueue has the same signature as Delayed::Job.enqueue
# i.e. it takes a job and an optional hash of options.
job_group.enqueue(MyJob.new('some arg'), queue: 'general')
job_group.enqueue(MyJob.new('some other arg'), queue: 'general', priority: 10)
# Tell the JobGroup we're done queueing jobs
job_group.mark_queueing_complete
```
Registering a job to run after all jobs in the job group have completed:
```ruby
# We can optionally pass options that will be used when queueing the on completion job
job_group = Delayed::JobGroups::JobGroup.create!(on_completion_job: MyCompletionJob.new,
on_completion_job_options: { queue: 'general' })
```
Registering a job to run if the job group is canceled or fails:
```ruby
# We can optionally pass options that will be used when queueing the on cancellation job
job_group = Delayed::JobGroups::JobGroup.create!(on_cancellation_job: MyCancellationJob.new,
on_cancellation_job_options: { queue: 'general' })
```
Block and unblock jobs in a job group:
```ruby
# Construct the JobGroup in a blocked state
job_group = Delayed::JobGroups::JobGroup.create!(blocked: true)
job_group.enqueue(MyJob.new('some arg'), queue: 'general')
job_group.mark_queueing_complete
# Do more stuff...
# Unblock the JobGroup so its jobs can run
job_group.unblock
```
Cancel a job group:
```ruby
job_group = Delayed::JobGroups::JobGroup.create!
# Do more stuff...
job_group.cancel
```
Configuration to allow failed jobs not to cancel the group
```ruby
# We can optionally pass options that will allow jobs to fail without cancelling the group.
# This also allows the on_completion job to fire once all jobs have either succeeded or failed.
job_group = Delayed::JobGroups::JobGroup.create!(failure_cancels_group: false)
```
### Maintenance
It's possible to end up in a state where all jobs in a group have been completed, but the completion job has not run.
This is due a race condition where the final job in a group is completed, and the worker running it is terminated before
the completion job can be enqueued.
As a remedy for the above scenario, a job is provided which cleans up any job groups in this state. It is recommended to
run this job periodically (for example in a cron job), especially in high-thoughput applications.
```ruby
Delayed::JobGroups::CompleteStuckJobGroupsJob.enqueue
```
## Supported Platforms
* Only the Delayed Job Active Record backend is supported.
* Tested with Rails 4.2 through 5.2.
* Tested with MRI 2.3 through 2.5.
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request