Yggdrasil v5.0.2 Yggdrasil behaviour View Source

Yggdrasil is an immense mythical tree that connects the nine worlds in Norse cosmology.

Yggdrasil is an agnostic publisher/subscriber:

  • Multi-node pubsub.
  • Simple API (subscribe/1, unsubscribe/1, publish/2).
  • GenServer wrapper for handling subscriber events easily.
  • Several fault tolerant adapters (RabbitMQ, Redis, PostgreSQL, GraphQL, Ethereum).

Small Example

The following example uses the Elixir distribution to send the messages:

iex(1)> Yggdrasil.subscribe(name: "my_channel")
iex(2)> flush()
{:Y_CONNECTED, %Yggdrasil.Channel{...}}

and to publish a for the subscribers:

iex(3)> Yggdrasil.publish([name: "my_channel"], "message")
iex(4)> flush()
{:Y_EVENT, %Yggdrasil.Channel{...}, "message"}

When the subscriber wants to stop receiving messages, then it can unsubscribe from the channel:

iex(5)> Yggdrasil.unsubscribe(name: "my_channel")
iex(6)> flush()
{:Y_DISCONNECTED, %Yggdrasil.Channel{...}}

Though a GenServer can be used to receive these messages, this module also implements a behaviour for handling events e.g:

defmodule Subscriber do
  use Yggdrasil

  def start_link do
    channel = [name: "my_channel"]
    Yggdrasil.start_link(__MODULE__, [channel])
  end

  def handle_event(_channel, message, _state) do
    IO.inspect message
    {:ok, nil}
  end
end

The previous Yggdrasil subscriber would subscribe to [name: "my_channel"] and print every message it receives from it.

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Creates a channel from data where data is a map or a Keyword list.

Publishes a message in a channel with some optional options.

Starts an Yggdrasil given a module, args and some optional options.

Stops a server given optional reason and timeout.

Subscribes to a channel.

Unsubscribes from a channel.

Callbacks

Callback to handle connection to channels.

Callback to handle disconnections from a channel.

Callback to handle incoming messages from a channel.

Callback to initialize an Yggdrasil.

Callback to handle Yggdrasil termination.

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

gen_channel(data)

View Source
gen_channel(map() | keyword() | Yggdrasil.Channel.t()) ::
  {:ok, Yggdrasil.Channel.t()} | {:error, term()}

Creates a channel from data where data is a map or a Keyword list.

Link to this function

publish(channel, message, options \\ [])

View Source
publish(map() | keyword() | Yggdrasil.Channel.t(), term(), Keyword.t()) ::
  :ok | {:error, term()}

Publishes a message in a channel with some optional options.

Link to this function

start_link(module, args, options \\ [])

View Source
start_link(module(), term(), GenServer.options()) :: GenServer.on_start()

Starts an Yggdrasil given a module, args and some optional options.

Link to this function

stop(server, reason \\ :normal, timeout \\ :infinity)

View Source
stop(GenServer.server(), term(), :infinity | non_neg_integer()) :: :ok

Stops a server given optional reason and timeout.

Link to this function

subscribe(channel)

View Source
subscribe(map() | keyword() | Yggdrasil.Channel.t()) :: :ok | {:error, term()}

Subscribes to a channel.

Link to this function

unsubscribe(channel)

View Source
unsubscribe(map() | keyword() | Yggdrasil.Channel.t()) :: :ok | {:error, term()}

Unsubscribes from a channel.

Link to this section Callbacks

Link to this callback

handle_connect(arg1, state)

View Source
handle_connect(Yggdrasil.Channel.t(), state) ::
  {:ok, state}
  | {:subscribe, [Yggdrasil.Channel.t()], state}
  | {:unsubscribe, [Yggdrasil.Channel.t()], state}
  | {:stop, reason, state}
when state: term(), reason: term()

Callback to handle connection to channels.

Link to this callback

handle_disconnect(arg1, state)

View Source
handle_disconnect(Yggdrasil.Channel.t(), state) ::
  {:ok, state}
  | {:subscribe, [Yggdrasil.Channel.t()], state}
  | {:unsubscribe, [Yggdrasil.Channel.t()], state}
  | {:stop, reason, state}
when state: term(), reason: term()

Callback to handle disconnections from a channel.

Link to this callback

handle_event(arg1, message, state)

View Source
handle_event(Yggdrasil.Channel.t(), message, state) ::
  {:ok, state}
  | {:subscribe, [Yggdrasil.Channel.t()], state}
  | {:unsubscribe, [Yggdrasil.Channel.t()], state}
  | {:stop, reason, state}
when message: term(), state: term(), reason: term()

Callback to handle incoming messages from a channel.

Link to this callback

init(args)

View Source
init(args) :: {:subscribe, [Yggdrasil.Channel.t()], state} | {:stop, reason}
when args: term(), reason: term(), state: term()

Callback to initialize an Yggdrasil.

Link to this callback

terminate(reason, state)

View Source
terminate(reason, state) :: term() when state: term(), reason: term()

Callback to handle Yggdrasil termination.