README.md in backburner-0.2.0 vs README.md in backburner-0.2.5
- old
+ new
@@ -6,13 +6,16 @@
Processing background jobs reliably has never been easier than with beanstalkd and Backburner. This gem works with any ruby-based
web framework, but is especially suited for use with [Sinatra](http://sinatrarb.com), [Padrino](http://padrinorb.com) and Rails.
If you want to use beanstalk for your job processing, consider using Backburner.
Backburner is heavily inspired by Resque and DelayedJob. Backburner stores all jobs as simple JSON message payloads.
-Backburner can be a persistent queue when the beanstalk persistence mode is enabled.
-It supports multiple queues, priorities, delays, and timeouts.
+Persistent queues are supported when beanstalkd persistence mode is enabled.
+Backburner supports multiple queues, job priorities, delays, and timeouts. In addition,
+Backburner has robust support for retrying failed jobs, handling error cases,
+custom logging, and extensible plugin hooks.
+
## Why Backburner?
Backburner is well tested and has a familiar, no-nonsense approach to job processing, but that is of secondary importance.
Let's face it, there are a lot of options for background job processing. [DelayedJob](https://github.com/collectiveidea/delayed_job),
and [Resque](https://github.com/defunkt/resque) are the first that come to mind immediately. So, how do we make sense
@@ -81,24 +84,28 @@
Backburner is extremely simple to setup. Just configure basic settings for backburner:
```ruby
Backburner.configure do |config|
- config.beanstalk_url = ["beanstalk://127.0.0.1", "beanstalk://127.0.0.1:11301"]
+ config.beanstalk_url = ["beanstalk://127.0.0.1", "..."]
config.tube_namespace = "some.app.production"
config.on_error = lambda { |e| puts e }
config.max_job_retries = 3 # default 0 retries
config.retry_delay = 2 # default 5 seconds
config.default_priority = 65536
config.respond_timeout = 120
+ config.default_worker = Backburner::Workers::Simple
config.logger = Logger.new(STDOUT)
end
```
+The key options available are:
+
* The `beanstalk_url` supports a string such as 'beanstalk://127.0.0.1' or an array of addresses.
* The `tube_namespace` is the prefix used for all tubes related to this backburner queue.
* The `on_error` is a callback that gets invoked with the error whenever any job in the system fails.
+ * The `default_worker` is the processing worker that will be used if no other worker is specified.
* The `max_job_retries` determines how many times to retry a job before burying
* The `retry_delay` determines the base time to wait (in secs) between retries
* The `logger` is the logger object written to when backburner wants to report info or errors.
## Usage
@@ -201,10 +208,39 @@
bundle exec backburner newsletter-sender,push-message -d -P /var/run/backburner.pid -l /var/log/backburner.log
```
This will daemonize the worker and store the pid and logs automatically.
+### Processing Strategies
+
+In Backburner, there are actually multiple different strategies for processing jobs
+which are reflected by multiple workers.
+Custom workers can be [defined fairly easily](https://github.com/nesquena/backburner/wiki/Defining-Workers).
+By default, Backburner comes with the following workers built-in:
+
+| Worker | Description |
+| ------- | ------------------------------- |
+| `Backburner::Workers::Simple` | Single threaded, no forking worker. Simplest option. |
+
+You can select the default worker for processing with:
+
+```ruby
+Backburner.configure do |config|
+ config.default_worker = Backburner::Workers::Simple
+end
+```
+
+or determine the worker on the fly when invoking `work`:
+
+```ruby
+Backburner.work('newsletter_sender', :worker => Backburner::Workers::Threaded)
+```
+
+or when more official workers are supported, through alternate rake tasks.
+Additional workers such as `threaded`, `forking` and `threads_on_fork` will hopefully be
+developed in the future. If you are interested in helping, please let us know.
+
### Default Queues
Workers can be easily restricted to processing only a specific set of queues as shown above. However, if you want a worker to
process **all** queues instead, then you can leave the queue list blank.
@@ -235,10 +271,10 @@
Backburner is highly extensible and can be tailored to your needs by using various hooks that
can be triggered across the job processing lifecycle.
Often using hooks is much easier then trying to monkey patch the externals.
-Check out [HOOKS.md](HOOKS.md) for a detailed overview on using hooks.
+Check out [HOOKS.md](https://github.com/nesquena/backburner/blob/master/HOOKS.md) for a detailed overview on using hooks.
### Failures
When a job fails in backburner (usually because an exception was raised), the job will be released
and retried again (with progressive delays in between) until the `max_job_retries` configuration is reached.
\ No newline at end of file