amqp 0.8.0.rc12 → 0.8.0.rc13

data/docs/ConnectionEncryptionWithTLS.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Using TLS
+
 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/DocumentationGuidesIndex.textile

@@ -1,20 +1,24 @@
+# @title Ruby AMQP gem documentation guides
+
 h1. Ruby AMQP gem documentation guides
 
 h2. Guide list
 
  * {file:docs/GettingStarted.textile Getting started}
  * {file:docs/ConnectingToTheBroker.textile Connecting to the broker}
- * {file:docs/Queues.textile Queues}
- * {file:docs/Exchanges.textile Exchanges}
+ * {file:docs/Queues.textile Working with queues}
+ * {file:docs/Exchanges.textile Working with exchanges}
  * {file:docs/Bindings.textile Bindings}
  * {file:docs/Routing.textile Routing}
  * {file:docs/Durability.textile Durability and message persistence}
  * {file:docs/ErrorHandling.textile Error handling}
  * {file:docs/08Migration.textile Upgrading from version 0.6.x/0.7.x to 0.8.x and above}
+ * {file:docs/Troubleshooting.textile Troubleshooting and debugging AMQP applications}
  * {file:docs/Clustering.textile Clustering}
  * {file:docs/RabbitMQVersions.textile RabbitMQ versions}
  * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)}
  * {file:docs/VendorSpecificExtensions.textile Vendor-specific extensions to AMQP 0.9.1 spec}
+ * {file:docs/RunningTests.textile Running amqp gem test suite}
 
 
 h2. Tell us what you think!
@@ -24,3 +28,21 @@ 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_documentation_guides_index';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/DocumentationGuidesIndex.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>

data/docs/Durability.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Durability and related matters
+
 h1. Durability and related matters
 
 
@@ -9,7 +11,7 @@ topics related to durability, for example, durability in cluster environment.
 
 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.
 
 
 h2. Entity durability and message persistence
@@ -101,3 +103,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_durability';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/Durability.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>

data/docs/ErrorHandling.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Error handling and recovery
+
 h1. Error handling and recovery
 
 h2. About this guide
@@ -17,7 +19,7 @@ issues like
 
 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.
 
 
 h2. Code examples
@@ -233,3 +235,21 @@ 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_error_handling';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/ErrorHandling.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>

data/docs/Exchanges.textile

@@ -1,44 +1,193 @@
-h1. TBD
+# @title Ruby AMQP gem: Working with exchanges
+
+h1. Working with exchanges
 
 
 h2. About this guide
 
-TBD
+This guide covers everything related to exchanges in AMQP 0.9.1, common usage scenarios and how to accomplish typical operations using
+amqp gem.
 
 
 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.
 
 
 h2. Exchanges in AMQP 0.9.1, briefly
 
-TBD
+h3. What are AMQP exchanges?
+
+An exchange accepts messages from a producer application and routes these to message queues. They can be thought of as "mailboxes" of AMQP
+world. Unlike some other messaging middleware products and protocols, in AMQP messages are *not* published directly to queues: they
+are published to exchanges that route them to queue(s) using pre-arranged criteria (called bindings).
+
+There are multiple exchange types in AMQP 0.9.1, each with its own routing semantics. Custom exchange types can be created to cover
+sophisticated routing scenarios (for example, routing based on geolocation data), edge cases or just for convenience.
+
+
+h3. Concept of bindings
+
+Binding is an association between a queue and an exchange. Queues must be bound to at least one exchange in order to receive messages from publishers.
+Learn more about bindings in {file:docs/Bindings.textile Bindings guide}.
+
+
+h3. Attributes
+
+Exchanges have several attributes associated with them:
+
+ * Name
+ * Type (direct, fanout, topic, headers or some custom type)
+ * Durability
+ * Whether exchange is auto-deleted when no longer used
+ * Other metadata (aka X-arguments)
 
 
 h2. Exchange types
 
-TBD
+There are 4 built-in exchange types in AMQP 0.9.1:
+
+ * Direct
+ * Fanout
+ * Topic
+ * Headers
+
+As stated previously, each exchange type has own routing semantics and new exchange types can be added by extending brokers with plugins.
+Custom exchange types begin with x-, much like custom HTTP headers, for example, "x-recent-history exchange":https://github.com/videlalvaro/rabbitmq-recent-history-exchange.
+
+
+
+
+h2. Message attributes
+
+Before we start looking at various exchange types and their routing semantics, we need to introduce idea of message attributes.
+Every AMQP message has a number of *attributes*. Some attributes are important and used very often, other are used rarely. AMQP message attributes are metadata:
+they are similar in purpose to HTTP request and response headers.
+
+Every AMQP 0.9.1 message has an attribute called the *routing key*. The routing key is an "address" that the exchange may use to decide how to route
+the message (similar to, but more generic, than URL in HTTP). Most exchange types use routing key to implement routing logic, but some ignore
+it and use other criteria (for example, message content).
+
+
 
 
 h2. Fanout exchanges
 
-TBD
+Fanout exchanges route messages to all queues bound to it, the routing key is ignored. If N queues are bound to a fanout exchange,
+when a new message is published to that exchange, a *copy of the message* is delivered to all N queues, so fanout exchanges
+are ideal for "broadcast routing":http://en.wikipedia.org/wiki/Broadcasting_%28computing%29 of messages.
+
+Graphically this can be represented as
+
+!http://upload.wikimedia.org/wikipedia/commons/thumb/d/dc/Broadcast.svg/500px-Broadcast.svg.png!
+
+AMQP 0.9.1 brokers must implement fanout exchange type and pre-declare one instance with the name of "amq.fanout".
+This means that applications can rely on that exchange to always be available to them. Each vhost has a separate instance of that exchange,
+it is *not shared across vhosts* for obvious reasons.
+
 
 
 h2. Direct exchanges
 
-TBD
+Direct exchange delivers messages to queues based on *message routing key*, an attribute every AMQP 0.9.1 message has.
+
+Here is how it works:
+
+ * A queue binds to the exchange with a routing key, K.
+ * When a new message with routing key R arrives to direct exchange, the exchange routes it to the queue if K = R.
+
+Direct exchange is ideal for "unicast routing":http://en.wikipedia.org/wiki/Unicast of messages (although it can be used for "multicast routing":http://en.wikipedia.org/wiki/Multicast, too).
+
+!http://upload.wikimedia.org/wikipedia/commons/thumb/7/75/Unicast.svg/500px-Unicast.svg.png!
+
+AMQP 0.9.1 brokers must implement direct exchange type and pre-declare two instances
+
+ * *amq.direct*.
+ * *""* (unnamed, referred to as an empty string by many clients including amqp Ruby gem) exchange known as *default exchange*.
+
+This means that applications can rely on those exchanges to always be available to them. Each vhost has separate instances of those exchanges,
+they are *not shared across vhosts* for obvious reasons.
+
+
+h3. Default exchange
+
+Default exchange is a direct exchange with no name (amqp gem refers to it using an empty string) pre-declared by the broker. It has one key special
+property that makes it very useful for simple applications: *every queue is automatically bound to it with a routing key the same as queue name".
+
+For example, when you declare a queue with the name of "search.indexing.online", AMQP broker will bind it to the default exchange using
+"search.indexing.online" as routing key. So a message publishes to the default exchange with routing key = "search.indexing.online"
+will be routed to the queue "search.indexing.online". In other words, default exchange makes it possible to "deliver messages directly to queues",
+even though that is not technically correct.
+
+
+amqp gem offers two ways of obtaining of the default exchange: {AMQP::Channel#default_exchange} and {AMQP::Channel#direct} (use  empty string as exchange name).
+{AMQP::Exchange#initialize} can be used as well but requires more effort and for this particular case offers no benefits over instance methods on {AMQP::Channel}.
+
+The default exchange is what the "Hello, World" example uses:
+
+{include:file:examples/hello_world.rb}
+
 
 
 h2. Topic exchanges
 
+Topic exchanges route messages to one or many queues based on matching between message routing key and pattern that was used for binding
+queue to the exchange.
+
+
+Topic exchanges are commonly used for "multicast routing":http://en.wikipedia.org/wiki/Multicast of messages.
+
+!http://upload.wikimedia.org/wikipedia/commons/thumb/3/30/Multicast.svg/500px-Multicast.svg.png!
+
+Topic exchanges can be used for "broadcast routing":http://en.wikipedia.org/wiki/Broadcasting_%28computing%29 but usually fanout exchanges are more efficient at that.
+
+
+
+Here is an example of topic exchange in action:
+
+{include:file:examples/routing/weather_updates.rb}
+
+TBD
+
+
+
+h2. Headers exchanges
+
+
+
+TBD
+
+
+
+h2. Custom exchange types
+
+TBD
+
+
+
+h2. Declaring/Instantiating exchanges
+
+
+
+Below is an example of {AMQP::Exchange#initialize} used with a callback:
+
+{include:file:examples/exchanges/declare_an_exchange_without_assignment.rb}
+
+
 TBD
 
 
 
 h2. Publishing messages
 
+
+h3. Publishing one-off messages
+
+The following example publishes a message and *safely* closes AMQP connection after that by passing a block
+to {AMQP::Exchange#publish}:
+
+{include:file:examples/publishing/publishing_a_one_off_message.rb}
+
 TBD
 
 
@@ -56,13 +205,18 @@ TBD
 
 h2. Deleting exchanges
 
+
+Exchanges are be *auto-deleted*. An example that uses two auto-deleted exchanges:
+
+{include:file:examples/exchanges/autodeletion_of_exchanges.rb}
+
 TBD
 
 
 
 h2. Exchange durability vs Message durability
 
-TBD
+See {file:docs/Durability.textile Durability guide}
 
 
 
@@ -74,7 +228,7 @@ TBD
 
 h2. Vendor-specific extensions related to exchanges
 
-TBD
+See {file:docs/VendorSpecificExtensions.textile Vendor-specific Extensions guide}
 
 
 
@@ -90,3 +244,21 @@ 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_exchanges';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/Exchanges.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>

data/docs/GettingStarted.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Getting Started with AMQP and Ruby
+
 h1. Getting started with AMQP Ruby gem
 
 
@@ -8,38 +10,46 @@ It should take about 20 minutes to read and study provided code examples. This g
 
  * Installing RabbitMQ, a mature popular implementation of multiple versions of AMQP protocol.
  * Installing amqp gem via "Rubygems":http://rubygems.org and "Bundler":http://gembundler.com.
- * Running a "Hello, world"-like code example, a simple demonstration of 1:1 communication.
+ * Running the "Hello, world" of messaging, a simple demonstration of 1:1 communication.
  * Creating a "Twitter like" publish/subscribe example with 1 publisher and 4 subscribers, a case of 1:n communication.
  * Creating a topic routing example with 2 publishers and 8 subscribers, a case of n:m communication when subscribers only receive messages they are interested in.
 
 
 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.
 
 
 h2. Installing RabbitMQ
 
-RabbitMQ site has a good "installation guide":http://www.rabbitmq.com/install.html that covers many operating systems.
-On Mac OS X, the fastest way to install RabbitMQ is with Homebrew:
+"RabbitMQ site":http://rabbitmq.com has a good "installation guide":http://www.rabbitmq.com/install.html that covers many operating systems.
+On Mac OS X, the fastest way to install RabbitMQ is with "Homebrew":http://mxcl.github.com/homebrew/:
 
+<pre>
 <code>
 brew install rabbitmq
 </code>
+</pre>
 
 then run it:
+
+<pre>
 <code>
 rabbitmq-server
 </code>
+</pre>
+
+On Debian and Ubuntu, you can either "download RabbitMQ .deb package":http://www.rabbitmq.com/server.html and install it with
+"dpkg":http://www.debian.org/doc/FAQ/ch-pkgtools.en.html or use "apt repository RabbitMQ team provides":http://www.rabbitmq.com/debian.html#apt.
+For RPM-based distributions like RedHat or CentOS RabbitMQ team provides an "RPM package":http://www.rabbitmq.com/install.html#rpm.
 
-On "Debian and Ubuntu":http://www.rabbitmq.com/install.html#debian, you can either download a .deb package and install it with
-dpkg or use apt repository RabbitMQ team provides. RabbitMQ package in even recent (10.10) versions of Ubuntu are old and won't
-work with amqp gem 0.8.0 and later (we need at least version 2.0). For "RPM-based distributions":http://www.rabbitmq.com/install.html#rpm like RedHat
-or CentOS RabbitMQ team provides an RPM package.
+<span class="note">
+RabbitMQ package in even recent (10.10) versions of Ubuntu are outdated and *won't work with amqp gem 0.8.0 and later* (we need at least version 2.0).
+</span>
 
 
 
-h2. Installing amqp gem
+h2. Installing Ruby amqp gem
 
 h3. Make sure you have Ruby installed
 
@@ -55,17 +65,27 @@ This guides assumes you have one of the supported Ruby implementations installed
 h3. With Rubygems
 
 To get amqp gem 0.8.0
+
+h4. On Microsoft Windows 7
+
 <pre>
-<code>
-gem install amqp --pre
-</code>
+gem install eventmachine --pre
+gem install amqp --pre --version "~> 0.8.0.RC12"
+</pre>
+
+h4. On other OSes or JRuby:
+
+<pre>
+gem install amqp --pre --version "~> 0.8.0.RC12"
 </pre>
 
 h3. With Bundler
 
 <pre>
 <code>
-gem "amqp", :git => "git://github.com/ruby-amqp/amqp.git", :branch => "master"
+source :rubygems
+
+gem "amqp", "~> 0.8.0.RC12" # optionally: :git => "git://github.com/ruby-amqp/amqp.git", :branch => "master"
 </code>
 </pre>
 
@@ -80,43 +100,18 @@ irb -rubygems
 :001 > require "amqp"
 => true
 :002 > AMQP::VERSION
-=> "0.8.0.rc2"
+=> "0.8.0.rc12"
 </code>
 </pre>
 
 
-h2. A "Hello, world" example
-
-Lets begin with a classic Hello, world example. First, here's the code:
-
-<pre>
-<code>
-#!/usr/bin/env ruby
-# encoding: utf-8
-
-require "rubygems"
-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..."
+h2. "Hello, world" example
 
-  channel  = AMQP::Channel.new(connection)
-  queue    = channel.queue("amqpgem.examples.hello_world", :auto_delete => true)
-  exchange = channel.direct("")
+Lets begin with the classic "Hello, world" example. First, here's the code:
 
-  queue.subscribe do |payload|
-    puts "Received a message: #{payload}. Disconnecting..."
+<script src="https://gist.github.com/998690.js"> </script>
 
-    connection.close {
-      EM.stop { exit }
-    }
-  end
-
-  exchange.publish "Hello, world!", :routing_key => queue.name
-end
-</code>
-</pre>
+(if the example above isn't displayed, see this "gist":https://gist.github.com/998690)
 
 This example demonstrates a very common communication scenario: app A wants to publish a message that will end up in
 a queue that app B listens on. In this example, queue name is "amqpgem.examples.hello". Lets go through this example
@@ -214,86 +209,28 @@ as message's routing key. This is how our message ends up in amqpgem.examples.he
 
 This first example can be modified to use method chaining technique:
 
-<pre>
-<code>
-#!/usr/bin/env ruby
-# encoding: utf-8
-
-require "rubygems"
-require "amqp"
-
-EventMachine.run do
-  AMQP.connect(:host => '127.0.0.1') do |connection|
-    puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
-
-    channel  = AMQP::Channel.new(connection)
+<script src="https://gist.github.com/998691.js"> </script>
 
-    channel.queue("amqpgem.examples.helloworld", :auto_delete => true).subscribe do |payload|
-      puts "Received a message: #{payload}. Disconnecting..."
-
-      connection.close {
-        EM.stop { exit }
-      }
-    end
-
-    channel.direct("").publish "Hello, world!", :routing_key => "amqpgem.examples.helloworld"
-  end
-end
-</code>
-</pre>
+(if the example above isn't displayed, see this "gist":https://gist.github.com/998691)
 
 With classes and methods introduced in this example, lets move on to a little bit more
 sophisticated one.
 
 
-h2. Babblr: one-to-many publish/subscribe example
+h2. Blabblr: one-to-many publish/subscribe example
 
 Previous example demonstrated how connection to the broker is made and how to do 1:1 communication
 using default exchange. Now lets take a look at another common scenario: broadcast, or multiple consumers
 and one producer.
 
 A very well know example of broadcast is Twitter: every time a person tweets, followers receive a notification.
-Blabbr, our imaginary information network, models this scenario this way: every network member has a separate
+Blabbr, our imaginary information network, models this scenario: every network member has a separate
 queue and publishes blabs to a separate exchange. 3 Blabbr members, Joe, Aaron and Bob, follow official NBA
 account on Blabbr to get updates about what is up in the world of basketball. Here is the code:
 
-<pre>
-<code>
-#!/usr/bin/env ruby
-# encoding: utf-8
-
-require "rubygems"
-require "amqp"
-
-AMQP.start("amqp://dev.rabbitmq.com:5672") do |connection|
-  channel  = AMQP::Channel.new(connection)
-  exchange = channel.fanout("nba.scores")
-
-  channel.queue("joe", :auto_delete => true).bind(exchange).subscribe do |payload|
-    puts "#{payload} => joe"
-  end
-
-  channel.queue("aaron", :auto_delete => true).bind(exchange).subscribe do |payload|
-    puts "#{payload} => aaron"
-  end
-
-  channel.queue("bob", :auto_delete => true).bind(exchange).subscribe do |payload|
-    puts "#{payload} => bob"
-  end
-
-  exchange.publish("BOS 101, NYK 89").publish("ORL 85, ALT 88")
+<script src="https://gist.github.com/998692.js"> </script>
 
-  # disconnect & exit after 1 second
-  EventMachine.add_timer(1) do
-    exchange.delete
-
-    connection.close {
-      EM.stop { exit }
-    }
-  end
-end
-</code>
-</pre>
+(if the example above isn't displayed, see this "gist":https://gist.github.com/998692)
 
 First line has a few difference from "Hello, world" example above:
 
@@ -398,66 +335,9 @@ on North America updates list.
 
 Here is the code:
 
-<pre>
-<code>
-#!/usr/bin/env ruby
-# encoding: utf-8
+<script src="https://gist.github.com/998694.js"> </script>
 
-require "rubygems"
-require "amqp"
-
-EventMachine.run do
-  AMQP.connect do |connection|
-    channel  = AMQP::Channel.new(connection)
-    exchange = channel.topic("pub/sub", :auto_delete => true)
-
-    # Subscribers.
-    channel.queue("", :exclusive => true) do |queue|
-      queue.bind(exchange, :routing_key => "americas.north.#").subscribe do |headers, payload|
-        puts "An update for North America: #{payload}, routing key is #{headers.routing_key}"
-      end
-    end
-    channel.queue("americas.south").bind(exchange, :routing_key => "americas.south.#").subscribe do |headers, payload|
-      puts "An update for South America: #{payload}, routing key is #{headers.routing_key}"
-    end
-    channel.queue("us.california").bind(exchange, :routing_key => "americas.north.us.ca.*").subscribe do |headers, payload|
-      puts "An update for US/California: #{payload}, routing key is #{headers.routing_key}"
-    end
-    channel.queue("us.tx.austin").bind(exchange, :routing_key => "#.tx.austin").subscribe do |headers, payload|
-      puts "An update for Austin, TX: #{payload}, routing key is #{headers.routing_key}"
-    end
-    channel.queue("it.rome").bind(exchange, :routing_key => "europe.italy.rome").subscribe do |headers, payload|
-      puts "An update for Rome, Italy: #{payload}, routing key is #{headers.routing_key}"
-    end
-    channel.queue("asia.hk").bind(exchange, :routing_key => "asia.southeast.hk.#").subscribe do |headers, payload|
-      puts "An update for Hong Kong: #{payload}, routing key is #{headers.routing_key}"
-    end
-
-    EM.add_timer(1) do
-      exchange.publish("San Diego update", :routing_key => "americas.north.us.ca.sandiego").
-        publish("Berkeley update",         :routing_key => "americas.north.us.ca.berkeley").
-        publish("San Francisco update",    :routing_key => "americas.north.us.ca.sanfrancisco").
-        publish("New York update",         :routing_key => "americas.north.us.ny.newyork").
-        publish("São Paolo update",        :routing_key => "americas.south.brazil.saopaolo").
-        publish("Hong Kong update",        :routing_key => "asia.southeast.hk.hongkong").
-        publish("Kyoto update",            :routing_key => "asia.southeast.japan.kyoto").
-        publish("Shanghai update",         :routing_key => "asia.southeast.prc.shanghai").
-        publish("Rome update",             :routing_key => "europe.italy.roma").
-        publish("Paris update",            :routing_key => "europe.france.paris")
-    end
-
-
-    show_stopper = Proc.new {
-      connection.close do
-        EM.stop
-      end
-    }
-
-    EM.add_timer(2, show_stopper)
-  end
-end
-</code>
-</pre>
+(if the example above isn't displayed, see this "gist":https://gist.github.com/998694)
 
 First line that is different from Blabbr example is
 
@@ -568,7 +448,7 @@ This tutorial ends here. Congratulations! You have learned quite a bit about bot
 
 h2. What to read next
 
-Documentation is organized as a {file:docs/DocumentationGuidesIndex.textile Number of guides}, covering all kinds of
+Documentation is organized as a number of {file:docs/DocumentationGuidesIndex.textile documentation guides}, covering all kinds of
 topics from {file:docs/Routing.textile routing} to {file:docs/ErrorHandling.textile error handling} to
 {file:docs/VendorSpecificExchanges.textile Broker-specific AMQP 0.9.1 extensions}.
 
@@ -590,3 +470,21 @@ 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/GettingStarted.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>