freddy v0.9.1 Freddy.Consumer behaviour

This module allows to consume messages from specified queue bound to specified exchange.

Example:

defmodule Notifications.Listener do
  use Freddy.Consumer

  def start_link(conn, initial \ nil, opts \ []) do
    config = [
      exchange: [name: "freddy-topic", type: :topic],
      queue: [name: "notifications-queue", opts: [auto_delete: true]],
      qos: [prefetch_count: 10], # optional
      routing_keys: ["routing_key1", "routing_key2"], # short way to declare binds
      binds: [ # fully customizable bindings
        [routing_key: "routing_key3", no_wait: true]
      ]
    ]
    Freddy.Consumer.start_link(__MODULE__, conn, config, initial, opts)
  end

  def init(initial) do
    # do something on init
    {:ok, initial}
  end

  def handle_message(payload, %{routing_key: "visitor.status.disconnect"}, state) do
    {:reply, :ack, state}
  end

  def handle_error(error, message, _meta) do
    # log error?
    {:reply, :nack, state}
  end
end

Link to this section Summary

Callbacks

Called when the process receives a call message sent by call/3. This callback has the same arguments as the GenServer equivalent and the :reply, :noreply and :stop return tuples behave the same

Called when the process receives a cast message sent by cast/3. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same

Called when a message cannot be decoded or when an error occurred during message processing

Called when the process receives a message. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same

Called when a message is delivered from the queue

Called when the AMQP server has registered the process as a consumer and it will start to receive messages

Called when the consumer process is first started

This callback is the same as the GenServer equivalent and is called when the process terminates. The first argument is the reason the process is about to exit with

Link to this section Types

Link to this type action()
action() :: :ack | :nack | :reject
Link to this type connection()
connection() :: GenServer.server
Link to this type error()
error() :: term
Link to this type meta()
meta() :: map
Link to this type payload()
payload() :: term
Link to this type state()
state() :: term

Link to this section Functions

Link to this function call(consumer, message)

See Hare.Consumer.call/2.

Link to this function call(consumer, message, timeout)

See Hare.Consumer.call/3.

Link to this function cast(consumer, message)

See Hare.Consumer.cast/2.

Link to this function start_link(mod, connection, config, initial, opts \\ [])
start_link(module, connection, config, initial :: term, GenServer.options) :: GenServer.on_start

Start a Freddy.Consumer process linked to the current process.

Arguments:

  • mod - the module that defines the server callbacks (like GenServer)
  • connection - the pid of a Hare.Core.Conn process
  • config - the configuration of the consumer
  • initial - the value that will be given to init/1
  • opts - the GenServer options
Link to this function stop(consumer, reason)

See GenServer.stop/2.

Link to this section Callbacks

Link to this callback handle_call(request, arg1, state)
handle_call(request :: term, GenServer.from, state) ::
  {:reply, reply :: term, state} |
  {:reply, reply :: term, state, timeout | :hibernate} |
  {:noreply, state} |
  {:noreply, state, timeout | :hibernate} |
  {:stop, reason :: term, state} |
  {:stop, reason :: term, reply :: term, state}

Called when the process receives a call message sent by call/3. This callback has the same arguments as the GenServer equivalent and the :reply, :noreply and :stop return tuples behave the same.

Link to this callback handle_cast(request, state)
handle_cast(request :: term, state) ::
  {:noreply, state} |
  {:noreply, state, timeout | :hibernate} |
  {:stop, reason :: term, state}

Called when the process receives a cast message sent by cast/3. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same.

Link to this callback handle_error(error, payload, meta, state)
handle_error(error, payload, meta, state) ::
  {:reply, action, state} |
  {:reply, action, opts :: Keyword.t, state} |
  {:noreply, state} |
  {:stop, reason :: term, state}

Called when a message cannot be decoded or when an error occurred during message processing.

The arguments are the error, the message’s original payload, some metadata and the internal state. The metadata is a map containing all metadata given by the adapter when receiving the message plus the :exchange and :queue values received at the connect/2 callback.

Returning {:reply, :ack | :nack | :reject, state} will ack, nack or reject the message.

Returning {:reply, :ack | :nack | :reject, opts, state} will ack, nack or reject the message with the given opts.

Returning {:noreply, state} will do nothing, and therefore the message should be acknowledged by using Freddy.Consumer.ack/2, Freddy.Consumer.nack/2 or Freddy.Consumer.reject/2.

Returning {:stop, reason, state} will terminate the main loop and call terminate(reason, state) before the process exits with reason reason.

Link to this callback handle_info(term, state)
handle_info(term, state) ::
  {:noreply, state} |
  {:noreply, state, timeout | :hibernate} |
  {:stop, reason :: term, state}

Called when the process receives a message. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same.

Link to this callback handle_message(payload, meta, state)
handle_message(payload, meta, state) ::
  {:reply, action, state} |
  {:reply, action, opts :: Keyword.t, state} |
  {:noreply, state} |
  {:stop, reason :: term, state}

Called when a message is delivered from the queue.

The arguments are the message’s decoded payload, some metadata and the internal state. The metadata is a map containing all metadata given by the adapter when receiving the message plus the :exchange and :queue values received at the connect/2 callback.

Returning {:reply, :ack | :nack | :reject, state} will ack, nack or reject the message.

Returning {:reply, :ack | :nack | :reject, opts, state} will ack, nack or reject the message with the given opts.

Returning {:noreply, state} will do nothing, and therefore the message should be acknowledged by using Freddy.Consumer.ack/2, Freddy.Consumer.nack/2 or Freddy.Consumer.reject/2.

Returning {:stop, reason, state} will terminate the main loop and call terminate(reason, state) before the process exits with reason reason.

Link to this callback handle_ready(meta, state)
handle_ready(meta, state) ::
  {:noreply, state} |
  {:stop, reason :: term, state}

Called when the AMQP server has registered the process as a consumer and it will start to receive messages.

Returning {:noreply, state} will causes the process to enter the main loop with the given state.

Returning {:stop, reason, state} will terminate the main loop and call terminate(reason, state) before the process exits with reason reason.

Link to this callback init(state)
init(state) :: {:ok, state} | :ignore | {:stop, reason :: term}

Called when the consumer process is first started.

Returning {:ok, state} will cause start_link/3 to return {:ok, pid} and attempt to open a channel on the given connection and declare the queue, the exchange, and the bindings to the specified routing keys.

After that it will enter the main loop with state as its internal state.

Returning :ignore will cause start_link/3 to return :ignore and the process will exit normally without entering the loop, opening a channel or calling terminate/2.

Returning {:stop, reason} will cause start_link/3 to return {:error, reason} and the process will exit with reason reason without entering the loop, opening a channel, or calling terminate/2.

Link to this callback terminate(reason, state)
terminate(reason :: term, state) :: any

This callback is the same as the GenServer equivalent and is called when the process terminates. The first argument is the reason the process is about to exit with.