AMQP.Basic (amqp v2.1.1) View Source

Functions to publish, consume and acknowledge messages.

Link to this section Summary

Functions

Acknowledges one or more messages.

Stops the given consumer from consuming.

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

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

Polls a queue for an existing message.

Negative acknowledges of one or more messages.

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

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

Rejects (and, optionally, requeues) a message.

Registers a handler to deal with returned messages.

Link to this section Types

Specs

consumer_tag() :: String.t()

Specs

delivery_tag() :: integer()

Specs

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

Specs

exchange() :: String.t()

Specs

payload() :: String.t()

Specs

queue() :: String.t()

Specs

routing_key() :: String.t()

Link to this section Functions

Link to this function

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

View Source

Specs

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 (default false)
Link to this function

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

View Source

Specs

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

  • :nowait - If set, the cancel operation is asynchronous (default false)

Specs

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

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

Link to this function

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

View Source

Specs

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 AMQP.Basic.publish/5 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 AMQP.Basic.consume/4

  • {:basic_cancel, %{consumer_tag: consumer_tag, nowait: nowait}} - 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 AMQP.Basic.cancel/3

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 (default "")

  • :no_local - If set, the server won't send messages to the connection that published them (default 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

  • :nowait - If set, the consume operation is asynchronous (default false)

  • :arguments - A list of arguments to pass when consuming (of type AMQP.arguments/0). See the README for more information (default [])

Link to this function

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

View Source

Specs

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) (default false, meaning explicit acks)
Link to this function

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

View Source

Specs

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 (default false)

  • :requeue - If set, the message will be returned to the queue and redelivered to the next available consumer (default true)

Link to this function

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

View Source

Specs

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
Link to this function

qos(channel, options \\ [])

View Source

Specs

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

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

This allows you to limit the number of unacknowledged messages.

Options

  • :prefetch_size - the prefetch size in bytes (default 0)

  • :prefetch_count - the prefetch count (default 0)

  • :global - If set, this applies to the entire Connection, otherwise it applies only to the given Channel (default false)

Link to this function

recover(channel, options \\ [])

View Source

Specs

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 (default false)
Link to this function

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

View Source

Specs

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 (default true)
Link to this function

return(chan, return_handler_pid)

View Source

Specs

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

Registers a handler to deal with returned messages.

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