amqp 0.8.0.rc3 → 0.8.0.rc4

data/CHANGELOG

@@ -1,6 +1,7 @@
 = Version 0.8.0
 
   * [FEATURE] AMQP 0.9.1 support, including tx.* operations class.
+  * [API] Default authentication handler now raises AMQP::PossibleAuthenticationFailureError
   * [API] AMQP::Channel#initialize now takes 3rd (optional) options hash.
   * [API] Broker connection class is now AMQP::Session.
   * [API] AMQP::Error instance now may carry cause, an exception that caused exception in question to be raised.
@@ -29,7 +30,6 @@
   * [API] AMQP::Channel#recover now takes (an optional) callback that is called when basic.recover-ok is received.
   * [API] AMQP::Frame is gone.
   * [API] AMQP::Buffer is gone. Serialization & framing are now handled primarily by amq-protocol.
-  * [FEATURE] AMQP gem is now AMQP 0.9.1 compatible: it runs atop of amq-client gem
   * [API] AMQP::Queue#publish is deprecated.
   * [API] Name argument for AMQP::Queue.new and Channel#queue is optional.
 

data/amqp.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
 
   # Dependencies
   s.add_dependency "eventmachine"
-  s.add_dependency "amq-client", ">= 0.7.0.alpha13"
+  s.add_dependency "amq-client", ">= 0.7.0.alpha16"
 
   begin
     require "changelog"

data/docs/ConnectingToTheBroker.textile

@@ -154,7 +154,7 @@ end
 </code>
 </pre>
 
-{AMQP.connect} (and, subsequentily, {AMQP.start}) will raise {AMQP::TCPConnectionFailed} if connection fails. Code that catches it can write to log
+{AMQP.connect} (and {AMQP.start}) will raise {AMQP::TCPConnectionFailed} if connection fails. Code that catches it can write to log
 about the issue or use retry to execute begin block one more time. Because initial connection failures are due to misconfiguration or network outage, reconnection
 to the same endpoint (hostname, port, vhost combination) will result in the same issue over and over. TBD: failover, connection to the cluster.
 
@@ -209,7 +209,7 @@ connection failure:
 require "rubygems"
 require "amqp"
 
-puts "=> TCP connection failure handling with a callback"
+puts "=> Authentication failure handling with a callback"
 puts
 
 handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
@@ -233,6 +233,41 @@ end
 </code>
 </pre>
 
+default handler raises {AMQP::PossibleAuthenticationFailureError}:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+puts "=> Authentication failure handling with a rescue block"
+puts
+
+handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
+connection_settings = {
+  :port     => 5672,
+  :vhost    => "/amq_client_testbed",
+  :user     => "amq_client_gem",
+  :password => "amq_client_gem_password_that_is_incorrect #{Time.now.to_i}",
+  :timeout        => 0.3,
+  :on_tcp_connection_failure => handler
+}
+
+
+begin
+  AMQP.start(connection_settings) do |connection, open_ok|
+    raise "This should not be reachable"
+  end
+rescue AMQP::PossibleAuthenticationFailureError => afe
+  puts "Authentication failed, as expected, caught #{afe.inspect}"
+  EventMachine.stop if EventMachine.reactor_running?
+end
+</code>
+</pre>
+
 In case you wonder why callback name has "possible" in it: {http://bit.ly/mTr1YN AMQP 0.9.1 spec} requires broker implementations to
 simply close TCP connection without sending any more data when an exception (such as authentication failure) occurs before AMQP connection
 is open. In practice, however, when broker closes TCP connection between successful TCP connection and before AMQP connection is open,
@@ -242,30 +277,80 @@ it means that authentication has failed.
 
 h2. In Web applications (Ruby on Rails, Sinatra, Merb, Rack)
 
-h3. With Unicorn
+Web applications are different from standalone applications in that main thread is occupied by Web/application server like Unicorn
+or Thin, so you need to start EventMachine reactor before you attempt to use {AMQP.connect}.
+In a Ruby on Rails app, probably the best place for this is in 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.
+
+Next we are going to discuss issues specific to particular Web servers.
 
-TBD
+h3. Using amqp gem with Unicorn
 
+h4. Use separate thread for EventMachine reactor
 
-h3. With Thin
+Since Unicorn is not EventMachine-based, you need to start EventMachine reactor in a separate thread like this:
+
+<pre>
+<code>
+Thread.new { EventMachine.run }
+# give EventMachine reactor a moment to start
+sleep(0.5)
 
-TBD
+# now is a good moment to use AMQP.connect
+</code>
+</pre>
 
+Otherwise EventMachine will block current thread.
 
-h3. With Goliath
+h4. Starting EventMachine reactor after Unicorn forks worker processes
 
-TBD
+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:
 
+<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)
 
-h3. With Passenger
+  # now is a good moment to use AMQP.connect
+end
+</code>
+</pre>
+
+
+h3. Using amqp gem with Passenger
+
+TBD: if you are a Passenger user, please help us write this section!
+
+
+
+h3. Using 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>
+<code>
+EventMachine.next_tick { AMQP.connect(...) }
+</code>
+</pre>
 
-TBD
+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.
 
 
 
 h2. What to read next
 
-TBD
+ * {file:docs/Queues.textile Queues}
+ * {file:docs/ErrorHandling.textile Error handling}
+ * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)} (if you want to use SSL encrypted connection to the broker)
 
 
 h2. Tell us what you think!

data/docs/DocumentationGuidesIndex.textile

@@ -12,7 +12,7 @@ h2. Guide list
  * {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/RabbitMQVersions.textile RabbitMQ versions}
- * {file:docs/TLS.textile Using TLS (SSL)}
+ * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)}
  * {file:docs/VendorSpecificExtensions.textile Vendor-specific extensions to AMQP 0.9.1 spec}
 
 

data/docs/ErrorHandling.textile

@@ -1,4 +1,4 @@
-h1. Handling AMQP exceptions and connection failures
+h1. Error handling and recovery
 
 h2. About this guide
 
@@ -26,9 +26,160 @@ There are several {https://github.com/ruby-amqp/amqp/tree/master/examples/error_
 free to contribute new examples.
 
 
-h2. Broker connection failures
+h3. Broker connection failures
 
-TBD
+When applications connect to the broker, they need to handle connection failures. Networks are not 100% reliable, even with modern system configuration tools
+like Chef or Puppet misconfigurations happen and broker might be down, too. Error detection should happen as early as possible. There are two ways of detecting
+TCP connection failure, the first one is to catch an exception:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+
+puts "=> TCP connection failure handling with a rescue statement"
+puts
+
+connection_settings = {
+  :port     => 9689,
+  :vhost    => "/amq_client_testbed",
+  :user     => "amq_client_gem",
+  :password => "amq_client_gem_password",
+  :timeout        => 0.3
+}
+
+begin
+  AMQP.start(connection_settings) do |connection, open_ok|
+    raise "This should not be reachable"
+  end
+rescue AMQP::TCPConnectionFailed => e
+  puts "Caught AMQP::TCPConnectionFailed => TCP connection failed, as expected."
+end
+</code>
+</pre>
+
+{AMQP.connect} (and {AMQP.start}) will raise {AMQP::TCPConnectionFailed} if connection fails. Code that catches it can write to log
+about the issue or use retry to execute begin block one more time. Because initial connection failures are due to misconfiguration or network outage, reconnection
+to the same endpoint (hostname, port, vhost combination) will result in the same issue over and over. TBD: failover, connection to the cluster.
+
+Alternative way of handling connection failure is with an errback (a callback for specific kind of error):
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+puts "=> TCP connection failure handling with a callback"
+puts
+
+handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
+connection_settings = {
+  :port     => 9689,
+  :vhost    => "/amq_client_testbed",
+  :user     => "amq_client_gem",
+  :password => "amq_client_gem_password",
+  :timeout        => 0.3,
+  :on_tcp_connection_failure => handler
+}
+
+
+AMQP.start(connection_settings) do |connection, open_ok|
+  raise "This should not be reachable"
+end
+</code>
+</pre>
+
+:on_tcp_connection_failure option accepts any object that responds to #call.
+
+If you connect to the broker from a code in a class (as opposed to top-level scope in a script), Object#method can be used to pass object method as a handler
+instead of a Proc.
+
+TBD: provide an example
+
+
+h3. Authentication failures
+
+Another reason why connection may fail is authentication failure. Handling authentication failure is very similar to handling initial TCP
+connection failure:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+puts "=> Authentication failure handling with a callback"
+puts
+
+handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
+connection_settings = {
+  :port     => 5672,
+  :vhost    => "/amq_client_testbed",
+  :user     => "amq_client_gem",
+  :password => "amq_client_gem_password_that_is_incorrect #{Time.now.to_i}",
+  :timeout        => 0.3,
+  :on_tcp_connection_failure => handler,
+  :on_possible_authentication_failure => Proc.new { |settings|
+                                            puts "Authentication failed, as expected, settings are: #{settings.inspect}"
+
+                                            EM.stop
+                                          }
+}
+
+AMQP.start(connection_settings) do |connection, open_ok|
+  raise "This should not be reachable"
+end
+</code>
+</pre>
+
+default handler raises {AMQP::PossibleAuthenticationFailureError}:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+puts "=> Authentication failure handling with a rescue block"
+puts
+
+handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
+connection_settings = {
+  :port     => 5672,
+  :vhost    => "/amq_client_testbed",
+  :user     => "amq_client_gem",
+  :password => "amq_client_gem_password_that_is_incorrect #{Time.now.to_i}",
+  :timeout        => 0.3,
+  :on_tcp_connection_failure => handler
+}
+
+
+begin
+  AMQP.start(connection_settings) do |connection, open_ok|
+    raise "This should not be reachable"
+  end
+rescue AMQP::PossibleAuthenticationFailureError => afe
+  puts "Authentication failed, as expected, caught #{afe.inspect}"
+  EventMachine.stop if EventMachine.reactor_running?
+end
+</code>
+</pre>
+
+In case you wonder why callback name has "possible" in it: {http://bit.ly/mTr1YN AMQP 0.9.1 spec} requires broker implementations to
+simply close TCP connection without sending any more data when an exception (such as authentication failure) occurs before AMQP connection
+is open. In practice, however, when broker closes TCP connection between successful TCP connection and before AMQP connection is open,
+it means that authentication has failed.
 
 
 

data/docs/Exchanges.textile

@@ -11,12 +11,77 @@ h2. Covered versions
 This guide covers amqp gem v0.8.0 and later.
 
 
+h2. Exchanges in AMQP 0.9.1, briefly
 
-h2. TBD
+TBD
+
+
+h2. Exchange types
+
+TBD
+
+
+h2. Fanout exchanges
 
 TBD
 
 
+h2. Direct exchanges
+
+TBD
+
+
+h2. Topic exchanges
+
+TBD
+
+
+
+h2. Publishing messages
+
+TBD
+
+
+
+h2. Binding queues to exchanges
+
+TBD
+
+
+
+h2. Unbinding queues from exchanges
+
+TBD
+
+
+h2. Deleting exchanges
+
+TBD
+
+
+
+h2. Exchange durability vs Message durability
+
+TBD
+
+
+
+h2. Error handling and recovery
+
+TBD
+
+
+
+h2. Vendor-specific extensions related to exchanges
+
+TBD
+
+
+
+h2.  What to read next
+
+TBD
+
 
 h2. Tell us what you think!
 

data/docs/Queues.textile

@@ -1,9 +1,10 @@
-h1. TBD
+h1. AMQP queues in detail
 
 
 h2. About this guide
 
-TBD
+This guide covers everything related to queues in AMQP 0.9.1, common usage scenarios and how to accomplish typical operations using
+amqp gem.
 
 
 h2. Covered versions
@@ -12,12 +13,535 @@ This guide covers amqp gem v0.8.0 and later.
 
 
 
-h2. TBD
+h2. Queues in AMQP 0.9.1, briefly
+
+h3. What are AMQP queues?
+
+Queues store and forward messages to consumers. They are similar to mailboxes in SMTP.
+Messages flow from producing applications to {file:docs/Exchanges.textile exchanges} that route them
+to queues and finally queues deliver them to consumer applications (or consumer applications fetch messages as needed).
+
+Note that unlike some other messaging protocols/systems, messages are not delivered directly
+to queues. They are delivered to exchanges that route messages to queues using rules
+knows as *bindings*.
+
+AMQP is a programmable protocol, so queues and bindings alike are declared by applications.
+
+
+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
+
+Queues have several attributes associated with them:
+
+ * Name
+ * Exclusivity
+ * Whether queue is auto-deleted when no longer used
+ * Other metadata (aka X-arguments)
+
+These attributes define how queues can be used, what their lifecycle is like and other aspects of queue
+behavior.
+
+amqp gem represents queues as instances of {AMQP::Queue}.
+
+h2. Queue names. Server-named queues. Predefined queues.
+
+Every queue has a name that identifies it. Queue names often contain several segments separated by a dot (.), similarly to how URI
+path segments are separated by a slash (/), although it may be almost any string, with some limitations (see below).
+Applications may pick queue names or ask broker to generate a name for them. To do so, pass *empty string* as queue name argument.
+
+Here is an example:
+
+<pre>
+<code>
+# Declaring a server-named queue using AMQP::Queue constructor
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    AMQP::Queue.new(channel, "", :auto_delete => true) do |queue, declare_ok|
+      puts "#{queue.name} is ready to go. AMQP method: #{declare_ok.inspect}"
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+If you want to declare a queue with a particular name, for example, "images.resize", pass it to Queue class constructor:
+
+<pre>
+<code>
+# Declaring a server-named queue using AMQP::Queue constructor
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    AMQP::Queue.new(channel, "images.resize", :auto_delete => true) do |queue, declare_ok|
+      puts "#{queue.name} is ready to go."
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+Queue names starting with 'amq.' are reserved for internal use by the broker. Attempts to declare queue with a name that violates this
+rule will result in AMQP::IncompatibleOptionsError to be thrown (when queue is re-declared on the same channel object) or channel-level exception
+(when originally queue was declared on one channel and re-declaration with different attributes happens on another channel).
+Learn more in Error handling and recovery section below.
+
+
+
+h2. Common usage scenarios
+
+h2. Queue life-cycles. When use of server-named queues is optimal and when it isn't.
+
+To quote AMQP 0.9.1 spec, there are two common message queue life-cycles:
+
+ * Durable message queues that are shared by many consumers and have an independent existence: i.e. they
+   will continue to exist and collect messages whether or not there are consumers to receive them.
+ * Temporary message queues that are private to one consumer and are tied to that consumer. When the
+   consumer disconnects, the message queue is deleted.
+
+There are some variations on these, such as shared message queues that are deleted when the last of
+many consumers disconnects.
+
+One example of durable message queues is well-known services like event collectors (event loggers).
+They are usually up whether there are services to log anything or not. Other applications know what
+queues they use and can rely on those queues being around all the time, survive broker restarts and
+in general be available should an application in the network need to use them. In this case,
+explicitly named durable queues are optimal and coupling it creates between applications is not
+an issue. Another scenario of a well-known long-lived service is distributed metadata/directory/locking server
+like Apache Zookeeper, Google's Chubby or DNS. Services like this benefit from using well-known, not generated
+queue names, and so do other applications that use them.
+
+Different scenario is in "a cloud settings" when some kind of workers/instances may come online and
+go down basically any time and other applications cannot rely on them being available. Using well-known
+queue names in this case is possible but server-generated, short-lived queues that are bound to
+topic or fanout exchanges to receive relevant messages is a better idea.
+
+Imagine a service that processes an endless stream of events (Twitter is one example). When traffic goes
+up, development operations may spin up additional applications instances in the cloud to handle the load.
+Those new instances want to subscribe to receive messages to process but the rest of the system doesn't
+know anything about them, rely on them being online or try to address them directly: they process events
+from a shared stream and are not different from their peers. In a case like this, there is no reason for
+message consumers to not use queue names generated by the broker.
+
+In general, use of explicitly named or server-named queues depends on messaging pattern your application needs.
+{http://www.eaipatterns.com/ Enterprise Integration Patters} discusses many messaging patterns in depth.
+RabbitMQ FAQ also has a section on {http://www.rabbitmq.com/faq.html#scenarios use cases}.
+
+
+
+h2. Declaring a durable shared queue
+
+To declare a durable shared queue, you pass queue name that is a non-blank string and use :durable option:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+# Declaring a client-named queue using AMQP::Queue constructor
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    AMQP::Queue.new(channel, "images.resize", :durable => true) do |queue, declare_ok|
+      puts "#{queue.name} is ready to go."
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+the same piece of code that uses {AMQP::Channel#queue} for convenience:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+# Declaring a client-named queue using AMQP::Queue constructor
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    channel.queue("images.resize", :durable => true) do |queue, declare_ok|
+      puts "#{queue.name} is ready to go."
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+
+h2. Declaring a temporary exclusive queue
+
+To declare a server-named, exclusive, auto-deleted queue, pass "" (empty string) as queue name and
+use :exclusive and :auto_delete options:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+# Declaring a server-named queue using AMQP::Queue constructor
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    AMQP::Queue.new(channel, "", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      puts "#{queue.name} is ready to go."
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+the same piece of code that uses {AMQP::Channel#queue} for convenience:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+# Declaring a server-named queue using AMQP::Queue constructor
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      puts "#{queue.name} is ready to go."
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+
+
+h2. Binding queues to exchanges
+
+In order to receive messages, a queue needs to be bound to at least one exchange. Most of the time binding is explcit (done by applications).
+To bind a queue to an exchange, use {AMQP::Queue#bind). Argument can be either an {AMQP::Exchange} instance or exchange name:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+# Binding a queue to an exchange
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    exchange = channel.fanout("amq.fanout")
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      queue.bind(exchange) do |bind_ok|
+        puts "Just bound #{queue.name} to #{exchange.name}"
+      end
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+# Binding a queue to an exchange
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    exchange_name = "amq.fanout"
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      queue.bind(exchange_name) do |bind_ok|
+        puts "Just bound #{queue.name} to #{exchange_name}"
+      end
+
+      connection.close {
+        EventMachine.stop { exit }
+      }
+    end
+  end
+end
+</code>
+</pre>
+
+
+h2. Subscribing to receive messages ("push API")
+
+Each queue usually has one or more consumers (message handlers). Without it, queues are not very useful, right?
+To subscribe to receive messages when they arrive to the queue ("start a queue consumer"), one uses {AMQP::Queue#subscribe} method.
+Then when a message arrives, message header and body (aka payload) are passed to handling block:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    exchange = channel.fanout("amq.fanout")
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      queue.bind(exchange).subscribe do |headers, payload|
+        puts "Received a message: #{payload.inspect}. Shutting down..."
+
+        connection.close {
+          EM.stop { exit }
+        }
+      end
+
+      EventMachine.add_timer(0.2) do
+        exchange.publish("Ohai!")
+      end
+    end
+  end
+end
+</code>
+</pre>
+
+h3. Exclusive consumers
+
+TBD
+
+
+
+h2. Fetching messages when needed ("pull API")
+
+AMQP 0.9.1 also provides a way for applications to fetch (pull) messages from the queue only when necessary. For that, use
+{AMQP::Queue#pop}:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    exchange = channel.fanout("amq.fanout")
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      queue.bind(exchange) do |_|
+        puts "Bound. Publishing a message..."
+        exchange.publish("Ohai!")
+      end
+
+      EventMachine.add_timer(0.5) do
+        queue.pop do |response|
+          puts "Fetched a message: #{response.inspect}. Shutting down..."
+
+          connection.close {
+            EM.stop { exit }
+          }
+        end
+      end
+    end
+  end
+end
+</code>
+</pre>
+
+
+TBD
+
+
+h2. Unsubscribing from messages
+
+TBD
+
+
+h2. Unbinding queues from exchanges
+
+To unbind queue from exchange, use {AMQP::Queue#unbind}:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  puts "Connected"
+  AMQP::Channel.new(connection) do |channel, open_ok|
+    puts "Opened a channel"
+    channel.on_error do |arg|
+      raise "Channel-level exception!"
+    end
+    exchange = channel.fanout("amq.fanout")
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      queue.bind(exchange) do |_|
+        puts "Bound"
+      end
+
+      EventMachine.add_timer(0.5) do
+        queue.unbind(exchange) do |_|
+          puts "Unbound. Shutting down..."
+
+          connection.close {
+            EM.stop { exit }
+          }
+        end
+      end # EventMachine.add_timer
+    end # channel.queue
+  end
+end
+</code>
+</pre>
+
+Note that unbinding an exchange queue was never bound to will result in an exception.
+
+
+h2. Purging queues
+
+It is possible to purge (remove all messages from) a queue using {AMQP::Queue#purge):
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  puts "Connected"
+  AMQP::Channel.new(connection) do |channel, open_ok|
+    puts "Opened a channel"
+    channel.on_error do |arg|
+      raise "Channel-level exception!"
+    end
+    exchange = channel.fanout("amq.fanout")
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      queue.purge do |_|
+        puts "Queue now has no messages"
+      end
+
+      EventMachine.add_timer(0.5) do
+        connection.close {
+          EM.stop { exit }
+        }
+      end # EventMachine.add_timer
+    end # channel.queue
+  end
+end
+</code>
+</pre>
+
+Callback is optional. However, remember that this operation takes some time.
+
+
+h2. Deleting queues
+
+To delete a queue, use {AMQP::Queue#delete}:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  puts "Connected"
+  AMQP::Channel.new(connection) do |channel, open_ok|
+    puts "Opened a channel"
+    channel.on_error do |arg|
+      raise "Channel-level exception!"
+    end
+    exchange = channel.fanout("amq.fanout")
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      EventMachine.add_timer(0.5) do
+        queue.delete do
+          puts "Deleted a queue"
+          connection.close {
+            EM.stop { exit }
+          }
+        end
+      end # EventMachine.add_timer
+    end # channel.queue
+  end
+end
+</code>
+</pre>
+
+Callback can be omitted. However, remember that this operation takes some time.
+
+h2. Queue durability vs Message durability
+
+TBD
+
+
+
+h2. Error handling and recovery
 
 TBD
 
 
 
+h2. Vendor-specific extensions related to queues
+
+TBD
+
+
+
+h2.  What to read next
+
+TBD
+
+
 h2. Tell us what you think!
 
 Please take a moment and tell us what you think about this guide on "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp: