amqp 0.8.0.rc13 → 0.8.0.rc14

data/docs/AMQP091ModelExplained.textile

@@ -0,0 +1,322 @@
+# @title Ruby amqp gem: AMQP 0.9.1 Model Explained
+
+h1. AMQP 0.9.1 Model Explained
+
+h2. About this guide
+
+This guide explains AMQP 0.9.1 Model used by RabbitMQ. Understanding the AMQP Model will make a lot of other documentation, both for the Ruby amqp gem and
+RabbitMQ itself, easier to follow.
+
+This guide covers:
+
+ * High-level overview of the AMQP 0.9.1 Model.
+ * Key differences of the AMQP model from some other messaging models.
+ * What are exchanges.
+ * What are queues.
+ * What are bindings.
+ * How AMQP protocol is structured. What are AMQP methods.
+ * What attributes AMQP 0.9.1 messages have.
+ * What are message acknowledgements.
+ * What are negative message acknowledgements.
+ * and a lot of other things.
+
+
+h2. Which versions of the amqp gem does this guide cover?
+
+This guide covers v0.8.0 and later of the "Ruby amqp gem":https://github.com/ruby-amqp/amqp.
+
+
+h2. High-level overview of the AMQP 0.9.1 Model
+
+h3. Brokers & Their Role
+
+AMQP (Advanced Message Queuing Protocol) is a networking protocol which enables conforming client applications to communicate with conforming
+messaging middleware brokers. Brokers receive messages from _producers_ (applications that publish them) and route them to _consumers_ (applications
+that process them).
+
+Brokers are centers of the nervous system, applications are more like limbs.
+
+
+h3. AMQP 0.9.1 Model, briefly
+
+The AMQP 0.9.1 Model has the following view of the world: messages are published by producers to _exchanges_, often compared to post offices or mailboxes. Exchanges then
+distribute message copies to _queues_ using rules called _bindings_. Then AMQP brokers either push messages to _consumers_ subscribed to some queues, or consumers
+fetch/pull messages from queues on demand, as needed.
+
+!https://github.com/ruby-amqp/amqp/raw/master/docs/diagrams/001_hello_world_example_routing.png!
+
+When publishing a message, producers may specify various _message attributes_ (message metadata). Some of this metadata may be used by the broker, some other
+is completely opaque and will only be used by applications that receive the message.
+
+Because networks are not reliable and applications may fail to process messages, the AMQP Model has a notion of
+_message acknowledgements_: when a message is pushed down to a consumer, the consumer _notifies the broker_, either automatically or as soon as application
+developer chooses to. Brokers then will only completely remove message from the queue when they receive a notification for that message (or a group of messages).
+
+In certain situations, for example, when a message cannot be routed, messages may be _returned_ to producers or dropped (or, if broker implements an extension,
+placed into a so-called "dead letter queue"). Producers choose how situations like this are handled by publishing messages with certain parameters.
+
+Queues, exchanges and bindings are commonly referred to as _AMQP entities_.
+
+
+h3. AMQP is a Programmable Protocol
+
+AMQP 0.9.1 is a programmable protocol in the sense that AMQP entities & routing schemes are defined by applications themselves, not a broker administrator. So there are protocol
+operations that declare queues and exchanges, define bindings between them, subscribe to queues and so on.
+
+This gives application developers a lot of freedom but also requires them to be aware of potential definition conflicts. In practice, those definition conflicts
+are rare and often indicate misconfigurations, and it is a good thing that misconfigurations are caught early.
+
+Applications declare AMQP entities they need, define routing schemes necessary and may choose to delete AMQP entities when they are no longer used.
+
+
+
+
+h2. AMQP Exchanges and Exchange Types.
+
+_Exchanges_ are AMQP entities where messages are sent. Exchanges then take a message and route it into one or more (or no) queues. The routing algorithm used
+depends on _exchange type_ and rules called _bindings_. AMQP 0.9.1 brokers typically provide 4 exchange types out of the box:
+
+ * Direct exchange (typically used for for 1-to-1 communication or unicasting)
+ * Fanout exchange (1-to-n communication or broadcasting)
+ * Topic exchange (1-to-n or n-to-m communication, multicasting)
+ * Headers exchange (message metadata-based routing)
+
+but it is possible to extend AMQP 0.9.1 brokers with custom exchange types, for example:
+
+ * x-random exchange (randomly chooses a queue to route incoming messages to)
+ * x-recent-history (a fanout exchange that also keeps N recent messages in memory)
+ * regular expressions based variations of headers exchange
+
+and so on.
+
+Besides the type, exchanges have a number of attributes, most imprortant of which are:
+
+ * Name
+ * Can be durable (information about them is persisted to disk and thus survives broker restarts) or non-durable (information is only kept in RAM)
+ * Can have metadata associated with them on declaration
+
+
+h2. AMQP Queues.
+
+Queues in the AMQP Model are very similar to queues in other messages (and "task queueing") systems: they store messages that are consumed by
+applications. Like AMQP exchanges, AMQP queues have names and durability property but also
+
+ * Can be exclusive (used by only one connection)
+ * Can be automatically deleted when last consumer unsubscribes
+ * Can have metadata associated with them on declaration (some brokers use it to implement features like message TTL and so on)
+
+
+
+h2. AMQP Bindings.
+
+Bindings are rules that exchanges use (among other things) to route messages to queues. To instruct an exchange E to route messages to a queue Q,
+Q has to _be bound_ to E. Bindings may have an optional _routing key_ attribute used by some exchange types. The purpose of the routing key is to
+selectively match only specific (matching) messages published to an exchange to the bound queue. In other words, the routing key acts like a filter.
+
+
+
+h2. AMQP Message Consumers.
+
+Storing messages in queues is useless unless applications can _consume_ them. In the AMQP 0.9.1 Model, there are two ways for applications to do it:
+
+ * Have messages pushed to them ("push API")
+ * Fetch messages as needed ("pull API")
+
+With the "push API", applications have to indicate interest in consuming messages from a particular queue. When they do so, we say that they _register a consumer_
+(or, simply put, _subscribe to a queue_). It is possible to have more than one consumer per queue or to register an _exclusive consumer_ (the only consumer on
+the queue).
+
+Each consumer (subscription) has an identifier called _consumer tag_. It can be used to unsubscribe from messages. Consumer tags are just strings.
+
+
+
+h2. AMQP Message Attributes and Payload.
+
+Messages in the AMQP Model have _attributes_. Some attributes are so common that AMQP 0.9.1 spec defines them and application developers don't have to think
+about exact attribute name. Some examples are
+
+ * Content type
+ * Content encoding
+ * Routing key
+ * Delivery mode (persistent or not)
+ * Message priority
+ * Message publishing timestamp
+ * Expiration period
+ * Producer application id
+
+Some attributes are used by AMQP brokers, but most are up to interpretation by applications that receive them. Some attributes are optional and known
+as _headers_. They are similar to X-Headers in HTTP. Message attributes are set when message is published.
+
+AMQP messages also have _payload_ (data they carry). Brokers treat this data as opaque (it is not modified nor used by them). It is possible for messages to only have attributes
+and no body. It is common to use serialization formats like JSON, Thrift, Protocol Buffers, MessagePack and so on to serialize structured data
+and publish it as AMQP message payload.
+
+
+
+h2. AMQP Message Acknowledgements.
+
+Since networks are unreliable and applications fail, it is often necessary to have some kind of "processing acknowledgements". Sometimes it is only
+necessary to acknowledge the fact that message has been received, sometimes acknowledgements mean that message was validated & processed by consumer,
+for example, verified to have mandatory data and persisted to a data store or indexed.
+
+Because this situation is so common, AMQP 0.9.1 has a built-in feature called _message acknowledgements_ (sometimes referred to as _acks_) that consumer
+use to confirm message delivery and/or processing. If an application crashes (AMQP broker notice this when connection is closed), if acknowledgement for a
+message was not received by AMQP broker, the message is re-queued (and possibly immediately delivered to another consumer, if any).
+
+Having acknowledgements built into the protocol helps developers to build more robust software.
+
+
+
+h2. AMQP 0.9.1 Methods
+
+AMQP 0.9.1 is structured as a number of _methods_. Methods are operations (like HTTP methods) and have nothing in common with methods in object-oriented programming
+languages. AMQP methods are grouped into _classes_. Classes are just logical groupings of AMQP methods. "AMQP 0.9.1 reference":http://www.rabbitmq.com/amqp-0-9-1-reference.html can be found on
+the RabbitMQ website.
+
+Lets take a look at the _exchange.*_ class, a group of methods related to operations on exchanges. It includes the following operations:
+
+
+ * exchange.declare
+ * exchange.declare-ok
+ * exchange.delete
+ * exchange.delete-ok
+
+(note that RabbitMQ site reference also includes RabbitMQ-specific extensions to the exchange.* class that we won't discuss in this guide).
+
+The operations above form logical pairs: *exchange.declare* and *exchange.declare-ok*,
+*exchange.delete* and *exchange.delete-ok*. These operations are "requests" (sent by clients) and "responses" (sent by
+brokers in response to aforementioned "requests").
+
+So first, client asks broker to declare a new exchange using *exchange.declare* method:
+
+!https://img.skitch.com/20110720-c4qjdhmdrih9bn56npqnic4die.jpg!
+
+As demonstrated on the diagram above, *exchange.declare* carries several _parameters_. They let client specify exchange name,
+type, durability flag and so on.
+
+And if the operation succeeds, broker responds with *exchange.declare-ok* method:
+
+!https://img.skitch.com/20110720-m4ptjbnex2sa52g6wdwj3e9ahm.jpg!
+
+*exchange.declare-ok* does not carry any parameters except for the channel number (channelswill be described later in this guide).
+
+Event sequence is very similar for another methods pair, *queue.declare* and *queue.declare-ok*:
+
+!https://img.skitch.com/20110720-tmxswrie71ubb5m5nh8n17idhk.jpg!
+
+!https://img.skitch.com/20110720-g67urxg75c71qtwhwsjs684323.jpg!
+
+Not all AMQP methods have counterparts. Some (*basic.publish* being the most widely used one) do not have corresponding "response" methods
+and some others (*basic.get*, for example) have more than one possible "response".
+
+
+
+h2. AMQP Connections.
+
+AMQP connections are typically long-lived. AMQP is an application level protocol that uses TCP for reliable delivery. AMQP connections use
+authentication and can be protected using TLS (SSL). When application no longer needs to be connected to AMQP broker, it should gracefully
+close AMQP connection instead of abruptly closing the underlying TCP connection.
+
+
+
+h2. AMQP Channels.
+
+Some applications need multiple connections to AMQP broker. It is, however, undesirable to keep many TCP connections open at the same time
+because doing so consumes system resources and makes it more difficult to configure firewalls. AMQP 0.9.1 connections are multiplexed with
+_channels_ that can be thought of as "lightweight connections that share a single TCP connection".
+
+For applications that use multiple threads/processes/etc for processing, it is very common to open a new channel per thread (process, etc)
+and *not share* channels between them.
+
+Because communication on a particular channel is completely separate from communication on a separate channel, every AMQP method also carries a channel number that clients
+use to figure out what channel this method is for (and thus, what event handler needs to be invoked, for example).
+
+
+
+
+h2. AMQP Virtual Hosts (vhosts).
+
+To make it possible for a single broker to host multiple isolated "environments" (groups of users, exchanges, queues and so on), AMQP includes concept
+of _virtual hosts_ (vhosts). They are similar to virtual hosts used by many popular Web servers and provide completely isolated environments
+in which AMQP entities live. AMQP clients specify what vhosts they want to use during AMQP connection negotiation.
+
+AMQP 0.9.1 vhost can be any non-blank string.
+
+
+
+h2. AMQP is Extensible
+
+AMQP 0.9.1 has several extension points:
+
+ * Custom exchange types let developers implement routing schemes that exchange types provided out-of-the-box do not cover well, for example, geodata-based routing.
+ * Declaration of exchanges and queues can include additional attributes broker can use. For example, per-queue message TTL in RabbitMQ is implemented this way.
+ * Broker-specific extensions to the protocol. See, for example, "extensions RabbitMQ implements":http://www.rabbitmq.com/extensions.html.
+ * New AMQP 0.9.1 method classes can be introduced.
+
+These features make it even more flexible and applicable to a very broad range of problems.
+
+
+
+
+h2. Key differences from some other messaging models
+
+Key difference to understand about the AMQP 0.9.1 Model is that *messages are not sent to queues. They are sent to exchanges that route them to
+queues according to rules called "bindings"*. This means that routing is primarily handled by AMQP brokers and not applications themselves.
+
+TBD
+
+
+
+h2. Wrapping up
+
+This is the end of the AMQP 0.9.1 Model tutorial. Congratulations! Armed with this knowledge, you will find it easy to follow the rest of
+the amqp gem documentation as well as rabbitmq.com documentation and "rabbitmq-discuss mailing list":http://groups.google.com/group/rabbitmq-discuss
+
+To stay up to date with amqp gem development, "follow @rubyamqp on Twitter":http://twitter.com/rubyamqp and "join our mailing list":http://groups.google.com/group/ruby-amqp.
+
+
+
+
+h2. What to read next
+
+Documentation is organized as a number of {file:docs/DocumentationGuidesIndex.textile documentation guides}, covering all kinds of
+topics from {file:docs/Exchanges.textile use cases for various exchange types} to {file:docs/ErrorHandling.textile error handling} and
+{file:docs/VendorSpecificExchanges.textile Broker-specific AMQP 0.9.1 extensions}.
+
+We recommend that you read the following guides next, if possible, in this order:
+
+ * {file:docs/ConnectingToTheBroker.textile Connection to the broker}. This guide explains how to connect to an AMQP broker and how to integrate the amqp gem into standalone and Web applications.
+ * {file:docs/Queues.textile Working With Queues}. This guide focuses on features that consumer applications use heavily.
+ * {file:docs/Exchanges.textile Working With Exchanges}. This guide focuses on features that producer applications use heavily.
+ * {file:docs/PatternsAndUseCases.textile Patterns & Use Cases}. This guide focuses implementation of "common messaging patterns":http://www.eaipatterns.com/ using AMQP Model features as building blocks.
+ * {file:docs/ErrorHandling.textile Error Handling & Recovery}. This guide explains how to handle protocol errors, network failures and other things that may go wrong in real world projects.
+
+If you are migrating your application from earlier versions of the amqp gem (0.6.x and 0.7.x), to 0.8.x and later, there is the
+{file:docs/08Migration.textile amqp gem 0.8 migration guide}.
+
+
+h2. Tell us what you think!
+
+Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.
+ Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is
+key to making the documentation better.
+
+If, for some reason, you cannot use the communication channels mentioned above, you can "contact the author of the guides 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 = 'amqp091_model_explained';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/AMQP091ModelExplained.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/Bindings.textile

@@ -2,10 +2,10 @@
 
 h1. TBD
 
-
 h2. About this guide
 
-TBD
+This guide covers bindings in AMQP 0.9.1, what they are, what role do they play and how to accomplish typical operations using
+Ruby amqp gem.
 
 
 h2. Covered versions
@@ -14,7 +14,27 @@ This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and la
 
 
 
-h2. TBD
+h2. Bindings in AMQP 0.9.1
+
+TBD
+
+
+h2. One day in life of an AMQP 0.9.1 message
+
+TBD
+
+
+h2. Binding queues to exchanges
+
+TBD
+
+
+h2. Unbinding queues from exchanges
+
+TBD
+
+
+h2. Binding attributes
 
 TBD
 
@@ -22,7 +42,7 @@ 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:
+Please take a moment and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
 what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
 key to making documentation better.
 

data/docs/Clustering.textile

@@ -22,7 +22,7 @@ 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:
+Please take a moment and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
 what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
 key to making documentation better.
 

data/docs/ConnectingToTheBroker.textile

@@ -5,23 +5,23 @@ 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,
+This guide covers connection to an AMQP broker from standalone and Web applications,
 connection error handling, authentication failure handling and related issues.
 
 
-h2. Covered versions
+h2. Which versions of the amqp gem does this guide cover?
 
-This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
+This guide covers v0.8.0 and later of the "Ruby amqp gem":http://github.com/ruby-amqp/amqp.
 
 
 
 h2. Terminology
 
-In this guide we define standalone application as application that does not run on
+In this guide we define a standalone application as an application that does not run on
 a Web server like Unicorn or Passenger. The key difference is that these applications
-control main Ruby VM thread and often use it to run EventMachine event loop. When
-amqp gem is used inside of a Web applications, main thread is occupied by Web application
-server and code required to establish connection to AMQP broker needs to be a little
+control the main Ruby VM thread and often use it to run the EventMachine event loop. When
+the amqp gem is used in a Web application, the main thread is occupied by the Web application
+server and the code required to establish a connection to an AMQP broker needs to be a little
 bit different.
 
 
@@ -35,7 +35,7 @@ Connection parameters (host, port, username, vhost and so on) can be passed in t
 
 h3. Using a hash
 
-Hash options amqp gem will recognize are
+Hash options that the amqp gem will recognize are
 
  * :host
  * :port
@@ -70,7 +70,7 @@ h3. Using connection strings
 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
+while the schemes share the same basic idea, they differ in some
 details.  This implementation aims to encourage URIs that work
 as widely as possible.
 
@@ -99,23 +99,23 @@ 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 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/%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/%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/foo/bar")  # => ArgumentError
 </code>
 </pre>
 
 
-h2. Starting event loop & connecting in standalone applications
+h2. Starting the event loop and connecting in standalone applications
 
 h3. EventMachine event loop
 
-amqp gem uses "EventMachine":http://rubyeventmachine.com under the hood and needs EventMachine
-event loop to be running in order to connect to AMQP broker or send any data. This means that
-before connecting to AMQP broker, we need to _start EventMachine reactor_ (get the event loop
+The amqp gem uses "EventMachine":http://rubyeventmachine.com under the hood and needs an EventMachine
+event loop to be running in order to connect to an AMQP broker or to send any data. This means that
+before connecting to an AMQP broker, we need to _start the EventMachine reactor_ (get the event loop
 going). Here is how to do it:
 
 <pre>
@@ -128,14 +128,14 @@ end
 </code>
 </pre>
 
-"EventMachine.run":http://eventmachine.rubyforge.org/EventMachine.html#M000461 will block current thread until event loop is stopped.
-Standalone applications often can afford starting event loop on the main thread. If you have no experience with threading, this is a
-recommended way.
+"EventMachine.run":http://eventmachine.rubyforge.org/EventMachine.html#M000461 will block the current thread until the event loop is stopped.
+Standalone applications often can afford to start the event loop on the main thread. If you have no experience with threading, this is a
+recommended way to proceed.
 
 
 h3. Using AMQP.connect with a block
 
-Once event loop is running, {AMQP.connect} method will attempt to connect to the broker. It can be used in two ways. Here is the
+Once the event loop is running, the {AMQP.connect} method will attempt to connect to the broker. It can be used in two ways. Here is the
 first one:
 
 <pre>
@@ -151,13 +151,13 @@ end
 </code>
 </pre>
 
-{AMQP.connect} takes a block that will be executed as soon as AMQP connection is open (TCP connection was set up,
-authentication succeeded, broker and client finished negotiating connection parameters like max frame size).
+{AMQP.connect} takes a block that will be executed as soon as the AMQP connection is open. In order for a connection to be opened a TCP connection has to be set up,
+authentication has to succeed, and the broker and client need to complete negotiation of connection parameters like max frame size.
 
 
 h3. Using AMQP.connect without a callback
 
-Alternative way of connecting is this:
+An alternative way of connecting is this:
 
 <pre>
 <code>
@@ -166,14 +166,14 @@ require "amqp"
 EventMachine.run do
   # using AMQP.connect with a block
   client = AMQP.connect(:host => "hub.megacorp.internal", :username => "hedgehog", :password => "t0ps3kr3t")
-  # connection is not yet open, however, amqp gem will delay
-  # channel operations until after connection is open. However,
+  # connection is not yet open, however, amqp gem will delay channel
+  # operations until after the connection is open. Bear in mind that
   # amqp gem cannot solve every possible race condition so be careful
 end
 </code>
 </pre>
 
-If you do not need to assign returned value to a variable, "block version" is recommended because it eliminates issues that may
+If you do not need to assign the returned value to a variable, then the "block version" is recommended because it eliminates issues that may
 arise from attempts to use a connection object that is not fully opened yet. For example, handling of authentication failures is simpler
 with the block version, as we will see in the following sections.
 
@@ -181,7 +181,7 @@ with the block version, as we will see in the following sections.
 
 h3. Using AMQP.start
 
-EventMachine.run and {AMQP.connect} with a block is such a common combination that amqp gem provides a shortcut:
+EventMachine.run and {AMQP.connect} with a block is such a common combination that the amqp gem provides a shortcut:
 
 <pre>
 <code>
@@ -194,20 +194,20 @@ end
 </pre>
 
 As these examples demonstrate, {AMQP.connect} and {AMQP.start} accept either a Hash of connection options or a connection URI string.
-See reference documentation for each method to learn all the options they accept and what the default values are.
+See the reference documentation for each method to learn all of the options that they accept and what the default values are.
 
 
 h3. On Thread#sleep use
 
-When not passing a block to {AMQP.connect}, it is tempting to "give connection some time to get through" by using Thread#sleep. Unless you are
-running event loop in a separate thread, don't do this. Thread#sleep blocks current thread so if event loop is running the very same current thread,
-blocking it _will also block the event loop_. *When event loop is blocked, no data is sent or received, so connection does not proceed.*
+When not passing a block to {AMQP.connect}, it is tempting to "give the connection some time to become established" by using Thread#sleep. Unless you are
+running the event loop in a separate thread, please do not do this. Thread#sleep blocks the current thread so that if the event loop is running in the current thread,
+blocking the thread _will also block the event loop_. *When the event loop is blocked, no data is sent or received, so the connection does not proceed.*
 
 
 h3. Detecting TCP connection failures
 
-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
+When applications connect to the broker, they need to handle connection failures. Networks are not 100% reliable and even with modern system configuration tools,
+like "Chef":http://http://www.opscode.com/chef or "Puppet":http://http://www.puppetlabs.com, misconfigurations can happen. Also, the broker might be down for some reason. Ideally, 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>
@@ -240,11 +240,11 @@ 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.
+{AMQP.connect} (and {AMQP.start}) will raise {AMQP::TCPConnectionFailed} if the connection fails. Code that catches the error can write to a log
+about the issue or use retry to execute the 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 error over and over again. TBD: failover, connection to the cluster.
 
-Alternative way of handling connection failure is with an errback (a callback for specific kind of error):
+An alternative way of handling connection failure is with an _errback_ (a callback for a specific kind of error):
 
 <pre>
 <code>
@@ -274,9 +274,9 @@ end
 </code>
 </pre>
 
-:on_tcp_connection_failure option accepts any object that responds to #call.
+the ":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
+If you connect to the broker from code in a class (as opposed to top-level scope in a script), Object#method can be used to pass an object method as a handler
 instead of a Proc.
 
 TBD: provide an example
@@ -284,7 +284,7 @@ TBD: provide an example
 
 h3. Detecting authentication failures
 
-Another reason why connection may fail is authentication failure. Handling authentication failure is very similar to handling initial TCP
+A connection may also fail due to authentication failure. Handling authentication failure is very similar to handling an initial TCP
 connection failure:
 
 <pre>
@@ -354,21 +354,21 @@ 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,
+In case you are wondering why the callback name has "possible" in it, {http://bit.ly/mTr1YN AMQP 0.9.1 spec} requires broker implementations to
+simply close the TCP connection without sending any more data when an exception, such as authentication failure, occurs before the AMQP connection
+is open. In practice, however, when a broker closes a TCP connection after a successful TCP connection has been established but before an AMQP connection is open,
 it means that authentication has failed.
 
 
 
-h2. Starting event loop & connecting in Web applications (Ruby on Rails, Sinatra, Merb, Rack)
+h2. Starting the event loop and connecting in Web applications (Ruby on Rails, Sinatra, Merb, Rack)
 
-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.
+Web applications are different from standalone applications in that the main thread is occupied by a Web/application server like Unicorn
+or Thin, so you need to start the EventMachine reactor before you attempt to use {AMQP.connect}.
+In a Ruby on Rails application, probably the best place for this is in the initializer (like config/initializers/amqp.rb). For Merb applications it is config/init.rb.
+For Sinatra and pure Rack applications, place it next to the other configuration code.
 
-Next we are going to discuss issues specific to particular Web servers.
+Next, we are going to discuss issues specific to particular Web servers.
 
 
 
@@ -377,18 +377,18 @@ h3. Using Ruby amqp gem with Unicorn
 h4. Unicorn is a pre-forking server
 
 "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:
+has several gotchas associated with it, two of which affect EventMachine and the "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)
+ * The fact that a "forked child process only inherits one thread":http://bit.ly/fork-and-threads and therefore the EventMachine thread is not inherited
 
-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.
+To avoid both problems, start the EventMachine reactor and AMQP connection *after* the master process forks workers. The master Unicorn process never serves HTTP requests and usually
+does not need to hold an AMQP connection. Next, let us see how to spin up the EventMachine reactor and connect to the broker after Unicorn forks a worker.
 
 
-h4. Starting EventMachine reactor and connecting to the broker after Unicorn forks worker processes
+h4. Starting the 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):
+Unicorn lets you specify a configuration file to use. In that file you define a callback that Unicorn runs after it forks worker process(es):
 
 <pre>
 <code>
@@ -427,38 +427,53 @@ end
 </code>
 </pre>
 
-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.
+In the example above we start the EventMachine reactor in a separate thread, block the current thread for 1 second to let the event loop spin up and then
+connect to the AMQP broker on the next event loop tick. Publishing several warmup messages on boot is a good idea because it
+allows the early detection of issues that forking may cause.
 
-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.
+Note that a configuration file can easily be used in development environments because, 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.
 
-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.
+An "example Ruby on Rails application that uses the Ruby amqp gem and Unicorn":http://bit.ly/ruby-amqp-gem-example-with-ruby-on-rails-and-unicorn is available on GitHub.
 
 
 
 
-h3. Using Ruby amqp gem with Passenger
+h3. Using the 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
+"Phusion Passenger":http://www.modrails.com is also a pre-forking server, and just as with Unicorn, the EventMachine reactor and AMQP connection should be started *after* it forks worker
+processes. The Passenger documentation has "a section":http://bit.ly/passenger-forking-gotchas that explains how to avoid problems related to the behavior of the fork(2) system
 call, namely:
 
  * 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)
+ * The fact that a "forked child process only inherits one thread":http://bit.ly/fork-and-threads and therefore the EventMachine thread is not inherited
 
-TBD: if you are a Passenger user, please help us write the rest of this section!
+h4. Using an event handler to spawn one amqp connection per worker
 
+Passenger provides a hook that you should use for spawning AMQP connections: 
 
+<pre>
+<code>
+if defined?(PhusionPassenger) # otherwise it breaks rake commands if you put this in an initializer
+  PhusionPassenger.on_event(:starting_worker_process) do |forked|
+    if forked
+      # We're in a smart spawning mode
+      # Now is a good place to connect to the broker
+    end
+  end
+end
+</code>
+</pre>
+
+Basically, the recommended default smart spawn mode works exactly the same as in Unicorn (with all of the same common pitfalls). An "example application":http://bit.ly/ruby-amqp-gem-example-with-ruby-on-rails-and-passenger is available on github.
 
-h3. Using Ruby amqp gem with Thin and Goliath
+h3. Using the Ruby amqp gem with Thin and Goliath
 
-h4. Thin and Goliath start EventMachine reactor for you, but there is a little nuance
+h4. Thin and Goliath start the 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:
+If you use "Thin":http://code.macournoyer.com/thin/ or "Goliath":https://github.com/postrank-labs/goliath/, you are all set because those two servers use EventMachine under the hood.
+There is no need to start the EventMachine reactor. However, depending on the application server, its version, the version of the framework and Rack middleware being used,
+EventMachine reactor start may be slightly delayed. To overcome this potential difficulty, use EventMachine.next_tick to delay connection until after the reactor is actually running:
 
 <pre>
 <code>
@@ -466,33 +481,34 @@ EventMachine.next_tick { AMQP.connect(...) }
 </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.
+So, in case the EventMachine reactor is not yet running on server/application boot, the connection will not fail but will instead wait for the reactor to start.
+Thin and Goliath are not pre-forking servers so there is no need to re-establish the connection as you do with Unicorn and Passenger.
 
 
 
 
-h2. If it just doesn't work: troubleshooting
+h2. If it just does not 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
+If you have read this guide and your issue is still unresolved, check our {file:docs/Troubleshooting.textile Troubleshooting guide} before asking on the mailing list.
 
 
 
 
 h2. What to read next
 
- * {file:docs/Queues.textile Queues}
+ * {file:docs/Queues.textile Working With Queues}. This guide focuses on features consumer applications use heavily.
+ * {file:docs/Exchanges.textile Working With Exchanges}. This guide focuses on features producer applications use heavily.
  * {file:docs/ErrorHandling.textile Error handling}
- * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)} (if you want to use SSL encrypted connection to the broker)
+ * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)} (if you want to use an SSL encrypted connection to the broker)
 
 
 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:
-what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
-key to making documentation better.
+Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.
+ Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is
+key to making the 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
+If, for some reason, you cannot use the communication channels mentioned above, you can "contact the author of the guides directly":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation