amqp gem is a simple asynchronous Ruby AMQP client built on top of EventMachine.
This library works with Ruby 1.8.7, Ruby 1.9.2, JRuby and Rubinius, and is
licensed under the Ruby License.
Version 0.8.0 and later of amqp gem implement AMQP 0.9.1.
AMQP is an open standard for messaging middleware that
emphasizes interoperability between different technologies (for example, Java, .NET,
Ruby, Python, C and so on).
Key features of AMQP are very flexible yet simple routing and binary protocol
efficiency.
One can use amqp gem to make Ruby applications interoperate with other
applications (both Ruby and not). Complexity and size may vary from
simple work queues to complex multi-stage data processing workflows that involve
dozens or hundreds of applications built with all kinds of technologies.
Specific examples:
- A Web application may route messages to a Java app that works
with SMS delivery gateways.
- Periodically run (Cron-driven) application may notify other systems that
there are some new results.
- Content aggregators may update full-text search and geospatial search indexes
by delegating actual indexing work to other applications over AMQP.
- Companies may provide “Firehose-like” push APIs to their customers, partners
or just general public.
- A new shiny Ruby-based system may be integrated with an existing C++-based component
using AMQP.
- An application that watches updates from a real-time stream (be it markets data
or Twitter stream) can propagate updates to interested parties, including
Web applications that display that information in the real time.
Please refer to RabbitMQ installation guide
gem install amqp
#!/usr/bin/env ruby
# encoding: utf-8
#!/usr/bin/env ruby
# encoding: utf-8
require "rubygems"
require 'amqp'
EventMachine.run do
AMQP.connect(:host => 'localhost') do |connection|
puts "Connected to AMQP broker"
channel = AMQP::Channel.new(connection)
queue = channel.queue("amqpgem.examples.hello_world")
exchange = channel.default_exchange
queue.subscribe do |payload|
puts "Received a message: #{payload}. Disconnecting..."
connection.close {
EM.stop { exit }
}
end
exchange.publish "Hello, world!", :routing_key => queue.name
end
end
(see as a Gist)
To use AMQP gem from web applications, you would need to have EventMachine reactor running.
If you use [Thin](http://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_connection = 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, Goliath 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.
Same separate thread technique can be used to make EventMachine play nicely with other
libraries that would block current thread (like File::Tail).
With Bundler, add this line to your Gemfile:
gem "amqp"
If you want to use edge version (usually there is no need to):
gem "amqp", :git => "git://github.com/ruby-amqp/amqp.git", :branch => "master"
You can find many examples (both real-world cases and simple demonstrations)
under examples directory in the repository.
See this page about AMQP gems family
- RabbitMQ tutorials that demonstrate interoperability
- Wikipedia page on AMQP
- AMQP quick reference
- John O’Hara on the history of AMQP
- Enterprise Integration Patterns, a book about messaging and use of messaging in systems integration.
- A Critique of the Remote Procedure Call Paradigm
- A Note on Distributed Computing
- Convenience Over Correctness
- Joe Armstrong on Erlang messaging vs RPC
- Ruby AMQP mailing list
- RabbitMQ mailing list (AMQP community epicenter).
- Jabber room for contributors
AMQP gem is licensed under the “Ruby License:”http://www.ruby-lang.org/en/LICENSE.txt.
- The Original Code is tmm1/amqp.
- The Initial Developer of the Original Code is Aman Gupta.
- Copyright © 2008 – 2010 Aman Gupta.
- Contributions from Jakub Stastny are Copyright © 2011 VMware, Inc.
- Copyright © 2010 — 2011 ruby-amqp group members.
Currently maintained by ruby-amqp group members
Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.
This library was tested primarily with RabbitMQ, although it should be compatible with any
server implementing the AMQP 0.9.1 spec. For AMQP 0.8.0 brokers,
use version 0.7.