Queues and Exchanges

Queues and exchanges - and the bindings that connect them - are at the heart of message routing with AMQP.

The process of configuring queues and exchanges is as follows:

1. Declare an exchange
2. Declare a queue
3. Bind the queue to the exchange, with a particular routing key pattern.

Then the queue will receive a copy of all messages published to the exchange, where the message routing key “matches” the routing key of the binding. Multiple queues can be bound to an exchange. Queues can be bound to more than one exchange, or bound multiple times to the same exchange.

Having created a queue, one or more clients may start consuming messages from the queue. In the case that more than one consumer is consuming from the same queue, each message is delivered to only one consumer.

See Introduction to AMQP for an introduction to AMQP Exchange/Queue/Binding topologies.

Exchange Management

class nucleon.amqp.channels.Channel

Channel.exchange_declare(exchange=None, type='direct', passive=False, durable=False, auto_delete=False, internal=False, arguments={})

This method creates an exchange if it does not already exist, and if the exchange exists, verifies that it is of the correct and expected class.

Parameters:

• type – Each exchange belongs to one of a set of exchange types implemented by the server. The exchange types define the functionality of the exchange - i.e. how messages are routed through it. It is not valid or meaningful to attempt to change the type of an existing exchange.
• passive – If set, the server will reply with Declare-Ok if the exchange already exists with the same name, and raise an error if not. The client can use this to check whether an exchange exists without modifying the server state. When set, all other method fields except name and no-wait are ignored. A declare with both passive and no-wait has no effect. Arguments are compared for semantic equivalence.
• durable – If set when creating a new exchange, the exchange will be marked as durable. Durable exchanges remain active when a server restarts. Non-durable exchanges (transient exchanges) are purged if/when a server restarts.
• auto_delete – If set, the exchange is deleted when all queues have finished using it.
• internal – If set, the exchange may not be used directly by publishers, but only when bound to other exchanges. Internal exchanges are used to construct wiring that is not visible to applications.
• arguments – A set of arguments for the declaration. The syntax and semantics of these arguments depends on the server implementation.

Channel.exchange_delete(exchange=None, if_unused=False)

This method deletes an exchange.

When an exchange is deleted all queue bindings on the exchange are cancelled.

Parameters:if_unused – If set, the server will only delete the exchange if it has no queue bindings. If the exchange has queue bindings the server does not delete it but raises a channel exception instead.

Queue Management

class nucleon.amqp.channels.Channel

Channel.queue_declare(queue='', passive=False, durable=False, exclusive=False, auto_delete=False, arguments={})

This method creates or checks a queue.

When creating a new queue the client can specify various properties that control the durability of the queue and its contents, and the level of sharing for the queue.

Parameters:

• passive – If set, the server will reply with Declare-Ok if the queue already exists with the same name, and raise an error if not. The client can use this to check whether a queue exists without modifying the server state. When set, all other method fields except name and no-wait are ignored. A declare with both passive and no-wait has no effect. Arguments are compared for semantic equivalence.
• durable – If set when creating a new queue, the queue will be marked as durable. Durable queues remain active when a server restarts. Non-durable queues (transient queues) are purged if/when a server restarts. Note that durable queues do not necessarily hold persistent messages, although it does not make sense to send persistent messages to a transient queue.
• exclusive – Exclusive queues may only be accessed by the current connection, and are deleted when that connection closes. Passive declaration of an exclusive queue by other connections are not allowed.
• auto_delete – If set, the queue is deleted when all consumers have finished using it. The last consumer can be cancelled either explicitly or because its channel is closed. If there was no consumer ever on the queue, it won’t be deleted. Applications can explicitly delete auto-delete queues using the Delete method as normal.
• arguments – A set of arguments for the declaration. The syntax and semantics of these arguments depends on the server implementation.

Channel.queue_delete(queue='', if_unused=False, if_empty=False)

This method deletes a queue.

When a queue is deleted any pending messages are sent to a dead-letter queue if this is defined in the server configuration, and all consumers on the queue are cancelled.

Parameters:

• queue – Specifies the name of the queue to delete.
• if_unused – If set, the server will only delete the queue if it has no consumers. If the queue has consumers the server does does not delete it but raises a channel exception instead.
• if_empty – If set, the server will only delete the queue if it has no messages.

Channel.queue_purge(queue='')

This method removes all messages from a queue which are not awaiting acknowledgment.

Parameters:queue – Specifies the name of the queue to purge.

Binding and Unbinding Queues

class nucleon.amqp.channels.Channel

Channel.queue_bind(queue='', exchange=None, routing_key='', arguments={})

This method binds a queue to an exchange.

Until a queue is bound it will not receive any messages. In a classic messaging model, store-and-forward queues are bound to a direct exchange and subscription queues are bound to a topic exchange.

Parameters:

• queue – Specifies the name of the queue to bind.
• routing_key – Specifies the routing key for the binding. The routing key is used for routing messages depending on the exchange configuration. Not all exchanges use a routing key - refer to the specific exchange documentation. If the queue name is empty, the server uses the last queue declared on the channel. If the routing key is also empty, the server uses this queue name for the routing key as well. If the queue name is provided but the routing key is empty, the server does the binding with that empty routing key. The meaning of empty routing keys depends on the exchange implementation.
• arguments – A set of arguments for the binding. The syntax and semantics of these arguments depends on the exchange class.

Channel.queue_unbind(queue='', exchange=None, routing_key='', arguments={})

This method unbinds a queue from an exchange.

Parameters:

• queue – Specifies the name of the queue to unbind.
• exchange – The name of the exchange to unbind from.
• routing_key – Specifies the routing key of the binding to unbind.
• arguments – Specifies the arguments of the binding to unbind.

Exchange-to-Exchange Binding (RabbitMQ Extension)

RabbitMQ allows exchanges to be bound to other exchanges, in order to allow for more sophisticated routing topologies.

These methods are available for exchange-to-exchange binding:

class nucleon.amqp.channels.Channel

Channel.exchange_bind(destination=None, source=None, routing_key='', arguments={})

This method binds an exchange to an exchange.

Parameters:

• destination – Specifies the name of the destination exchange to bind.
• source – Specifies the name of the source exchange to bind.
• routing_key – Specifies the routing key for the binding. The routing key is used for routing messages depending on the exchange configuration. Not all exchanges use a routing key - refer to the specific exchange documentation.
• arguments – A set of arguments for the binding. The syntax and semantics of these arguments depends on the exchange class.

Channel.exchange_unbind(destination=None, source=None, routing_key='', arguments={})

This method unbinds an exchange from an exchange.

Parameters:

• destination – Specifies the name of the destination exchange to unbind.
• source – Specifies the name of the source exchange to unbind.
• routing_key – Specifies the routing key of the binding to unbind.
• arguments – Specifies the arguments of the binding to unbind.