freddy v0.9.0 Freddy.Publisher behaviour

A behaviour module for implementing Freddy-compliant AMQP publisher processes.

The Freddy.Publisher module provides a way to create processes that hold, monitor, and restart a channel in case of failure, exports a function to publish messages to an exchange, and some callbacks to hook into the process lifecycle.

An example Freddy.Publisher process that only sends every other message:

defmodule MyPublisher do
  use Freddy.Publisher

  def start_link(conn, config, opts \ []) do
    Hare.Publisher.start_link(__MODULE__, conn, config, :ok, opts)
  end

  def publish(publisher, payload, routing_key) do
    Hare.Publisher.publish(publisher, payload, routing_key)
  end

  def init(:ok) do
    {:ok, %{last_ignored: false}}
  end

  def before_publication(_payload, _routing_key, _opts, %{last_ignored: false}) do
    {:ignore, %{last_ignored: true}}
  end
  def before_publication(_payload, _routing_key, _opts, %{last_ignored: true}) do
    {:ok, %{last_ignored: false}}
  end
end

Channel handling

When the Freddy.Publisher starts with start_link/5 it runs the init/1 callback and responds with {:ok, pid} on success, like a GenServer.

After starting the process it attempts to open a channel on the given connection. It monitors the channel, and in case of failure it tries to reopen again and again on the same connection.

Context setup

The context setup process for a publisher is to declare its exchange.

Every time a channel is open the context is set up, meaning that the exchange is declared through the new channel based on the given configuration.

The configuration must be a Keyword.t that contains a single key: :exchange whose value is the configuration for the Hare.Context.Action.DeclareExchange. Check it for more detailed information.

Link to this section Summary

Callbacks

Called before a message will be published to the exchange

Called when the process receives a message

Called when the publisher process is first started. start_link/5 will block until it returns

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 meta()
meta() :: map
Link to this type payload()
payload() :: term
Link to this type routing_key()
routing_key() :: Hare.Adapter.routing_key
Link to this type state()
state() :: term

Link to this section Functions

Link to this function call(publisher, message)

See Hare.Publisher.call/2.

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

See Hare.Publisher.call/3.

Link to this function cast(publisher, message)

See Hare.Publisher.cast/2.

Link to this function publish(publisher, payload)

See Hare.Publisher.publish/2.

Link to this function publish(publisher, payload, routing_key)

See Hare.Publisher.publish/3.

Link to this function publish(publisher, payload, routing_key, opts)

See Hare.Publisher.publish/4.

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

Starts a Freddy.Publisher process linked to the current process.

The process will be started by calling init with the given initial value.

Arguments:

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

See GenServer.stop/2.

Link to this section Callbacks

Link to this callback before_publication(payload, routing_key, opts, state)
before_publication(payload, routing_key, opts :: term, state) ::
  {:ok, state} |
  {:ok, payload, routing_key, opts :: term, state} |
  {:ignore, state} |
  {:stop, reason :: term, state}

Called before a message will be published to the exchange.

It receives as argument the message payload, the routing key, the options for that publication and the internal state.

Returning {:ok, state} will cause the message to be sent with no modification, and enter the main loop with the given state.

Returning {:ok, payload, routing_key, opts, state} will cause the given payload, routing key and options to be used instead of the original ones, and enter the main loop with the given state.

Returning {:ignore, state} will ignore that message and enter the main loop again with the given state.

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

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

Called when the process receives a message.

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

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

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

Called when the publisher process is first started. start_link/5 will block until it returns.

It receives as argument the fourth argument given to start_link/5.

Returning {:ok, state} will cause start_link/5 to return {:ok, pid} and attempt to open a channel on the given connection and declare the exchange. After that it will enter the main loop with state as its internal state.

Returning :ignore will cause start_link/5 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/5 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.