README.md

Path: README.md
Last Update: Sat Dec 03 15:46:43 +0000 2011

What AMQP gem is

=============

Simple asynchronous AMQP driver for Ruby/EventMachine This library works with Ruby 1.8, Ruby 1.9, JRuby and Rubinius, and is licensed under [the Ruby License](www.ruby-lang.org/en/LICENSE.txt).

This library was tested primarily with RabbitMQ, although it should be compatible with any server implementing the [AMQP 0-8 spec](www.amqp.org/confluence/download/attachments/720900/amqp0-8.pdf).

Getting started

=========

To use examples with RabbitMQ, first [install the broker](www.rabbitmq.com/install.html). If you have Mercurial and Erlang/OTP installed, here is how to do it in 4 lines:

    hg clone http://hg.rabbitmq.com/rabbitmq-codegen
    hg clone http://hg.rabbitmq.com/rabbitmq-server
    cd rabbitmq-server
    make run

Then have a look at the various bundled examples:

    ruby examples/mq/pingpong.rb   # 1-1 communication using amq.direct
    ruby examples/mq/clock.rb      # 1-N communication using amq.fanout
    ruby examples/mq/stocks.rb     # 1-subscriber communication using amq.topic

    ruby examples/mq/multiclock.rb # header based routing (new rabbitmq feature)
    ruby examples/mq/ack.rb        # using ack
    ruby examples/mq/pop.rb        # pop off messages one at a time

    ruby examples/mq/hashtable.rb  # simple async rpc layer
    ruby examples/mq/primes.rb 4   # parallelized prime number generation
    ruby examples/mq/logger.rb     # simple logging api

For high level API documentation see MQ class. For more details into the lower level AMQP client API, run the simple client example:

    ruby examples/amqp/simple.rb   # low-level AMQP api
    ruby examples/mq/internal.rb   # low-level Queue/Exchange api

Or refer to protocol/doc.txt, which enumerates packets sent between a server and client during a typical session, in both binary and decoded formats.

How to use AMQP gem with Ruby on Rails, Merb, Sinatra and other web frameworks

========================================================================

To use AMQP gem from web applications, you would need to have EventMachine reactor running. If you use [Thin](code.macournoyer.com/thin/), you are all set: Thin uses EventMachine under the hood.

With other web servers, you need to start EventMachine reactor in it‘s own thread like this:

    Thread.new { EM.run }

because otherwise EventMachine will block current thread. Then connect to AMQP broker:

    AMQP.connect(:host => "localhost", :user => "guest", :pass => "guest", :vhost => "/")

In a Ruby on Rails app, probably the best place for this code is initializer (like config/initializers/amqp.rb). For Merb apps, it is config/init.rb. For Sinatra and pure Rack applications, place it next to other configuration code.

If you want to integrate AMQP with Thin or another EventMachine-based software which already runs an event loop, you might want to use following code:

    EM.next_tick { AMQP.connect(...) }

So in case the reactor isn‘t running yet (which seems to be the case with Ruby on Rails 3.x and Thin combination), it won‘t fail, but wait when the reactor is started (see [issue 21](github.com/tmm1/amqp/issues/21)).

Same separate thread technique can be used to make EventMachine play nicely with other libraries that would block current thread (like [File::Tail](rubygems.org/gems/file-tail)).

Links

========================

Contributions

======================

All the dependencies are specified in Gemfile, so if you have [Bundler](gembundler.com), you can just run bundle install.

The lib/amqp/spec.rb file is generated automatically based on the [AMQP specification](www.amqp.org/confluence/display/AMQP/AMQP+Specification). To generate it:

    rake codegen

For running specs, use rake spec.

Credits and more information

======================
  • The Original Code is tmm1/amqp.
  • The Initial Developer of the Original Code is Aman Gupta.
  • Copyright (c) 2008 - 2010 [Aman Gupta](github.com/tmm1) (tmm1).
  • Contributions from Jakub Stastny are Copyright (c) 2011 VMware, Inc.

Current maintainer: [Jakub Stastny](github.com/botanicus) aka [botanicus](twitter.com/botanicus).

This project was inspired by [py-amqplib](barryp.org/software/py-amqplib/), [rabbitmq](rabbitmq.com), [qpid](qpid.apache.org/) and [rubbyt](github.com/rubbyt/rubbyt). Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.

AMQP brokers

[Validate]