Struct amiquip::Channel

pub struct Channel { /* fields omitted */ }

Handle for an AMQP channel.

Interaction with I/O Thread

A Channel is a wrapper around in-memory channels that communicate with its connection's I/O thread. Messages to the I/O thread go through bounded channels; see the discussion on connection tuning for more details.

Unbounded Memory Usage

Messages coming from the I/O thread use in-memory channels that are unbounded to prevent a slow or misbehaving channel from blocking the I/O thread. This means it is possible for memory usage to also grow in an unbounded way. There are two ways an unbounded in-memory channel gets created:

• Creating a consumer; the channel for delivering messages is unbounded.
• Attaching a returned message listener; the channel for delivering returned messages is unbounded.

To control the memory usage of consumers, avoid the use of no_ack consumers. If the consumer is set up to acknowledge messages, the server will not send messages until previous messages have been acknowledged, and you can use qos to control how many outstanding unacknowledged messages are allowed. no_ack consumers do provide higher performance, but amiquip does not have a mechanism for avoiding unbounded growth on the consumer channel if the consumer is not processing messages fast enough to keep up with deliveries from the server.

There is no built-in mechanism to limit memory growth on a channel's returned message listener. If the returned message listener cannot keep up with the rate of returned messages, consider dropping the listener (which will force the I/O thread to discard returned messages instead of buffering them into a channel) and reattaching a new listener once you have caught up.

Connection Errors

If the connection that opened this channel closes, operations on this channel will fail, and may or may not return meaningful error messages. See the discussion on Connection::close for a strategy to deal with this.

Methods

impl Channel

pub fn close(self) -> Result<()>

Synchronously close this channel. This method blocks until the server confirms that the channel has been closed (or an error occurs).

pub fn channel_id(&self) -> u16

Return integral ID of this channel. No two open channels on the same connection may have the same channel ID, but channel IDs can be reused if a channel is opened then closed; its ID becomes available for use by a new channel.

pub fn qos(
    &self,
    prefetch_size: u32,
    prefetch_count: u16,
    global: bool
) -> Result<()>

Specify the prefetching window.

If prefetch_size is greater than 0, instructs the server to go ahead and send messages up to prefetch_size in bytes even before previous deliveries have been acknowledged. If prefetch_count is greater than 0, instructs the server to go ahead and send up to prefetch_count messages even before previous deliveries have been acknowledged. If either field is 0, that field is ignored. If both are 0, prefetching is disabled. If both are nonzero, messages will only be sent before previous deliveries are acknowledged if that send would satisfy both prefetch limits. If a consumer is started with no_ack set to true, prefetch limits are ignored and messages are sent as quickly as possible.

According to the AMQP spec, setting global to true means to apply these prefetch settings to all channels in the entire connection, and global false means the settings apply only to this channel. RabbitMQ does not interpret global the same way; for it, global: true means the settings apply to all consumers on this channel, and global: false means the settings apply only to consumers created on this channel after this call to qos, not affecting previously-created consumers.

pub fn recover(&self, requeue: bool) -> Result<()>

Ask the server to redeliver all unacknowledged messages on this channel. If requeue is false, the server will attempt to redeliver to the original recipient. If it is true, it will attempt to requeue the message, potentially delivering it to a different recipient.

pub fn basic_publish<S: Into<String>>(
    &self,
    exchange: S,
    publish: Publish
) -> Result<()>

Publish a message to exchange. If the exchange does not exist, the server will close this channel. Consider using one of the exchange_declare methods and then Exchange::publish to avoid this.

pub fn listen_for_publisher_confirms(&self) -> Result<Receiver<Confirm>>

Open a crossbeam channel to receive publisher confirmations from the server.

You should call this method before either calling enable_publisher_confirms or before publishing any messages, or you risk missing some confirmations.

The Confirm messages sent to this receiver are the raw confirmation messages from the server; they may be out of order or be confirms for multiple messages. If you want to process perfectly sequential confirmation messages, consider using ConfirmSmoother.

There can be only one return listener per channel. If you call this method a second (or more) time, the I/O thread will drop the sending side of previously returned channels.

Dropping the Receiver returned by this method is harmless. If the I/O loop receives a confirmation and there is no listener registered or the previously-registered listener has been dropped, it will discard the confirmation

pub fn enable_publisher_confirms(&self) -> Result<()>

Synchronously enable publisher confirms on this channel. Confirmations will be delivered to the channel registered via listen_for_publisher_confirms.

pub fn enable_publisher_confirms_nowait(&self) -> Result<()>

Asynchronously enable publisher confirms on this channel. Confirmations will be delivered to the channel registered via listen_for_publisher_confirms.

pub fn listen_for_returns(&self) -> Result<Receiver<Return>>

Open a crossbeam channel to receive returned messages from the server (i.e., messages published as mandatory or immediate that could not be delivered).

There can be only one return listener per channel. If you call this method a second (or more) time, the I/O thread will drop the sending side of previously returned channels.

Dropping the Receiver returned by this method is harmless. If the I/O loop receives a returned message and there is no listener registered or the previously-registered listener has been dropped, it will discard the message.

pub fn queue_declare<S: Into<String>>(
    &self,
    queue: S,
    options: QueueDeclareOptions
) -> Result<Queue>

Synchronously declare a queue named queue with the given options.

If queue is "" (the empty string), the server will assign an automatically generated queue name; use Queue::name to get access to that name.

If the server cannot declare the queue (e.g., if the queue already exists with options that conflict with options), it will close this channel.

pub fn queue_declare_nowait<S: Into<String>>(
    &self,
    queue: S,
    options: QueueDeclareOptions
) -> Result<Queue>

Asynchronously declare a queue named queue with the given options.

If the server cannot declare the queue (e.g., if the queue already exists with options that conflict with options), it will close this channel.

Panics

This method will panic if queue is "" (the empty string), as we would not receive a reply from the server telling us what the autogenerated name is.

pub fn queue_declare_passive<S: Into<String>>(&self, queue: S) -> Result<Queue>

Passively declare that a queue exists. This asks the server to confirm that a queue named queue already exists; it will close the channel if it does not.

pub fn basic_get<S: Into<String>>(
    &self,
    queue: S,
    no_ack: bool
) -> Result<Option<Get>>

Synchronously get a single message from queue. If the queue does not exist, the server will close this channel. Consider using one of the queue_declare methods and then Queue::get to avoid this.

On success, returns Some(message) if there was a message in the queue or None if there were no messages in the queue. If no_ack is false, you are responsible for acknowledging the returned message, typically via Get::ack.

Prefer using basic_consume to allow the server to push messages to you on demand instead of polling with get.

pub fn basic_consume<S: Into<String>>(
    &self,
    queue: S,
    options: ConsumerOptions
) -> Result<Consumer>

Synchronously set up a consumer on queue. If the queue does not exist, the server will close this channel. Consider using one of the queue_declare methods and then Queue::consume to avoid this.

pub fn queue_bind<S0: Into<String>, S1: Into<String>, S2: Into<String>>(
    &self,
    queue: S0,
    exchange: S1,
    routing_key: S2,
    arguments: FieldTable
) -> Result<()>

Syncronously bind queue to exchange with the given routing key and arguments.

If either the queue or the exchange do not exist, the server will close this channel. Consider using the queue_declare and exchange_declare methods and then using Queue::bind to avoid this.

pub fn queue_bind_nowait<S0: Into<String>, S1: Into<String>, S2: Into<String>>(
    &self,
    queue: S0,
    exchange: S1,
    routing_key: S2,
    arguments: FieldTable
) -> Result<()>

Asyncronously bind queue to exchange with the given routing key and arguments.

If either the queue or the exchange do not exist, the server will close this channel. Consider using the queue_declare and exchange_declare methods and then using Queue::bind_nowait to avoid this.

pub fn queue_unbind<S0: Into<String>, S1: Into<String>, S2: Into<String>>(
    &self,
    queue: S0,
    exchange: S1,
    routing_key: S2,
    arguments: FieldTable
) -> Result<()>

Syncronously unbind queue from exchange with the given routing key and arguments.

If either the queue or the exchange do not exist, the server will close this channel. Consider using the queue_declare and exchange_declare methods and then using Queue::unbind to avoid this.

pub fn queue_purge<S: Into<String>>(&self, queue: S) -> Result<u32>

Synchronously purge all messages from queue. On success, returns the number of messages purged.

If the queue does not exist, the server will close this channel. Consider using one of the queue_declare methods and then Queue::purge to avoid this.

pub fn queue_purge_nowait<S: Into<String>>(&self, queue: S) -> Result<()>

Asynchronously purge all messages from queue.

If the queue does not exist, the server will close this channel. Consider using one of the queue_declare methods and then Queue::purge_nowait to avoid this.

pub fn queue_delete<S: Into<String>>(
    &self,
    queue: S,
    options: QueueDeleteOptions
) -> Result<u32>

Synchronously delete queue. On success, returns the number of messages that were in the queue when it was deleted.

If the queue does not exist, the server will close this channel. Consider using one of the queue_declare methods and then Queue::delete to avoid this.

pub fn queue_delete_nowait<S: Into<String>>(
    &self,
    queue: S,
    options: QueueDeleteOptions
) -> Result<()>

Synchronously delete queue.

If the queue does not exist, the server will close this channel. Consider using one of the queue_declare methods and then Queue::delete_nowait to avoid this.

pub fn exchange_declare<S: Into<String>>(
    &self,
    type_: ExchangeType,
    exchange: S,
    options: ExchangeDeclareOptions
) -> Result<Exchange>

Synchronously declare an exchange named exchange with the given type and options.

If the server cannot declare the exchange (e.g., if the exchange already exists with a different type or options that conflict with options), it will close this channel.

pub fn exchange_declare_nowait<S: Into<String>>(
    &self,
    type_: ExchangeType,
    exchange: S,
    options: ExchangeDeclareOptions
) -> Result<Exchange>

Asynchronously declare an exchange named exchange with the given type and options.

If the server cannot declare the exchange (e.g., if the exchange already exists with a different type or options that conflict with options), it will close this channel.

pub fn exchange_declare_passive<S: Into<String>>(
    &self,
    exchange: S
) -> Result<Exchange>

Passively declare that a exchange exists. This asks the server to confirm that a exchange named exchange already exists; it will close the channel if it does not.

pub fn exchange_bind<S0: Into<String>, S1: Into<String>, S2: Into<String>>(
    &self,
    destination: S0,
    source: S1,
    routing_key: S2,
    arguments: FieldTable
) -> Result<()>

Synchronously bind an exchange to an exchange with the given routing key and arguments.

If either the source or destination exchanges do not exist, the server will close this channel. Consider using exchange_declare and then Exchange::bind_to_source (or one of its variants) to avoid this.

Exchange-to-exchange binding is a RabbitMQ extension. You can examine the connection's server properties to see if the current connection supports this feature.

pub fn exchange_bind_nowait<S0: Into<String>, S1: Into<String>, S2: Into<String>>(
    &self,
    destination: S0,
    source: S1,
    routing_key: S2,
    arguments: FieldTable
) -> Result<()>

Asynchronously bind an exchange to an exchange with the given routing key and arguments.

If either the source or destination exchanges do not exist, the server will close this channel. Consider using exchange_declare and then Exchange::bind_to_source_nowait (or one of its variants) to avoid this.

Exchange-to-exchange binding is a RabbitMQ extension. You can examine the connection's server properties to see if the current connection supports this feature.

pub fn exchange_unbind<S0: Into<String>, S1: Into<String>, S2: Into<String>>(
    &self,
    destination: S0,
    source: S1,
    routing_key: S2,
    arguments: FieldTable
) -> Result<()>

Synchronously unbind an exchange from an exchange with the given routing key and arguments.

If either the source or destination exchanges do not exist, the server will close this channel. Consider using exchange_declare and then Exchange::unbind_from_source (or one of its variants) to avoid this.

Exchange-to-exchange binding is a RabbitMQ extension. You can examine the connection's server properties to see if the current connection supports this feature.

pub fn exchange_unbind_nowait<S0: Into<String>, S1: Into<String>, S2: Into<String>>(
    &self,
    destination: S0,
    source: S1,
    routing_key: S2,
    arguments: FieldTable
) -> Result<()>

Asynchronously unbind an exchange from an exchange with the given routing key and arguments.

If either the source or destination exchanges do not exist, the server will close this channel. Consider using exchange_declare and then Exchange::unbind_from_source_nowait (or one of its variants) to avoid this.

Exchange-to-exchange binding is a RabbitMQ extension. You can examine the connection's server properties to see if the current connection supports this feature.

pub fn exchange_delete<S: Into<String>>(
    &self,
    exchange: S,
    if_unused: bool
) -> Result<()>

Synchronously delete an exchange.

If if_unused is true, the exchange will only be deleted if it has no queue bindings.

If the server cannot delete the exchange (either because it does not exist or because if_unused was true and it has queue bindings), it will close this channel.

pub fn exchange_delete_nowait<S: Into<String>>(
    &self,
    exchange: S,
    if_unused: bool
) -> Result<()>

Asynchronously delete an exchange.

If if_unused is true, the exchange will only be deleted if it has no queue bindings.

If the server cannot delete the exchange (either because it does not exist or because if_unused was true and it has queue bindings), it will close this channel.

pub fn ack_all(&self) -> Result<()>

Asynchronously acknowledge all messages consumers on this channel have received that have not yet been acknowledged.

pub fn nack_all(&self, requeue: bool) -> Result<()>

Asynchronously reject all messages consumers on this channel have received that have not yet been acknowledged. If requeue is true, instructs the server to attempt to requeue all such messages.

Trait Implementations

impl Drop for Channel

fn drop(&mut self)

Executes the destructor for this type.