README.md in bbqueue-0.0.1 vs README.md in bbqueue-0.0.2
- old
+ new
@@ -1,24 +1,25 @@
# BBQueue
[![Build Status](https://secure.travis-ci.org/mrkamel/bbqueue.png?branch=master)](http://travis-ci.org/mrkamel/bbqueue)
[![Code Quality](https://codeclimate.com/github/mrkamel/bbqueue.png)](https://codeclimate.com/github/mrkamel/bbqueue)
+[![Gem Version](https://badge.fury.io/rb/bbqueue.svg)](http://badge.fury.io/rb/bbqueue)
[![Still Maintained](http://stillmaintained.com/mrkamel/bbqueue.png)](http://stillmaintained.com/mrkamel/bbqueue)
[![Dependency Status](https://gemnasium.com/mrkamel/bbqueue.png?travis)](https://gemnasium.com/mrkamel/bbqueue)
BBQueue is an opinionated ruby gem to queue and process background jobs. Other
-gems for this purpose usually don't work with ruby objects and serialize only
-method arguments. Instead, BBQueue jobs are simple ruby objects:
+gems for this purpose usually don't work with ruby objects and serialize method
+arguments only. Instead, BBQueue jobs are simple ruby objects:
```ruby
MyQueue.enqueue MyJob.new
```
BBQueue jobs need to fulfill the following interface:
1. The object contains an instance method `#work` without any arguments
-2. The object must be serializable via `Marshal.dump` and `Marshal.load`
+2. The object (instance) must be serializable via `Marshal.dump` and `Marshal.load`
## Installation
Add this line to your application's Gemfile:
@@ -34,12 +35,13 @@
$ gem install bbqueue
## Usage
-BBQueue is currently built on top of the `stalking` gem. Therefore, you have to
-install beanstalkd.
+BBQueue is currently built on top of the
+[stalking](https://github.com/mrkamel/stalking) gem. Therefore, you have to
+install [beanstalkd](http://kr.github.io/beanstalkd/).
### Producer
To enqueue a job, first create a queue, aka Producer:
@@ -84,24 +86,23 @@
### Consumer
To process the enqueued jobs, create a file, e.g. jobs.rb:
```ruby
-require "bbqueue"
-
BBQueue::Consumer.new "default"
```
and run it via:
$ bbqueue jobs.rb
BBQueue will loop through all the jobs, run them, and will then wait for new
-ones. You can pass multiple queue names and `stalking`-specific options:
+ones (no polling). You can pass multiple queue names and `stalking`-specific
+options:
```ruby
-BBQueue.new ["default", "important"], :logger => ..., :servers => ...
+BBQueue::Consumer.new ["default", "important"], :logger => ..., :servers => ...
```
By using a separate file like `jobs.rb`, you can load your environment or do
other fancy things before finally calling `BBQueue::Consumer.new`. You can e.g.
load your rails environment:
@@ -114,17 +115,46 @@
SomeLogger.info "jobs booted into #{Rails.env.inspect} environment"
BBQueue::Consumer.new "background", :logger => SomeLogger
```
+### Forking Consumers
+
+By default, BBQueue does not fork a process for every job, but
+it already ships with the ability to do so.
+
+To make BBQueue fork, create a custom consumer:
+
+```ruby
+class ForkingConsumer < BBQueue::Consumer
+ def fork?
+ true
+ end
+
+ def before_fork
+ # ...
+ end
+
+ def after_fork
+ # ...
+ end
+end
+```
+
+Then, start your custom consumer in favor of BBQueue's default one:
+
+```ruby
+ForkingConsumer.new ["queue1", "queue2", ...], ...
+```
+
## Graceful Termination
Like for the `stalking` gem, you can stop a worker gracefully by sending a QUIT
signal to it. The worker will finish its current job and terminate afterwards.
## Contributing
-1. Fork it ( https://github.com/[my-github-username]/bbqueue/fork )
+1. Fork it ( https://github.com/mrkamel/bbqueue/fork )
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 a new Pull Request