amqp v1.4.2 AMQP.Basic View Source

Functions to publish, consume and acknowledge messages.

Link to this section Summary

Types

consumer_tag()

delivery_tag()

error()

exchange()

payload()

queue()

routing_key()

Functions

ack(channel, delivery_tag, options \\ [])

Acknowledges one or more messages.

cancel(channel, consumer_tag, options \\ [])

Stops the given consumer from consuming.

cancel_return(channel)

Removes the return handler, if it exists. Does nothing if there is no such handler.

consume(chan, queue, consumer_pid \\ nil, options \\ [])

Registers a queue consumer process. The pid of the process can be set using the consumer_pid argument and defaults to the calling process.

get(channel, queue, options \\ [])

Polls a queue for an existing message.

nack(channel, delivery_tag, options \\ [])

Negative acknowledges of one or more messages.

publish(channel, exchange, routing_key, payload, options \\ [])

Publishes a message to an Exchange.

qos(channel, options \\ [])

Sets the message prefetch count or prefetech size (in bytes).

recover(channel, options \\ [])

Asks the server to redeliver all unacknowledged messages on a specified channel.

reject(channel, delivery_tag, options \\ [])

Rejects (and, optionally, requeues) a message.

return(channel, return_handler_pid)

Registers a handler to deal with returned messages.

Link to this section Types

consumer_tag()

consumer_tag() :: String.t()

delivery_tag()

delivery_tag() :: integer()

error()

error() :: {:error, reason :: :blocked | :closing}

exchange()

exchange() :: String.t()

payload()

payload() :: String.t()

queue()

queue() :: String.t()

routing_key()

routing_key() :: String.t()

Link to this section Functions

ack(channel, delivery_tag, options \\ [])

ack(AMQP.Channel.t(), delivery_tag(), keyword()) :: :ok | error()

Acknowledges one or more messages.

Options

:multiple - If set, all messages up to the one specified by delivery_tag are acknowledged. Defaults to false.

cancel(channel, consumer_tag, options \\ [])

cancel(AMQP.Channel.t(), String.t(), keyword()) :: {:ok, String.t()} | error()

Stops the given consumer from consuming.

This method cancels a consumer. This does not affect already delivered messages, but it does mean the server will not send any more messages for that consumer. The client may receive an arbitrary number of messages in between sending the cancel method and receiving the reply.

consumer_tag identifies the "subscription" to cancel, that is, the subscription of a consumer to a specific queue. The consumer tag is returned by consume/4.

Options

:no_wait - If set, the cancel operation is asynchronous. Defaults to false.

cancel_return(channel)

cancel_return(AMQP.Channel.t()) :: :ok

Removes the return handler, if it exists. Does nothing if there is no such handler.

consume(chan, queue, consumer_pid \\ nil, options \\ [])

consume(AMQP.Channel.t(), String.t(), pid() | nil, keyword()) ::
  {:ok, String.t()} | error()

Registers a queue consumer process. The pid of the process can be set using the consumer_pid argument and defaults to the calling process.

The consumer process will receive the following data structures:

{:basic_deliver, payload, meta} - This is sent for each message consumed, where payload contains the message content and meta contains all the metadata set when sending with Basic.publish or additional info set by the broker;
{:basic_consume_ok, %{consumer_tag: consumer_tag}} - Sent when the consumer process is registered with Basic.consume. The caller receives the same information as the return of Basic.consume;
{:basic_cancel, %{consumer_tag: consumer_tag, no_wait: no_wait}} - Sent by the broker when the consumer is unexpectedly cancelled (such as after a queue deletion)
{:basic_cancel_ok, %{consumer_tag: consumer_tag}} - Sent to the consumer process after a call to Basic.cancel

Options

:consumer_tag - Specifies the consumer tag for this consumer (as a string). This tag is local to the given channel chan, so different channels can have consumers that use the same consumer tag. If the given consumer tag is "", then the server autogenerates the tag. Defaults to "".
:no_local - If set, the server won't send messages to the connection that published them. Defaults to false.
:no_ack - If set, the server will not expect message acks from the consumer and will consider every message that it believes was delivered to the consumer as acknowledged. Defaults to false, meaning that messages need to be acked explicitly through ack/3.
:exclusive - If set, requests exclusive consumer access, meaning that only this consumer can consume from the given queue. Note that the client cannot have exclusive access to a queue that already has consumers.
:no_wait - If set, the consume operation is asynchronous. Defaults to false.
:arguments - A list of arguments to pass when consuming (of type AMQP.arguments/0). See the README for more information. Defaults to [].

get(channel, queue, options \\ [])

get(AMQP.Channel.t(), queue(), keyword()) ::
  {:ok, String.t(), map()} | {:empty, map()} | error()

Polls a queue for an existing message.

Returns the tuple {:empty, meta} if the queue is empty or the tuple {:ok, payload, meta} if at least one message exists in the queue. The returned meta map includes the entry :message_count with the current number of messages in the queue.

Receiving messages by polling a queue is not as as efficient as subscribing a consumer to a queue, so consideration should be taken when receiving large volumes of messages.

Options

:no_ack - If set, the broker is told that the received will not send an acknoledgement of the message. Once the broker believes it has delivered the message, then it's free to assume that the consuming application has taken responsibility for it. In general, a lot of applications will not want these semantics, rather, they will want to explicitly acknowledge the receipt of a message (through ack/3). Defaults to false (meaning explicit acks).

nack(channel, delivery_tag, options \\ [])

nack(AMQP.Channel.t(), delivery_tag(), keyword()) :: :ok | error()

Negative acknowledges of one or more messages.

This is a RabbitMQ specific extension to AMQP 0.9.1. It is equivalent to reject/3, but allows rejecting multiple messages using the multiple option.

Options

:multiple - If set, all messages up to the one specified by delivery_tag are considered as not acknowledged by the server. Defaults to false.
:requeue - If set, the message will be returned to the queue and redelivered to the next available consumer. Defaults to true.

publish(channel, exchange, routing_key, payload, options \\ [])

publish(AMQP.Channel.t(), exchange(), routing_key(), payload(), keyword()) ::
  :ok | error()

Publishes a message to an Exchange.

This method publishes a message to a specific exchange. The message will be routed to queues as defined by the exchange configuration and distributed to any subscribers.

The parameter exchange specifies the name of the exchange to publish to. If set to empty string, it publishes to the default exchange. The routing_key parameter specifies the routing key for the message.

The payload parameter specifies the message content as a binary.

In addition to the previous parameters, the following options can be used:

Options

:mandatory - If set, returns an error if the broker can't route the message to a queue (default false);
:immediate - If set, returns an error if the broker can't deliver the message to a consumer immediately (default false);
:content_type - MIME Content type;
:content_encoding - MIME Content encoding;
:headers - Message headers of type AMQP.arguments/0. Can be used with headers Exchanges;
:persistent - If set, uses persistent delivery mode. Messages marked as persistent that are delivered to durable queues will be logged to disk;
:correlation_id - application correlation identifier;
:priority - message priority, ranging from 0 to 9;
:reply_to - name of the reply queue;
:expiration - how long the message is valid (in milliseconds);
:message_id - message identifier;
:timestamp - timestamp associated with this message (epoch time);
:type - message type as a string;
:user_id - creating user ID. RabbitMQ will validate this against the active connection user;
:app_id - publishing application ID.

Examples

iex> AMQP.Basic.publish chan, "my_exchange", "my_routing_key", "Hello World!", persistent: true
:ok

qos(channel, options \\ [])

qos(AMQP.Channel.t(), keyword()) :: :ok | error()

Sets the message prefetch count or prefetech size (in bytes).

Options

:prefetch_size - the prefetch size (in bytes). Defaults to 0.
:prefetch_count - the prefetch count. Defaults to 0.
:global - If set, this applies to the entire Connection, otherwise it applies only to the given Channel. Defaults to false.

recover(channel, options \\ [])

recover(AMQP.Channel.t(), keyword()) :: :ok | error()

Asks the server to redeliver all unacknowledged messages on a specified channel.

Options

:requeue - If set, the server will attempt to requeue the message, potentially delivering it to another subscriber. Otherwise it will be redelivered to the original recipient. Defaults to false.

reject(channel, delivery_tag, options \\ [])

reject(AMQP.Channel.t(), delivery_tag(), keyword()) :: :ok | error()

Rejects (and, optionally, requeues) a message.

Options

:requeue - If set, the message is requeued by the server, otherwise it's discarded. Defaults to true.

return(channel, return_handler_pid)

return(AMQP.Channel.t(), pid()) :: :ok

Registers a handler to deal with returned messages.

The registered process will receive {:basic_return, payload, meta} tuples.