ExRabbitMQ v2.10.0 ExRabbitMQ.Consumer behaviour View Source
A behaviour module that abstracts away the handling of RabbitMQ connections and channels.
It abstracts the handling of message delivery and acknowlegement.
It also provides hooks to allow the programmer to wrap the consumption of a message without having to directly access the AMPQ interfaces.
For a connection configuration example see ExRabbitMQ.ConnectionConfig
.
For a queue configuration example see ExRabbitMQ.Consumer.QueueConfig
.
Example usage for a consumer implementing a GenServer
defmodule MyExRabbitMQConsumer do
@module __MODULE__
use GenServer
use ExRabbitMQ.Consumer, GenServer
def start_link() do
GenServer.start_link(@module, :ok)
end
def init(state) do
new_state =
xrmq_init(:my_connection_config, :my_queue_config, state)
|> xrmq_extract_state()
{:ok, new_state}
end
# required override
def xrmq_basic_deliver(payload, meta, state) do
# your message delivery logic goes here...
{:noreply, state}
end
# optional override when there is a need to do setup the channel right after the connection has been established.
def xrmq_channel_setup(channel, state) do
# any channel setup goes here...
{:ok, state}
end
# optional override when there is a need to setup the queue and/or exchange just before the consume.
def xrmq_queue_setup(channel, queue, state) do
# The default queue setup uses the exchange, exchange_opts, bind_opts and qos_opts from
# the queue's configuration to setup the QoS, declare the exchange and bind it with the queue.
# Your can override this function, but you can also keep this functionality of the automatic queue setup by
# calling super, eg:
{:ok, state} = super(channel, queue, state)
# any other queue setup goes here...
end
end
Link to this section Summary
Callbacks
This overridable function can be called whenever no_ack
is set to false
and the user
wants to ack a message
This overridable hook is called as a response to a :basic_cancel
message
This callback is the only required callback (i.e., without any default implementation) and
is called as a response to a :basic_consume
message
This overridable function publishes the payload
to the exchange
using the provided routing_key
This overridable function can be called whenever no_ack
is set to false
and the user wants
to reject a message
This overridable function can be called whenever no_ack
is set to false
and the user wants
to reject a message
This hook is called when a connection has been established and a new channel has been opened
This hook is called automatically, if start_consuming
was true
when xrmq_init/4
Helper function that extracts the state
argument from the passed in tuple
Returns the connection configuration as it was passed to xrmq_init/4
Returns a part of the :exrabbitmq
configuration section, specified with the
key
argument
Returns the queue configuration as it was passed to xrmq_init/4
Initiates a connection or reuses an existing one
This hook is called automatically as part of the flow in xrmq_consume/1
Link to this section Callbacks
xrmq_basic_ack(delivery_tag :: String.t, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
This overridable function can be called whenever no_ack
is set to false
and the user
wants to ack a message.
It is passed the delivery_tag
of the request and by default it simply acks the message
as per the RabbitMQ API.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
xrmq_basic_cancel(cancellation_info :: any, state :: any) :: {:noreply, new_state :: term} | {:noreply, new_state :: term, timeout | :hibernate} | {:noreply, [event :: term], new_state :: term} | {:noreply, [event :: term], new_state :: term, :hibernate} | {:stop, reason :: term, new_state :: term}
This overridable hook is called as a response to a :basic_cancel
message.
It is passed the cancellation_info
of the request and by default it logs an error and
returns {:stop, :basic_cancel, state}
.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
xrmq_basic_deliver(payload :: term, meta :: term, state :: term) :: {:noreply, new_state :: term} | {:noreply, new_state :: term, timeout | :hibernate} | {:noreply, [event :: term], new_state :: term} | {:noreply, [event :: term], new_state :: term, :hibernate} | {:stop, reason :: term, new_state :: term}
This callback is the only required callback (i.e., without any default implementation) and
is called as a response to a :basic_consume
message.
It is passed the payload
of the request as well as the meta
object or the message.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
This overridable function publishes the payload
to the exchange
using the provided routing_key
.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
xrmq_basic_reject(delivery_tag :: String.t, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
This overridable function can be called whenever no_ack
is set to false
and the user wants
to reject a message.
It is passed the delivery_tag
of the request and by default it simply rejects the message
as per the RabbitMQ API.
This function simply calls xrmq_basic_reject/3
with opts
set to []
.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
xrmq_basic_reject(delivery_tag :: String.t, opts :: term, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
This overridable function can be called whenever no_ack
is set to false
and the user wants
to reject a message.
It is passed the delivery_tag
of the request and by default it simply rejects the message
as per the RabbitMQ API.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
xrmq_channel_setup(channel :: term, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
This hook is called when a connection has been established and a new channel has been opened.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
xrmq_consume(state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
This hook is called automatically, if start_consuming
was true
when xrmq_init/4
.
If not, then the user has to call it to start consuming.
It is invoked when a connection has been established and a new channel has been opened.
Its flow is to:
- Declare the queue
- Run
xrmq_queue_setup/3
- Start consuming from the queue
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
xrmq_extract_state({:ok, state :: term} | {:error, reason :: term, state :: term}) :: state :: term
Helper function that extracts the state
argument from the passed in tuple.
Returns the connection configuration as it was passed to xrmq_init/4
.
This configuration is set in the wrapper process’s dictionary.
For the configuration format see the top section of ExRabbitMQ.Consumer
.
xrmq_get_env_config(key :: atom) :: keyword
Returns a part of the :exrabbitmq
configuration section, specified with the
key
argument.
For the configuration format see the top section of ExRabbitMQ.Consumer
.
Returns the queue configuration as it was passed to xrmq_init/4
.
This configuration is set in the wrapper process’s dictionary.
For the configuration format see the top section of ExRabbitMQ.Consumer
.
xrmq_init(connection_config :: struct, queue_config :: struct, start_consuming :: boolean, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
xrmq_init(connection_config :: struct, queue_key :: atom, start_consuming :: boolean, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
xrmq_init(connection_key :: atom, queue_config :: struct, start_consuming :: boolean, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
xrmq_init(connection_key :: atom, queue_key :: atom, start_consuming :: boolean, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
Initiates a connection or reuses an existing one.
When a connection is established then a new channel is opened.
Next, xrmq_channel_setup/2
is called to do any extra work on the opened channel.
If start_consuming
is true
then xrmq_consume/1
is called automatically.
This variant accepts a ExRabbitMQ.Connection
and a ExRabbitMQ.Consumer.QueueConfig
structs
as the arguments for the connection_config
and queue_config
parameters.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.
For the configuration format see the top section of ExRabbitMQ.Consumer
.
xrmq_queue_setup(channel :: term, queue :: String.t, state :: term) :: {:ok, new_state :: term} | {:error, reason :: term, new_state :: term}
This hook is called automatically as part of the flow in xrmq_consume/1
.
It allows the user to run extra queue setup steps when the queue has been declared. The default queue setup uses the exchange, exchange_opts, bind_opts and qos_opts from the queue’s configuration to setup the QoS, declare the exchange and bind it with the queue.
The wrapper process’s state is passed in to allow the callback to mutate it if overriden.