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.

This library was tested primarily with RabbitMQ, although it should be compatible with any server implementing the AMQP 0-8 spec.

This fork of AMQP

Intention is to describe AMQP lib behavior using RSpec, with reasonable level of completeness. Given a solid spec suite, it will be easier to expand the library going forward.

Some improvements that are currently merged in, but not yet fully specified:

  • Support for setting extended headers in MQ::Exchange#publish. Particularly useful for :reply_to for RPC.
  • Multibyte character support (Ruby 1.9) in MQ::Exchange#publish.
  • MQ::Exchange#publish raises error if no connection to broker.
  • MQ::Queue only wraps headers with new MQ::Headers if they are not nil. This allows pops to tell more easily when they've requested a message from an empty queue. See (https://github.com/tmm1/amqp/issues#issue/22)
  • Support for receiving Headers with zero-size data packets. Such contents with no body frames are totally legit if indicated header size is zero.

Some improvements that are planned:

Getting started

First things first, start with:

$ gem install arvicco-amqp

To use examples with RabbitMQ, first install the broker.

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, you are set: Thin uses EventMachine under the hook.

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.

Same separate thread technique can be used to make EventMachine play nicely with other libraries that would block current thread (like File::Tail).

AMQP gem resources

Running specifications suite

To run the test suite make sure you have Rspec2 gem installed and run:

rake spec

The lib/amqp/spec.rb file is generated automatically based on the AMQP specification. To generate it:

rake codegen

Writing your own AMQP/evented specs

Writing evented specs properly is a bit difficult due to gory details of event loop management. Libraries such as AMQP-Spec and Moqueue may be helpful.

Credits and more information

(c) 2008—2010 Aman Gupta (tmm1)

This project was inspired by py-amqplib, rabbitmq, qpid and rubbyt. Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.

AMQP brokers

  • RabbitMQ (Rabbit Technologies, Erlang/OTP, MPL)
  • ZeroMQ (iMatix/FastMQ/Intel, C++, GPL3)
  • OpenAMQ (iMatix, C, GPL2)
  • ActiveMQ (Apache Foundation, Java, Apache2)

AMQP resources

Messaging and distributed systems resources