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