amqp 0.8.0.rc12 → 0.8.0.rc13

data/.travis.yml

@@ -1,10 +1,10 @@
 script: "bundle exec rake spec:ci"
 rvm:
   - 1.8.7
+  - rbx
   - 1.9.2
   - ree
   - jruby
-  - rbx
 gemfile:
   - Gemfile
   - gemfiles/eventmachine-pre

data/.yardopts

@@ -1,7 +1,8 @@
 --no-private
 --protected
 --markup="textile" lib/**/*.rb
---main README.textile
+--main README.md
+--asset docs:docs --asset examples:examples
 -
 LICENSE
 CHANGELOG

data/CONTRIBUTORS

@@ -1,22 +1,29 @@
-Aman Gupta: 232
-Jakub Šťastný aka Botanicus: 57
-arvicco: 26
-Michael S. Klishin: 17
-Chuck Remes: 7
-Marek Majkowski: 4
-Chris Van Pelt: 3
-Jake Douglas: 3
-Doug Barth: 2
-coderrr: 2
-binary42: 1
-Daniel Neighman: 1
-Brendan Ribera: 1
-dan: 1
-Dane Jensen: 1
-Tony Garnock-Jones: 1
-Phil Smith: 1
-Kasper Bjørn Nielsen: 1
-Simon Horne: 1
-Cliff Moon: 1
-Coda Hale: 1
-John Richmond: 1
+   557	Michael S. Klishin
+   232	Aman Gupta
+    98	Jakub Šťastný aka Botanicus
+    43	Jakub Stastny aka botanicus
+    26	arvicco
+    24	Mark Abramov
+     7	Chuck Remes
+     4	Marek Majkowski
+     4	David Wragg
+     3	Chris Van Pelt
+     3	Jake Douglas
+     2	Yuri Leikind
+     2	coderrr
+     2	Doug Barth
+     1	binary42
+     1	dan
+     1	Brendan Ribera
+     1	Cliff Moon
+     1	Coda Hale
+     1	Dane Jensen
+     1	Daniel Neighman
+     1	John Richmond
+     1	Jonathan Bryant
+     1	Jordan Ritter
+     1	Kasper Bjørn Nielsen
+     1	Michael
+     1	Phil Smith
+     1	Simon Horne
+     1	Tony Garnock-Jones

data/Gemfile

@@ -19,9 +19,10 @@ custom_gem "amq-client",   :git => "git://github.com/ruby-amqp/amq-client.git",
 custom_gem "amq-protocol", :git => "git://github.com/ruby-amqp/amq-protocol.git", :branch => "master"
 
 group(:development) do
-  gem "yard", ">= 0.7.0"
+  gem "yard", ">= 0.7.1"
   # yard tags this buddy along
   gem "RedCloth"
+  gem "rdiscount"
 
   custom_gem "nake",         :platform => :ruby_19
   custom_gem "contributors", :platform => :ruby_19

data/README.md

@@ -0,0 +1,241 @@
+# About Ruby amqp gem #
+
+Ruby amqp gem is a widely used, feature-rich, well-maintained asynchronous AMQP 0.9.1 client with batteries included.
+This library works with Ruby 1.8.7 (p174 and p334), Ruby 1.9.2, [JRuby](http://jruby.org) (highly recommended to Microsoft Windows users), [REE](http://www.rubyenterpriseedition.com) and [Rubinius](http://rubini.us), and is licensed under the [Ruby License](http://www.ruby-lang.org/en/LICENSE.txt)
+
+Versions 0.8.0 and later of amqp gem implement [AMQP 0.9.1](http://bit.ly/hw2ELX) and supports [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
+
+[![Continuous Integration status](http://travis-ci.org/ruby-amqp/amqp.png)](http://travis-ci.org/ruby-amqp/amqp)
+
+
+## I know what AMQP is, how do I get started? ##
+
+See [Getting started with amqp gem](http://bit.ly/getting-started-with-amqp-ruby-gem) and other [documentation guides](http://bit.ly/amqp-gem-docs).
+
+
+
+## What is AMQP? ##
+
+AMQP is an [open standard for messaging middleware](http://www.amqp.org/confluence/display/AMQP/About+AMQP) that
+emphasizes interoperability between different technologies (for example, Java, .NET, Ruby, Python, Node.js, Erlang, C and so on).
+
+Key features of AMQP are very flexible yet simple routing and binary protocol efficiency. AMQP supports many sophisticated features, for example,
+message acknowledgements, returning messages to producer, delivery confirmation, flow control and so on.
+
+
+## What is amqp gem good for? ##
+
+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 streaming/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.
+
+
+
+## Getting started with Ruby amqp gem ##
+
+### Install RabbitMQ ###
+
+Please refer to the [RabbitMQ installation guide](http://www.rabbitmq.com/install.html). Note that for Ubuntu and Debian we strongly advice that you
+use [RabbitMQ apt repository](http://www.rabbitmq.com/debian.html#apt) that has recent versions of RabbitMQ. RabbitMQ packages Ubuntu and Debian ship
+with are outdated even in recent (10.10) releases. Learn more in the [RabbitMQ versions guide](http://rubydoc.info/github/ruby-amqp/amqp/master/file/docs/RabbitMQVersions.textile).
+
+
+### Install the gem ###
+
+On Microsoft Windows 7
+
+    gem install eventmachine --pre
+    gem install amqp --pre --version "~> 0.8.0.RC12"
+
+On other OSes or [JRuby](http://jruby.org):
+
+    gem install amqp --pre --version "~> 0.8.0.RC12"
+
+
+### "Hello, World" example ###
+
+    #!/usr/bin/env ruby
+    # encoding: utf-8
+
+    require "rubygems"
+    # or
+    #
+    # require "bundler"
+    # Bundler.setup
+    #
+    # if you use Bundler
+
+    require 'amqp'
+
+    EventMachine.run do
+      connection = AMQP.connect(:host => '127.0.0.1')
+      puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
+
+      channel  = AMQP::Channel.new(connection)
+      queue    = channel.queue("amqpgem.examples.hello_world", :auto_delete => true)
+      exchange = channel.direct("")
+
+      queue.subscribe do |payload|
+        puts "Received a message: #{payload}. Disconnecting..."
+
+        connection.close {
+          EventMachine.stop { exit }
+        }
+      end
+
+      exchange.publish "Hello, world!", :routing_key => queue.name
+    end
+
+
+[Getting started guide](http://bit.ly/getting-started-with-amqp-ruby-gem) explains this and two more examples in detail,
+and is written in a form of a tutorial.
+
+
+
+## Documentation: tutorials, guides & API reference ##
+
+We believe that in order to be a library our users **really** love, we need to care about documentation as much as (or more)
+code readability, API beauty and autotomated testing across 5 Ruby implementations on multiple operating systems. We do care
+about our documentation: **if you don't find your answer in documentation, we consider it a high severity bug** that you
+should [file to us](http://github.com/ruby-amqp/amqp/issues). Or just complain to [@rubyamqp](https://twitter.com/rubyamqp) on Twitter.
+
+
+### Tutorials ###
+
+[Getting started guide](http://bit.ly/getting-started-with-amqp-ruby-gem) is written as a tutorial that walks you through
+3 examples:
+
+ * The "Hello, world" of messaging, 1-to-1 communication
+ * Blabbr, a Twitter-like example of broadcasting (1-to-many communication)
+ * Weathr, an example of sophisticated routing capabilities AMQP 0.9.1 has to offer (1-to-many or many-to-many communication)
+
+all in under 20 minutes. Check it out! If something isn't clear, every guide explains how to contact documentation authors at the bottom
+of the page.
+
+
+### Examples ###
+
+You can find many examples (both real-world cases and simple demonstrations) under [examples directory](https://github.com/ruby-amqp/amqp/tree/master/examples) in the repository.
+Note that those examples are written against version 0.8.0.rc1 and later. 0.6.x and 0.7.x may not support certain AMQP protocol or "DSL syntax" features.
+
+
+### Documentation guides ###
+
+[Documentation guides](http://bit.ly/amqp-gem-docs) describe the library itself as well as AMQP usage scenarios, topics like routing, error handing & recovery, broker-specific extensions, TLS support, troubleshooting and so on.
+
+
+### API reference ###
+
+[API reference](http://bit.ly/mDm1JE) is up on [rubydoc.info](http://rubydoc.info) and is updated daily.
+
+
+
+
+## How to use AMQP gem with Ruby on Rails, Merb, Sinatra and other web frameworks ##
+
+We cover this subject for multiple Ruby application servers in [Connecting to the broker guide](http://bit.ly/kFCVQU), take a look and let us know
+what wasn't clear.
+
+
+
+## Community
+
+ * Join [Ruby AMQP mailing list](http://groups.google.com/group/ruby-amqp)
+ * Follow [@rubyamqp](https://twitter.com/rubyamqp) on Twitter for Ruby AMQP ecosystem updates.
+ * Join also [RabbitMQ mailing list](https://lists.rabbitmq.com/cgi-bin/mailman/listinfo/rabbitmq-discuss) (AMQP community epicenter).
+ * Stop by #rabbitmq on irc.freenode.net. You can use [Web IRC client](http://webchat.freenode.net?channels=rabbitmq) if you don't have an IRC client installed.
+
+
+
+## Links ##
+
+* [API reference](http://rdoc.info/github/ruby-amqp/amqp/master/frames)
+* [Documentation guides](http://bit.ly/amqp-gem-docs)
+* [Code Examples](https://github.com/ruby-amqp/amq-protocol/tree/master/examples/)
+* [Issue tracker](http://github.com/ruby-amqp/amqp/issues)
+* [Continous integration status](http://travis-ci.org/#!/ruby-amqp/amqp)
+
+
+## License ##
+
+AMQP gem is licensed under the [Ruby License](http://www.ruby-lang.org/en/LICENSE.txt).
+
+
+
+## Credits and copyright information ##
+
+* The Original Code is [tmm1/amqp](http://github.com/tmm1/amqp).
+* The Initial Developer of the Original Code is Aman Gupta.
+* Copyright (c) 2008 - 2010 [Aman Gupta](http://github.com/tmm1).
+* Contributions from [Jakub Stastny](http://github.com/botanicus) are Copyright (c) 2011 VMware, Inc.
+* Copyright (c) 2010 — 2011 [ruby-amqp](https://github.com/ruby-amqp) group members.
+
+Currently maintained by [ruby-amqp](https://github.com/ruby-amqp) group members
+Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.
+
+
+## How can I learn more about AMQP and messaging in general? ##
+
+### AMQP resources ###
+
+ * [RabbitMQ tutorials](http://www.rabbitmq.com/getstarted.html) that demonstrate interoperability
+ * [Wikipedia page on AMQP](http://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol)
+ * [AMQP quick reference](http://www.rabbitmq.com/amqp-0-9-1-quickref.html)
+ * John O'Hara on the [history of AMQP](http://www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=485)
+
+### Messaging and distributed systems resources ###
+
+ * [Enterprise Integration Patterns](http://www.eaipatterns.com), a book about messaging and use of messaging in systems integration.
+
+ * [A Critique of the Remote Procedure Call Paradigm](http://www.cs.vu.nl/~ast/publications/euteco-1988.pdf)
+ * [A Note on Distributed Computing](http://research.sun.com/techrep/1994/smli_tr-94-29.pdf)
+ * [Convenience Over Correctness](http://steve.vinoski.net/pdf/IEEE-Convenience_Over_Correctness.pdf)
+ * Joe Armstrong on [Erlang messaging vs RPC](http://armstrongonsoftware.blogspot.com/2008/05/road-we-didnt-go-down.html)
+
+
+
+## (Very) Short FAQ ##
+
+### So, does amqp gem only work with RabbitMQ? ###
+
+This library is developed and tested primarily with [RabbitMQ](http://rabbitmq.com), although it should be compatible with any
+server implementing the [AMQP 0.9.1 spec](http://bit.ly/hw2ELX). For AMQP 0.8 brokers, use amqp gem version 0.7.x.
+
+### Why isn't Ruby 1.8.7.-p249 supported? ###
+
+Because there is absolutely no way we can both make code like the following (pseudo-synchronous) work
+
+    conn = AMQP.connect
+    ch   = AMQP::Channel.new(conn)
+
+    ex   = ch.default_exchange
+    ex.publish(some_data)
+
+and not be affected by this [Ruby 1.8.7-p249-specific bug (super called outside of method)](http://bit.ly/iONBmH)
+
+
+### How does amqp gem relate to amq-client gem, amq-protocol and libraries like bunny? ###
+
+See [this page about AMQP gems family](https://github.com/ruby-amqp/amq-client/blob/master/README.textile)

data/amqp.gemspec

@@ -9,20 +9,22 @@ Gem::Specification.new do |s|
   s.version = AMQP::VERSION
   s.authors = ["Aman Gupta", "Jakub Stastny aka botanicus", "Michael S. Klishin"]
   s.homepage = "http://github.com/ruby-amqp/amqp"
-  s.summary = "AMQP client implementation in Ruby/EventMachine."
-  s.description = "Widely used, feature-rich asynchronous AMQP 0.9.1 client with batteries included"
+  s.summary = "Widely used, feature-rich asynchronous AMQP 0.9.1 client with batteries included"
+  # RubyGems will emit warnings if summary is the same as description. I have no idea why but lets trick it. MK.
+  s.description = "Widely used, feature-rich asynchronous AMQP 0.9.1 client with batteries included."
   s.email = ["bWljaGFlbEBub3ZlbWJlcmFpbi5jb20=\n", "c3Rhc3RueUAxMDFpZGVhcy5jeg==\n"].map { |i| Base64.decode64(i) }
 
   # files
   s.files = `git ls-files`.split("\n").reject { |file| file =~ /^vendor\// || file =~ /^gemfiles\// }
   s.require_paths = ["lib"]
 
-  s.rdoc_options = '--include=examples --main README.textile'
-  s.extra_rdoc_files = ["README.textile"] + Dir.glob("docs/*")
+  s.rdoc_options = '--include=examples --main README.md'
+  s.extra_rdoc_files = ["README.md"] + Dir.glob("docs/*")
 
   # Dependencies
   s.add_dependency "eventmachine"
-  s.add_dependency "amq-client", ">= 0.7.0.alpha25"
+  s.add_dependency "amq-client",   ">= 0.7.0.alpha34"
+  s.add_dependency "amq-protocol", ">= 0.7.0.alpha6"
 
   begin
     require "changelog"

data/bin/set_test_suite_realms_up.sh

@@ -7,15 +7,15 @@ rabbitmqctl add_user guest guest
 rabbitmqctl set_permissions -p / guest ".*" ".*" ".*"
 
 
-# amqp_gem:amqp_gem_password has full access to /amqp_gem_testbed
+# amqp_gem:amqp_gem_password has full access to amqp_gem_testbed
 
-rabbitmqctl add_vhost /amqp_gem_testbed
+rabbitmqctl add_vhost amqp_gem_testbed
 rabbitmqctl add_user amqp_gem amqp_gem_password
-rabbitmqctl set_permissions -p /amqp_gem_testbed amqp_gem ".*" ".*" ".*"
+rabbitmqctl set_permissions -p amqp_gem_testbed amqp_gem ".*" ".*" ".*"
 
 
-# amqp_gem_reader:reader_password has read access to /amqp_gem_testbed
+# amqp_gem_reader:reader_password has read access to amqp_gem_testbed
 
 rabbitmqctl add_user amqp_gem_reader reader_password
-rabbitmqctl clear_permissions -p /amqp_gem_testbed guest
-rabbitmqctl set_permissions -p /amqp_gem_testbed amqp_gem_reader "^---$" "^---$" ".*"
+rabbitmqctl clear_permissions -p amqp_gem_testbed guest
+rabbitmqctl set_permissions -p amqp_gem_testbed amqp_gem_reader "^---$" "^---$" ".*"

data/docs/08Migration.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Migrating to version 0.8.0 and later
+
 h1. TBD
 
 
@@ -8,7 +10,7 @@ TBD
 
 h2. Covered versions
 
-This guide covers amqp gem v0.8.0 and later.
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
 
 
 

data/docs/Bindings.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Bindings
+
 h1. TBD
 
 
@@ -8,7 +10,7 @@ TBD
 
 h2. Covered versions
 
-This guide covers amqp gem v0.8.0 and later.
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
 
 
 

data/docs/Clustering.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Clustering
+
 h1. Clustering
 
 
@@ -8,6 +10,8 @@ This guide covers clustered AMQP broker setups, with RabbitMQ as example.
 
 h2. Covered versions
 
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.9.0 and later.
+
 TBD
 
 

data/docs/ConnectingToTheBroker.textile

@@ -1,15 +1,17 @@
-h1. Connecting to the broker
+# @title Ruby amqp gem: Connecting to the broker, integrating with Ruby on Rails, Merb and Sinatra
+
+h1. Connecting to the broker, integrating with Ruby on Rails, Merb and Sinatra
 
 
 h2. About this guide
 
 This guide covers connection to AMQP broker from standalone and Web applications,
-connection error handling, authentication failure handling and related issues..
+connection error handling, authentication failure handling and related issues.
 
 
 h2. Covered versions
 
-This guide covers amqp gem v0.8.0 and later.
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
 
 
 
@@ -65,42 +67,47 @@ Default connection parameters are
 
 h3. Using connection strings
 
-It is possible to use connection URIs (à la JDBC) with amqp and amqps schemas, for example:
+It is convenient to be able to specify the AMQP connection
+parameters as a URI string, and various "amqp" URI schemes
+exist.  Unfortunately, there is no standard for these URIs, so
+while the schemes share the basic idea, they differ in some
+details.  This implementation aims to encourage URIs that work
+as widely as possible.
+
+Here are some examples:
 
  * amqp://dev.rabbitmq.com
  * amqp://dev.rabbitmq.com:5672
  * amqp://guest:guest@dev.rabbitmq.com:5672
  * amqp://hedgehog:t0ps3kr3t@hub.megacorp.internal/production
- * amqps://hub.megacorp.internal//
+ * amqps://hub.megacorp.internal/%2Fvault
 
-Two supported schemas are *amqp* and *amqps*. Default port for amqp is 5672. If port isn't given, and schema
-is amqps, amqp gem will assume it has to connect to 5671, default port for amqps.
+The URI scheme should be "amqp", or "amqps" if SSL is required.
 
-h4. Vhosts: naming schemas and parsing
+The host, port, username and password are represented in the
+authority component of the URI in the same way as in http URIs.
 
-AMQP 0.9.1 spec does not define what vhost naming scheme should be. RabbitMQ and Apache Qpid use different schemes
-(Qpid said to have two) but the bottom line is: even though some brokers use / as the default vhost, it can be *any string*.
-Host (and optional port) part must be separated from vhost (path component) with a slash character (/).
+The vhost is obtained from the first segment of the path, with the
+leading slash removed.  The path should contain only a single segment
+(i.e, the only slash in it should be the leading one).  If the vhost
+is to include slashes or other reserved URI characters, these should
+be percent-escaped.
 
-Here are some examples that demonstrate how {AMQP::Client.parse_connection_uri} parses out vhost from connection URI:
+Here are some examples that demonstrate how
+{AMQP::Client.parse_connection_uri} parses out the vhost from
+connection URIs:
 
 <pre>
 <code>
 AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com")            # => vhost is nil, so default (/) will be used
 AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/")           # => vhost is an empty string
-AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com//")          # => vhost is /
-AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com//vault")     # => vhost is /vault
 AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/%2Fvault")   # => vhost is /vault
 AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/production") # => vhost is production
 AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/a.b.c")      # => vhost is a.b.c
-AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com///a/b/c/d")  # => vhost is //a/b/c/d
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/foo/bar")  # => ArgumentError
 </code>
 </pre>
 
-{AMQP::Client.parse_connection_uri} will also unescape path part of the URI.
-
-
-
 
 h2. Starting event loop & connecting in standalone applications
 
@@ -363,116 +370,112 @@ For Sinatra and pure Rack applications, place it next to other configuration cod
 
 Next we are going to discuss issues specific to particular Web servers.
 
-h3. Using amqp gem with Unicorn
 
-h4. Use separate thread for EventMachine reactor
 
-Since Unicorn is not EventMachine-based, you need to start EventMachine reactor in a separate thread like this:
+h3. Using Ruby amqp gem with Unicorn
 
-<pre>
-<code>
-Thread.new { EventMachine.run }
-# give EventMachine reactor a moment to start
-sleep(0.5)
+h4. Unicorn is a pre-forking server
 
-# now is a good moment to use AMQP.connect
-</code>
-</pre>
+"Unicorn":http://unicorn.bogomips.org is a pre-forking server. That means it forks worker processes that serve HTTP requests. The "fork(2)":http://en.wikipedia.org/wiki/Fork_(operating_system) system call
+has several gotchas associated with it, two of which affect EventMachine and "Ruby amqp gem":http://github.com/ruby-amqp/amqp:
+
+ * Unintentional file descriptor sharing
+ * The fact that "forked child process only inherits one thread":http://bit.ly/fork-and-threads (and EventMachine thread thus is not inherited)
 
-Otherwise EventMachine will block current thread.
+To avoid both problems, start EventMachine reactor and AMQP connection *after* master process forks workers. Master Unicorn process never serves HTTP requests and usually
+doesn't need to hold an AMQP connection. Next lets see how to spin up EventMachine reactor and connect to the broker after Unicorn forks a worker.
 
-h4. Starting EventMachine reactor after Unicorn forks worker processes
 
-Because *Unicorn is a pre-forking server, you need to run the same piece of code in
-after_fork hook in Unicorn configuration file for your app*, otherwise, worker processes won't have EventMachine reactor running:
+h4. Starting EventMachine reactor and connecting to the broker after Unicorn forks worker processes
+
+Unicorn lets you specify a configuration file to use. In that file, you define a callback Unicorn runs after it forks worker process(es):
 
 <pre>
 <code>
-# example snippet of Unicorn configuration file ( config/unicorn/development.rb or similar)
-after_fork do |server, worker|
-  Thread.new { EventMachine.run }
-  # give EventMachine reactor a moment to start
-  sleep(0.5)
+ENV["FORKING"] = "true"
 
-  # now is a good moment to use AMQP.connect
-end
-</code>
-</pre>
+listen 3000
 
+worker_processes 1
+timeout          30
 
-h3. Using amqp gem with Passenger
+preload_app true
 
-TBD: if you are a Passenger user, please help us write this section!
 
+after_fork do |server, worker|
+  require "amqp"
 
+  # the following is *required* for Rails + "preload_app true",
+  defined?(ActiveRecord::Base) and
+    ActiveRecord::Base.establish_connection
 
-h3. Using amqp gem with Thin and Goliath
 
-h4. Thin and Goliath start EventMachine reactor for you, but there is a little nuance
+  t = Thread.new { AMQP.start }
+  sleep(1.0)
 
-If you use "Thin":http://code.macournoyer.com/thin/ or "Goliath":https://github.com/postrank-labs/goliath/, you are all set: those two servers use EventMachine under the hood.
-There is no need to start EventMachine reactor. However, depending on app server, it's version, version of the framework and Rack middleware being used,
-EventMachine reactor start may be slightly delayed. To not depend on this factor, use EventMachine.next_tick to delay connection until after reactor is actually running:
+  EventMachine.next_tick do
+    AMQP.channel ||= AMQP::Channel.new(AMQP.connection)
+    AMQP.channel.queue("amqpgem.examples.rails23.warmup", :durable => true)
 
-<pre>
-<code>
-EventMachine.next_tick { AMQP.connect(...) }
+    3.times do |i|
+      puts "[after_fork/amqp] Publishing a warmup message ##{i}"
+
+      AMQP.channel.default_exchange.publish("A warmup message #{i} from #{Time.now.strftime('%H:%M:%S %m/%b/%Y')}", :routing_key => "amqpgem.examples.rails23.warmup")
+    end
+  end
+end
 </code>
 </pre>
 
-So in case EventMachine reactor isn't running yet on server/application boot, connection won't fail but instead wait for reactor to start.
-Thin and Goliath are not pre-forking servers so there is no need to re-establish connection the way you do it with Unicorn and Passenger.
+In the example above we start EventMachine reactor in a separate thread, block current thread for 1 second to let event loop spin up and then
+connect to AMQP broker on the next event loop tick. Publishing several warmup messages on boot is a good idea because it
+lets you detect issues that forking may cause earlier.
 
+Note that configuration file can easily be used in development environments: other than the fact that Unicorn runs in the foreground,
+it gives you exactly the same application boot behavior as in QA and production environments, which is a good thing.
 
+An "example Ruby on Rails application that uses Ruby amqp gem and Unicorn":http://bit.ly/ruby-amqp-gem-example-with-ruby-on-rails-and-unicorn is available on GitHub.
 
 
-h2. If it just doesn't work: troubleshooting
 
-If you read this guide yet your issue is still unresolved, check the following things before asking on the mailing list:
 
- * AMQP broker log.
- * List of users in a particular vhost you are trying to connect
- * Network connectivity. We know, it's obvious, yet even experienced developers and devops engineers struggle with network access misconfigurations every once in a while.
- * If EventMachine is started in a separate thread, make sure that isn't dead. If it is, this usually means there was an exception that caused it to terminate.
+h3. Using Ruby amqp gem with Passenger
 
+Phusion Passenger is a pre-forking server, much like Unicorn. Just like with Unicorn, EventMachine reactor and AMQP connection should be started *after* it forks worker
+processes. Passenger documentation has "a section":http://bit.ly/passenger-forking-gotchas that explains how to avoid problems related to the behavior of fork(2) system
+call, namely:
 
-h3. Inspecting AMQP broker log file
+ * Unintentional file descriptor sharing
+ * The fact that "forked child process only inherits one thread":http://bit.ly/fork-and-threads (and EventMachine thread thus is not inherited)
 
-In this section we will cover typical problems that can be tracked down by reading AMQP broker log. We will use RabbitMQ as an example, however, different AMQP brokers
-often log most of the same issues.
+TBD: if you are a Passenger user, please help us write the rest of this section!
 
-RabbitMQ logs abrupt TCP connection failures, timeouts, protocol version mismatches and so on.
-If you are running RabbitMQ, log locations for various operating systems and distributions is documented in the "RabbitMQ installation guide":http://www.rabbitmq.com/install.html
 
-On Mac OS X, RabbitMQ installed via Homebrew logs to $HOMEBREW_HOME/var/log/rabbitmq/rabbit@$HOSTNAME.log. For example, if you have Homebrew installed at /usr/local and
-your hostname is giove, log will be at /usr/local/var/log/rabbitmq/rabbit@giove.log.
 
-Here is what authentication failure looks like in RabbitMQ log:
+h3. Using Ruby amqp gem with Thin and Goliath
+
+h4. Thin and Goliath start EventMachine reactor for you, but there is a little nuance
+
+If you use "Thin":http://code.macournoyer.com/thin/ or "Goliath":https://github.com/postrank-labs/goliath/, you are all set: those two servers use EventMachine under the hood.
+There is no need to start EventMachine reactor. However, depending on app server, it's version, version of the framework and Rack middleware being used,
+EventMachine reactor start may be slightly delayed. To not depend on this factor, use EventMachine.next_tick to delay connection until after reactor is actually running:
 
 <pre>
-=ERROR REPORT==== 17-May-2011::17:37:58 ===
-exception on TCP connection <0.4770.0> from 127.0.0.1:46551
-{channel0_error,starting,
-                {amqp_error,access_refused,
-                            "AMQPLAIN login refused: user 'pipeline_agent' - invalid credentials",
-                            'connection.start_ok'}}
+<code>
+EventMachine.next_tick { AMQP.connect(...) }
+</code>
 </pre>
 
-This means that connection attempt with username pipeline_agent failed because credentials were invalid. If you are seeing this message, make sure username,
-password *and vhost* are correct.
+So in case EventMachine reactor isn't running yet on server/application boot, connection won't fail but instead wait for reactor to start.
+Thin and Goliath are not pre-forking servers so there is no need to re-establish connection the way you do it with Unicorn and Passenger.
 
 
-The following entry:
 
-<pre>
-=ERROR REPORT==== 17-May-2011::17:26:28 ===
-exception on TCP connection <0.4201.62> from 10.8.0.30:57990
-{bad_header,<<65,77,81,80,0,0,9,1>>}
-</pre>
 
-Means that client supports AMQP 0.9.1 but broker doesn't (RabbitMQ versions pre-2.0 only support AMQP 0.8, for example). If you are using amqp gem 0.8 or later
-and seeing this entry in your broker log, you are connecting to AMQP broker that is too old to support this AMQP version. In case of RabbitMQ, make sure you run
-version 2.0 or later.
+h2. If it just doesn't work: troubleshooting
+
+If you read this guide yet your issue is still unresolved, check our {file:docs/Troubleshooting.textile Troubleshooting guide} before asking on the mailing list
+
 
 
 
@@ -490,3 +493,22 @@ what was unclear? what wasn't covered? maybe you don't like guide style or gramm
 key to making documentation better.
 
 If mailing list communication is not an option for you for some reason, you can "contact guides author directly":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation
+
+
+
+<div id="disqus_thread"></div>
+<script type="text/javascript">
+    /* * * CONFIGURATION VARIABLES * * */
+    var disqus_shortname = 'rubyamqpdocs'; // required: replace example with your forum shortname
+
+    var disqus_developer = 0; // set to 1 on local machine for testing comments
+    var disqus_identifier = 'amqp_connecting_to_the_broker';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/ConnectingToTheBroker.textile';
+
+    /* * * DON'T EDIT BELOW THIS LINE * * */
+    (function() {
+        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
+        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
+        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
+    })();
+</script>