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.
Publishes a message to an Exchange.
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
Link to this section Functions
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 bydelivery_tag
are acknowledged (defaultfalse
)
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 (defaultfalse
)
Specs
cancel_return(AMQP.Channel.t()) :: :ok
Removes the return handler, if it exists. Does nothing if there is no such handler.
Specs
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, wherepayload
contains the message content andmeta
contains all the metadata set when sending withAMQP.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 ofAMQP.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 toAMQP.Basic.cancel/3
Options
:consumer_tag
- Specifies the consumer tag for this consumer (as a string). This tag is local to the given channelchan
, 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 (defaultfalse
):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 tofalse
, meaning that messages need to be acked explicitly throughack/3
:exclusive
- If set, requests exclusive consumer access, meaning that only this consumer can consume from the givenqueue
. Note that the client cannot have exclusive access to a queue that already has consumers:nowait
- If set, the consume operation is asynchronous (defaultfalse
):arguments
- A list of arguments to pass when consuming (of typeAMQP.arguments/0
). See the README for more information (default[]
)
Specs
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 (throughack/3
) (defaultfalse
, meaning explicit acks)
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 bydelivery_tag
are considered as not acknowledged by the server (defaultfalse
):requeue
- If set, the message will be returned to the queue and redelivered to the next available consumer (defaulttrue
)
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 (defaultfalse
):immediate
- If set, returns an error if the broker can't deliver the message to a consumer immediately (defaultfalse
):content_type
- MIME Content type:content_encoding
- MIME Content encoding:headers
- Message headers of typeAMQP.arguments/0
. Can be used with headers Exchanges:persistent
- If set, uses persistent delivery mode. Messages marked aspersistent
that are delivered todurable
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
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 (default0
):prefetch_count
- the prefetch count (default0
):global
- If set, this applies to the entire Connection, otherwise it applies only to the given Channel (defaultfalse
)
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 (defaultfalse
)
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 (defaulttrue
)
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.