amqp 0.8.0.rc14 → 0.8.0.rc15

data/.travis.yml

@@ -4,10 +4,10 @@ script: "bundle exec rake spec:ci"
 before_script: ./bin/ci/before_build.sh
 rvm:
   - 1.8.7
-  - 1.9.2
-  - jruby
-  - ree
   - rbx-2.0
+  - jruby
+  - 1.9.2
+  - 1.9.3
 gemfile:
   - Gemfile
   - gemfiles/eventmachine-pre

data/Gemfile

@@ -18,16 +18,19 @@ custom_gem "eventmachine"
 custom_gem "amq-client",   :git => "git://github.com/ruby-amqp/amq-client.git",   :branch => "master"
 custom_gem "amq-protocol", :git => "git://github.com/ruby-amqp/amq-protocol.git", :branch => "master"
 
-group(:development) do
+group :development do
   gem "yard", ">= 0.7.2"
   # yard tags this buddy along
   gem "RedCloth",  :platform => :mri
-  gem "rdiscount", :platform => :ruby
-  gem "yajl-ruby", :platform => :ruby
 
-  # To test event loop helper and various Rack apps
-  gem "thin",    :platform => :ruby
-  gem "unicorn", :platform => :ruby
+  platform :ruby do
+    gem "rdiscount"
+    gem "yajl-ruby"
+
+    # To test event loop helper and various Rack apps
+    gem "thin"
+    gem "unicorn"
+  end
 
   gem "changelog"
 end

data/README.md

@@ -1,16 +1,16 @@
 # About Ruby amqp gem #
 
 Ruby amqp gem is a widely used, feature-rich, well-maintained asynchronous AMQP 0.9.1 client with batteries included.
-This library works with Ruby 1.8.7 (p174 and p334), Ruby 1.9.2, [JRuby](http://jruby.org) (highly recommended to Microsoft Windows users), [REE](http://www.rubyenterpriseedition.com) and [Rubinius](http://rubini.us), and is licensed under the [Ruby License](http://www.ruby-lang.org/en/LICENSE.txt)
+This library works with Ruby 1.8.7 (*except for p249*, see the FAQ), Ruby 1.9.2, Ruby 1.9.3-preview1, [JRuby](http://jruby.org), [Rubinius](http://rubini.us) as well as [REE](http://www.rubyenterpriseedition.com), and is licensed under the [Ruby License](http://www.ruby-lang.org/en/LICENSE.txt)
 
-Versions 0.8.0.RC13 and later of amqp gem implement [AMQP 0.9.1](http://bit.ly/amqp-model-explained) (see also [AMQP 0.9.1 spec document](http://bit.ly/hw2ELX)) and support [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
+0.8.0.RCs and later versions of amqp gem implement [AMQP 0.9.1](http://bit.ly/amqp-model-explained) (see also [AMQP 0.9.1 spec document](http://bit.ly/hw2ELX)) and support [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
 
 [![Continuous Integration status](https://secure.travis-ci.org/ruby-amqp/amqp.png)](http://travis-ci.org/ruby-amqp/amqp)
 
 
 ## I know what AMQP is, how do I get started? ##
 
-See [Getting started with amqp gem](http://bit.ly/getting-started-with-amqp-ruby-gem) and other [documentation guides](http://bit.ly/amqp-gem-docs).
+See [Getting started with amqp gem](http://bit.ly/getting-started-with-amqp-ruby-gem) and other [documentation guides](http://bit.ly/amqp-gem-docs). We recommend that you read [AMQP 0.9.1 Model Explained](http://bit.ly/amqp-model-explained), too.
 
 
 
@@ -95,11 +95,11 @@ On other OSes or [JRuby](http://jruby.org):
 
     EventMachine.run do
       connection = AMQP.connect(:host => '127.0.0.1')
-      puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
+      puts "Connecting to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
 
       channel  = AMQP::Channel.new(connection)
       queue    = channel.queue("amqpgem.examples.hello_world", :auto_delete => true)
-      exchange = channel.direct("")
+      exchange = channel.default_exchange
 
       queue.subscribe do |payload|
         puts "Received a message: #{payload}. Disconnecting..."
@@ -136,8 +136,8 @@ should [file to us](http://github.com/ruby-amqp/amqp/issues). Or just complain t
  * Blabbr, a Twitter-like example of broadcasting (1-to-many communication)
  * Weathr, an example of sophisticated routing capabilities AMQP 0.9.1 has to offer (1-to-many or many-to-many communication)
 
-all in under 20 minutes. Check it out! If something isn't clear, every guide explains how to contact documentation authors at the bottom
-of the page.
+all in under 20 minutes. [AMQP 0.9.1 Protocol Tutorial](http://bit.ly/amqp-model-explained) will introduce you to protocol concepts
+in less than 5 minutes.
 
 
 ### Examples ###
@@ -160,11 +160,16 @@ error handing & recovery, broker-specific extensions, TLS support, troubleshooti
 
 
 
-
 ## How to use AMQP gem with Ruby on Rails, Merb, Sinatra and other web frameworks ##
 
-We cover this subject for multiple Ruby application servers in [Connecting to the broker guide](http://bit.ly/kFCVQU), take a look and let us know
-what wasn't clear.
+We cover Web application integration for multiple Ruby Web servers in [Connecting to the broker guide](http://bit.ly/kFCVQU).
+
+
+
+## Migration from amqp gem 0.6.x and 0.7.x
+
+Upgrading from amqp gem 0.6.x and 0.7.x to to 0.8.0.RCs is straightforward, please see [amqp gem 0.8.0 migration guide](http://bit.ly/amqp-gem-080-migration).
+The same guide explains amqp gem versions history and why you would want to upgrade.
 
 
 
@@ -208,6 +213,7 @@ Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.
 
 ### AMQP resources ###
 
+ * [AMQP 0.9.1 Model Explained](http://bit.ly/amqp-model-explained)
  * [RabbitMQ tutorials](http://www.rabbitmq.com/getstarted.html) that demonstrate interoperability
  * [Wikipedia page on AMQP](http://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol)
  * [AMQP quick reference](http://www.rabbitmq.com/amqp-0-9-1-quickref.html)
@@ -242,8 +248,8 @@ In order to make code like the following (pseudo-synchronous) work
     ex.publish(some_data)
 
 and not be affected by this [Ruby 1.8.7-p249-specific bug (super called outside of method)](http://bit.ly/iONBmH), we need to
-avoid any inheritance for key amqp gem classes: Channel, Queue, Exchange. This will take a moderate refactoring effort, and
-is likely to happen in 0.8.0.RC15.
+avoid any inheritance for key amqp gem classes: Channel, Queue, Exchange, Consumer. This will take a significant refactoring effort and
+we do not expect this to change at this time.
 
 
 ### How does amqp gem relate to amq-client gem, amq-protocol and libraries like bunny? ###

data/amqp.gemspec

@@ -23,8 +23,8 @@ Gem::Specification.new do |s|
 
   # Dependencies
   s.add_dependency "eventmachine"
-  s.add_dependency "amq-client",   ">= 0.8.0"
-  s.add_dependency "amq-protocol", ">= 0.8.0"
+  s.add_dependency "amq-client",   "~> 0.8.2"
+  s.add_dependency "amq-protocol", "~> 0.8.0"
 
   begin
     require "changelog"

data/bin/docup

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+yard server --reload

data/docs/08Migration.textile

@@ -8,6 +8,8 @@ h2. About this guide
 This guide explains how (and why) applications that use amqp gem versions 0.6.x and 0.7.x should migrate
 to 0.8.0.RCs and future versions. It also outlines deprecated features, when and why they will be removed.
 
+This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
+
 
 h2. Covered versions
 
@@ -129,24 +131,82 @@ MQ class and class methods that use implicit connection (MQ.queue and so on) wil
 
 h2. MQ class is now AMQP::Channel
 
-TBD
+MQ class was renamed to AMQP::Channel to follow established {file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 terminology}. Implicit per-thread
+channels are deprecated so code like this:
+
+<pre>
+<code>
+# amqp gem 0.6.x code style: connection is implicit, channel is implicit. Error handling & recovery are thus
+# not possible.
+# Deprecated, do not use.
+MQ.queue("search.indexing")
+
+# same for exchanges. Deprecated, do not use.
+MQ.direct("services.imaging")
+MQ.fanout("services.broadcast")
+MQ.topic("services.weather_updates")
+</code>
+</pre>
+
+<pre>
+<code>
+# connection object lets you define error handlers
+connection = AMQP.connect(:vhost => "myapp/production", :host => "192.168.0.18")
+# channek object lets you define error handlers and use multiple channels per application,
+# for example, one per thread
+channel    = AMQP::Channel.new(connection)
+# AMQP::Channel#queue has unchanged otherwise
+channel.queue("search.indexing")
+
+# exchanges examples
+channel.direct("services.imaging")
+channel.fanout("services.broadcast")
+channel.topic("services.weather_updates")
+</code>
+</pre>
+
+<span class="note">
+MQ.queue, MQ.direct, MQ.fanout and MQ.topic methods will be removed before 1.0 release. Use
+instance methods on AMQP::Channel (AMQP::Channel#queue, AMQP::Channel#direct, AMQP::Channel#default_exchange
+and so on) instead.
+</span>
 
 
 h2. MQ::Queue is now AMQP::Queue
 
-TBD
+MQ::Queue is now AMQP::Queue. All the methods from 0.6.x series are still available.
+
+<span class="note">
+MQ::Queue alias will be removed before 1.0 release. Please switch to AMQP::Queue.
+</span>
 
 
 h2. MQ::Exchange is now AMQP::Exchange
 
-TBD
+MQ::Exchange is now AMQP::Exchange. All the methods from 0.6.x series are still available.
+
+<span class="note">
+MQ::Exchange alias will be removed before 1.0 release. Please switch to AMQP::Exchange.
+</span>
+
 
 
 h2. MQ::Header is now AMQP::Header
 
-TBD
+MQ::Header is now AMQP::Header. If you code has any type checks or case matches on
+MQ::Header, it needs to change to AMQP::Header.
 
 
+h2. AMQP.error is deprecated
+
+Catch-all solutions for error handling are very difficult to use. Automatic recovery and fine-grained
+event handling is also not possible. amqp gem 0.8.0.RC14 and later includes fine-grained {file:docs/ErrorHandling.textile Error Handling and Recovery API}
+that is both significantly easier to use in real-world cases but also makes automatic recovery mode possible.
+
+<span class="note">
+AMQP.error method will be removed before 1.0 release.
+</span>
+
 
 h2. MQ::RPC is deprecated
 
@@ -210,7 +270,9 @@ AMQP::Protocol::* classes were removed in the the amqp gem 0.8.0 development cyc
 
 
 
-h2. TBD
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
 
 
 

data/docs/AMQP091ModelExplained.textile

@@ -4,74 +4,92 @@ 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 explains the 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 work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available "on Github":https://github.com/ruby-amqp/amqp/tree/master/docs.
 
-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.
+h3. What this guide covers
 
+This guide covers:
 
-h2. Which versions of the amqp gem does this guide cover?
+ * High-level overview of the AMQP 0.9.1 Model
+ * Key differences of the AMQP model from some other messaging models
+ * What exchanges are
+ * What queues are
+ * What bindings are
+ * How AMQP protocol is structured and what AMQP methods are
+ * What attributes AMQP 0.9.1 messages have
+ * What message acknowledgements are
+ * What negative message acknowledgements are
+ * and a lot of other things
 
-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
+h2. High-level overview of AMQP 0.9.1 and the AMQP Model
 
-h3. Brokers & Their Role
+h3. What is AMQP
 
 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
+messaging middleware brokers.
+
+
+h3. Why AMQP was created
+
+Messaging solutions have been around since the 1970s with a view to solving the problem of integrating incompatible products from diverse vendors. Without the use of messaging middleware, the integration of heterogenous systems has proved to be very expensive and complex. However, messaging solutions, such as IBM Websphere MQ and Tibco Enterprise Message Service, are also very costly and tend to be exclusively employed by large companies (who can afford them), especially those in the financial services industry.
+
+There is also a problem with interoperability between messaging solutions. Vendors have created their own proprietary messaging protocols which do not interoperate with others, therefore resulting in 'vendor lock-in'.
+
+AMQP has multiple design goals but two of the most important are:
+
+ * To produce an open standard for messaging middleware
+ * To enable interoperability between various technologies and platforms
+
+There is a lot of software running on many operating systems built with multiple programming languages running on
+various hardware architectures and virtual machines. AMQP not only makes it possible for these disparate systems to
+communicate with one another, but also enables different products that implement AMQP to exchange information.
+
+
+h3. Brokers and their role
+
+Messaging 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.
+If you imagine the human body, then brokers would be equivalent to centers of the nervous system and applications would be more like limbs.
 
 
-h3. AMQP 0.9.1 Model, briefly
+h3. AMQP 0.9.1 Model in brief
 
 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.
+distribute message copies to _queues_ using rules called _bindings_. Then AMQP brokers either push messages to _consumers_ subscribed to queues, or consumers
+fetch/pull messages from queues on demand.
 
 !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.
+When publishing a message, producers may specify various _message attributes_ (message metadata). Some of this metadata may be used by the broker, however, the rest of it
+is completely opaque to the broker and is only 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).
+Networks are unreliable and applications may fail to process messages, therefore 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 the application
+developer chooses to do so. When message acknowledgements are in use, a broker will only completely remove a message from a queue when it receives a notification for that message (or 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.
+In certain situations, for example, when a message cannot be routed, messages may be _returned_ to producers, dropped, or, if the broker implements an extension,
+placed into a so-called "dead letter queue". Producers choose how to handle situations like this by publishing messages using 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
+AMQP 0.9.1 is a programmable protocol in the sense that AMQP entities and routing schemes are defined by applications themselves, not a broker administrator. Accordingly, provision is made for 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.
+This gives application developers a lot of freedom but also requires them to be aware of potential definition conflicts. In practice, definition conflicts
+are rare and often indicate misconfigurations. This can be very useful as it is a good thing if misconfigurations are caught early.
 
+Applications declare the AMQP entities that they need, define necessary routing schemes and may choose to delete AMQP entities when they are no longer used.
 
 
-
-h2. AMQP Exchanges and Exchange Types.
+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:
@@ -96,44 +114,53 @@ Besides the type, exchanges have a number of attributes, most imprortant of whic
  * Can have metadata associated with them on declaration
 
 
-h2. AMQP Queues.
+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
+Queues in the AMQP Model are very similar to queues in other message and "task queueing" systems: they store messages that are consumed by
+applications. Like AMQP exchanges, an AMQP queue has a name and a 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)
-
+ * Can have metadata associated with them on declaration (some brokers use it to implement features like message TTL)
 
 
-h2. AMQP Bindings.
+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.
 
+To draw an analogy:
 
+ * Queue is like your destination in New York city
+ * Exchange is like JFK airport
+ * Bindings are routes from JFK to your destination. There can be none or more than one way to reach it
 
-h2. AMQP Message Consumers.
+Having this layer of indirection enables routing scenarios that are impossible of very hard to implement using publishing directly to queues and
+also eliminates certain amount of duplicated work application developers have to do.
 
-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:
+If AMQP message cannot be routed to any queue (for example, because there are no bindings for the exchange it was published to), it is either
+dropped or returned to the publisher, depending on message attributes the publisher has set.
+
+
+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 this:
 
  * 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.
+or, simply put, _subscribe to a queue_. It is possible to have more than one consumer per queue or to register an _exclusive consumer_ (excludes all other consumers from
+the queue while it is consuming).
 
+Each consumer (subscription) has an identifier called a _consumer tag_. It can be used to unsubscribe from messages. Consumer tags are just strings.
 
 
-h2. AMQP Message Attributes and Payload.
+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
+Messages in the AMQP Model have _attributes_. Some attributes are so common that the AMQP v0.9.1 specification defines them and application developers do not have to think
+about the exact attribute name. Some examples are
 
  * Content type
  * Content encoding
@@ -144,36 +171,35 @@ about exact attribute name. Some examples are
  * 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.
+Some attributes are used by AMQP brokers, but most are open 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 a 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.
+AMQP messages also have a _payload_ (the data that they carry). Brokers treat this data as opaque (it is neither modified nor used by them). It is possible for messages to contain only attributes
+and no payload. It is common to use serialization formats like JSON, Thrift, Protocol Buffers and MessagePack
+to serialize structured data
+in order to publish it as AMQP message payload.
 
 
+h2. AMQP Message Acknowledgements
 
-h2. AMQP Message Acknowledgements.
+Since networks are unreliable and applications fail, it is often necessary to have some kind of "processing acknowledgement". Sometimes it is only
+necessary to acknowledge the fact that a message has been received. Sometimes acknowledgements mean that a message was validated and processed by a consumer,
+for example, verified as having mandatory data and persisted to a data store or indexed.
 
-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).
+This situation is very common, so AMQP 0.9.1 has a built-in feature called _message acknowledgements_ (sometimes referred to as _acks_) that consumers
+use to confirm message delivery and/or processing. If an application crashes (AMQP broker notices this when connection is closed), if an acknowledgement for a
+message was expected but not received by the AMQP broker, the message is re-queued (and possibly immediately delivered to another consumer, if any exists).
 
 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
+languages. AMQP methods are grouped into _classes_. Classes are just logical groupings of AMQP methods. The "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:
+Let us take a look at the _exchange.*_ class, a group of methods related to operations on exchanges. It includes the following operations:
 
 
  * exchange.declare
@@ -181,26 +207,26 @@ Lets take a look at the _exchange.*_ class, a group of methods related to operat
  * 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).
+(note that the RabbitMQ site reference also includes RabbitMQ-specific extensions to the exchange.* class that we will not 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").
+brokers in response to the aforementioned "requests").
 
-So first, client asks broker to declare a new exchange using *exchange.declare* method:
+As an example, the client asks the broker to declare a new exchange using the *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,
+As shown on the diagram above, *exchange.declare* carries several _parameters_. They enable the client to specify exchange name,
 type, durability flag and so on.
 
-And if the operation succeeds, broker responds with *exchange.declare-ok* method:
+If the operation succeeds, the broker responds with the *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).
+*exchange.declare-ok* does not carry any parameters except for the channel number (channels will be described later in this guide).
 
-Event sequence is very similar for another methods pair, *queue.declare* and *queue.declare-ok*:
+The sequence of events is very similar for another method pair, *queue.declare* and *queue.declare-ok*:
 
 !https://img.skitch.com/20110720-tmxswrie71ubb5m5nh8n17idhk.jpg!
 
@@ -210,38 +236,33 @@ Not all AMQP methods have counterparts. Some (*basic.publish* being the most wid
 and some others (*basic.get*, for example) have more than one possible "response".
 
 
-
-h2. AMQP Connections.
+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.
+authentication and can be protected using TLS (SSL). When an application no longer needs to be connected to an AMQP broker, it should gracefully
+close the AMQP connection instead of abruptly closing the underlying TCP connection.
 
 
+h2. AMQP Channels
 
-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
+Some applications need multiple connections to an AMQP broker. However, it is 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)
+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).
-
+Communication on a particular channel is completely separate from communication on another channel, therefore every AMQP method also carries a channel number that clients
+use to figure out which channel the method is for (and thus, which event handler needs to be invoked, for example).
 
 
+h2. AMQP Virtual Hosts (vhosts)
 
-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
+To make it possible for a single broker to host multiple isolated "environments" (groups of users, exchanges, queues and so on), AMQP includes the 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.
-
+An AMQP 0.9.1 vhost name can be any non-blank string.
 
 
 h2. AMQP is Extensible
@@ -249,32 +270,43 @@ 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.
+ * Declaration of exchanges and queues can include additional attributes that the 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.
+ * Brokers can be extended with additional plugins, for example, RabbitMQ management frontend and HTTP API are implemented as a plugin.
 
-These features make it even more flexible and applicable to a very broad range of problems.
-
-
+These features make the AMQP 0.9.1 Model 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
+One 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. AMQP 0.9.1 clients ecosystem
 
-h2. Wrapping up
+h3. Overview
 
-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
+There are many AMQP 0.9.1 clients for many popular programming languages and platforms. Some of them follow AMQP terminology closely
+and only provide implementation of AMQP methods. Some others have additional features, convenience methods and abstractions. Some of the
+clients are asynchronous (non-blocking), some are synchronous (blocking), some support both models. Some clients support vendor-specific
+extensions (for example, RabbitMQ-specific extensions).
+
+Because one of the main AMQP goals is interoperability, it is a good idea for developers to understand protocol operations
+and not limit themselves to terminology of a particular client library. This way communicating with developers using different libraries will
+be significantly easier.
 
-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. Wrapping up
+
+This is the end of the AMQP 0.9.1 Model tutorial. Congratulations! Armed with this knowledge, you will find it easier to follow the rest of
+the amqp gem documentation as well as the rabbitmq.com documentation and the "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
@@ -295,13 +327,18 @@ If you are migrating your application from earlier versions of the amqp gem (0.6
 {file:docs/08Migration.textile amqp gem 0.8 migration guide}.
 
 
+h2. Authors
+
+This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.
+
+
 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
+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
+If, for some reason, you cannot use the communication channels mentioned above, you can "contact the author of the guides directly":mailto:michaelklishin@me.com?subject=amqp%20gem%20documentation
 
 
 <div id="disqus_thread"></div>