h1. Beanstalk Messaging Plugin for Rails

The Beanstalk Messaging Plugin provides a simple interface to the +beanstalkd+ queuing
process.

h2. Configuration

Copy beanstalk.example.yml from the plugin config folder to your Rails config folder 
and configure the queues that you need for your application. Use script/beanstalk to 
start/stop/restart your beanstalkd processes.

h2. Using the Beanstalk::QueueManager

Use the Beanstalk::QueueManager class to access your queues by name, using the 
Beanstalk::QueueManager#queue method. For example:

  queue_manager = BeanStalk::QueueManager.new("beanstalk-config.yml")
  my_queue = queue_manager.queue(:my_queue)
  my_queue << "Here's a message"

In your +environment.rb+ file, you should create a single instance of a Beanstalk::QueueManager 
using your +beanstalk.yml+ config as a global constant that you can use throughout your app. This 
will ensure that each request to QueueManager.queue returns the same Beanstalk::Queue 
instance. For example, you may wish to add the following to the bottom of +environment.rb+:

  QUEUE_MANAGER = Beanstalk::QueueManager.new(File.join(RAILS_ROOT, 'config', 'beanstalk.yml'))
  
You can disable queues globally by using the Beanstalk::QueueManager#disable method to temporarily 
disable the use of that particular queue. Beanstalk::QueueManager#disable_all disables all queues. 
When a queue is disabled, the Beanstalk::QueueManager will return a Beanstalk::NullQueue instead of an actual 
Beanstalk::Queue object which will handle any Beanstalk::Queue API calls silently:

<pre><code>
# In environment.rb
QUEUE_MANAGER.disable(:my_queue)

## Elsewhere in your application...
queue = QUEUE_MANAGER.queue(:my_queue)
100.times { queue << "In /dev/null, noone can hear you scream..." }
## Nothing actually gets sent to the beanstalkd process
</code></pre>

h2. Using Beanstalk::Queue

Use the Beanstalk::Queue API to push messages on to the queue and consume messages. This
amounts to using Beanstalk::Queue#push (or Beanstalk::Queue#<<) to add messages to the queue,
and Beanstalk::Queue#next_message to retrieve messages. Note that you do not need to
transform the data into YAML - this is performed automatically by the queue.

<pre><code>
queue << [1,2,3]
# => "---\n1\n2\n3" # YAML version ends up on the queue

queue.next_message
# => [1,2,3] # YAML deserialization is performed automatically
</code></pre>