Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Finishing Queues guide

  • Loading branch information...
commit 8c6181f24da1571038f42bfb4155988c920f6116 1 parent 1b043f8
@michaelklishin michaelklishin authored
Showing with 51 additions and 43 deletions.
  1. +51 −43 articles/queues.md
View
94 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
Please sign in to comment.
Something went wrong with that request. Please try again.