Finishing Queues guide

articles/queues.md

@@ -373,9 +373,13 @@ Delivery tag is simply a channel-specific increasing number that the server uses
 
 When acknowledging multiple messages at once, the delivery tag is treated as "up to and including". For example, if delivery tag = 5 that would mean "acknowledge messages 1, 2, 3, 4 and 5".
 
-<p class="alert alert-error">Acknowledgements are channel-specific. Applications must not receive messages on one channel and acknowledge them on another.</p>
+<p class="alert alert-error">
+Acknowledgements are channel-specific. Applications must not receive messages on one channel and acknowledge them on another.
+</p>
 
-<p class="alert alert-error">A message MUST not be acknowledged more than once. Doing so will result in a channel-level exception (PRECONDITION_FAILED) with an error message like this: "PRECONDITION_FAILED - unknown delivery tag"</p>
+<p class="alert alert-error">
+A message MUST not be acknowledged more than once. Doing so will result in a channel-level exception (PRECONDITION_FAILED) with an error message like this: "PRECONDITION_FAILED - unknown delivery tag"
+</p>
 
 ### Rejecting messages
 
@@ -420,7 +424,8 @@ To configure prefetching per channel, use the `langohr.basic/qos` function. Let
 
 {% gist 062357d99c9b63f1b518 %}
 
-In that example, one consumer prefetches three messages and another consumer prefetches just one. If we take a look at the output that the example produces, we will see that `consumer1` fetched four messages and acknowledged one. After that, all subsequent messages were delivered to `consumer2`:
+In that example, one consumer prefetches three messages and another consumer prefetches just one. If we take a look at the output that the example produces,
+we will see that `consumer1` fetched four messages and acknowledged one. After that, all subsequent messages were delivered to `consumer2`:
 
 {% gist 00ea1388dea0c93eb327 %}
 
@@ -458,25 +463,25 @@ Publisher Confirms RabbitMQ extension.
 ## Fetching messages when needed ("pull API")
 
 The AMQP 0.9.1 specification also provides a way for applications to fetch (pull) messages from the queue only when necessary.
-For that, use the `langohr.basic/get` function:
+For that, use the `langohr.basic/get` function which returns a pair of `[metadata payload]`:
 
-{% gist %}
+{% gist 4acb034a4841023308e2 %}
 
 The same example in context:
 
-{% gist %}
+{% gist acfe1a4cad751f4e2cec %}
+
+The metadata map has the same keys as for delivery handlers (see the "Push API" section above).
 
-If the queue is empty, then ...  will be nil, otherwise ....
+If the queue is empty, then `nil` will be returned.
 
 ## Unsubscribing From Messages
 
-Sometimes it is necessary to unsubscribe from messages without deleting a queue. To do that, use the `` function:
+Sometimes it is necessary to unsubscribe from messages without deleting a queue. To do so, use the `langohr.basic/cancel` function:
 
-{% gist %}
+{% gist 6e4e8694938636bcb315 %}
 
-The same example in context:
-
-{% gist %}
+The consumer tag is either known to your application ahead of time or generated by the broker and returned by `langohr.basic/consume`.
 
 In AMQP parlance, unsubscribing from messages is often referred to as "cancelling a consumer". Once a consumer is cancelled, messages will
 no longer be delivered to it, however, due to the asynchronous nature of the protocol, it is possible for "in flight" messages to be received
@@ -489,66 +494,69 @@ Fetching messages with `langohr.basic/get` is still possible even after a consum
 
 To unbind a queue from an exchange use the `langohr.queue/unbind` function:
 
-{% gist %}
+{% gist https://gist.github.com/96c1c4752349244fb59d %}
 
-The same example in context:
-
-{% gist %}
-
-Note that trying to unbind a queue from an exchange that the queue was never bound to will result in a channel-level exception.
+Note that trying to unbind a queue from an exchange that the queue was never bound to will
+result in a channel-level exception.
 
 ## Querying the Number of Messages in a Queue
 
-It is possible to query the number of messages sitting in the queue by declaring the queue with the ":passive" attribute set.
-The response (`queue.declare-ok` AMQP method) will include the number of messages along with other attributes. However, the amqp gem provides
-a convenience function `langohr.queue/status`:
-
-{% gist %}
-
-The same example in context:
+It is possible to query the number of messages sitting in the queue by declaring the queue
+with the `:passive` attribute set.
+The response (`queue.declare-ok` AMQP method) will include the number of messages along with
+other attributes. However, the amqp gem provides a convenience function `langohr.queue/status`:
 
-{% gist %}
+{% gist 7703ef627a4234b2cabe %}
 
 ## Querying the Number of Consumers On a Queue
 
 It is possible to query the number of consumers on a queue by declaring the queue with the ":passive" attribute set. The response (`queue.declare-ok` AMQP method)
 will include the number of consumers along with other attributes. However, the amqp gem provides a convenience function `langohr.queue/status`:
 
-{% gist %}
-
-The same example in context:
-
-{% gist %}
+{% gist adb53fc1201630a5199c %}
 
 ## Purging queues
 
 It is possible to purge a queue (remove all of the messages from it) using the `langohr.queues/purge` function:
 
-{% gist %}
-
-The same example in context:
-
-{% gist %}
+{% gist be4b2501a72874e6d214 %}
 
-Note that this example purges a newly declared queue with a unique server-generated name. When a queue is declared, it is empty,
-so for server-named queues, there is no need to purge them before they are used.
+Note that this example purges a newly declared queue with a unique server-generated name. When a queue is declared,
+it is empty, so for server-named queues, there is no need to purge them before they are used.
 
 ## Deleting queues
 
 To delete a queue, use the `langohr.queue/delete` function:
 
-{% gist %}
+{% gist dd6a06ac1e50e4c142eb %}
 
-The same example in context:
+When a queue is deleted, all of the messages in it are deleted as well.
 
-{% gist %}
 
-When a queue is deleted, all of the messages in it are deleted as well.
+## Queue durability vs message durability
+
+See [Durability guide](/articles/durability.html)
+
+
+## Vendor-specific extensions related to queues
+
+See [RabbitMQ Extensions guide](/articles/rabbitmq_extensions.html)
+
 
 
 ## Wrapping Up
 
-TBD
+AMQP queues can be client-named or server-named. It is possible to either subscribe for
+messages to be pushed to consumers (register a consumer) or pull messages from the client
+as needed. Consumers are identified by consumer tags.
+
+For messages to be routed to queues, queues need to be bound to exchanges.
+
+Most functions related to queues are found in two Langohr namespaces:
+
+ * `langohr.queue`
+ * `langohr.basic`
+
 
 ## What to Read Next