Umbra v0.1.0 Umbra.GenServer behaviour View Source

The Umbra.GenServer is the only module users should care.

You only need to use that module to get started. Umbra.Operations is include behind the scene to adds macros and so function generators.

Example:

defmodule MyGenServer do
  use Umbra.GenServer

  # your code
end

You can use Behaviours to override the default Umbra.GenServer behaviour :

Umbra.Behaviour.Default which is used by default.
Umbra.Behaviour.Strict.
Umbra.Behaviour.Tolerant.

To use a specific Behaviour, you can do:

defmodule MyGenServer do
  use Umbra.GenServer,
    behaviour: Umbra.GenServer.Tolerant
end

Umbra is overridable by callbacks, but you should use it at your own depends.

You can also use Extensions to modify the behaviour of your GenServer :

Link to this section Summary

Callbacks

__get_pid__(pid_or_state)

This callback is used to retrieve the PID.t from the first argument of each client-side genserver function.

__init__(state)

This callback is used to do some changement on state or just initialize some stuff for extensions.

__start__(linked, state, opts)

This callback is used behind the scene by Umbra to start the GenServer and can be overrided by extensions or user when needed.

Link to this section Callbacks

__get_pid__(pid_or_state)

Specs

__get_pid__(pid_or_state :: struct() | PID.t()) ::
  {:ok, PID.t()} | {:error, any()}

This callback is used to retrieve the PID.t from the first argument of each client-side genserver function.

Without any extensions, only PID.t are working.

The Umbra.Extension.Registry extension did set this callback to retrieve the PID.t from the GenServer state/struct.

init(state)

Specs

__init__(state :: struct()) :: {:ok, struct()} | {:error, any()}

This callback is used to do some changement on state or just initialize some stuff for extensions.

It's a callback which only should be override! You should call super(state) when success at the end of your own implementation.

The Umbra.Extension.Ping extension did set this callback to initialize itself.

start(linked, state, opts)

Specs

__start__(linked :: boolean(), state :: struct(), opts :: keyword()) ::
  {:ok, PID.t()} | {:error, any()}

This callback is used behind the scene by Umbra to start the GenServer and can be overrided by extensions or user when needed.

It's here to allow user/extensions to modify the options passed to GenServer.

It's a callback which only should be override! You should call super(linked, state, opts) at the end of your own implementation.

Example:

defmodule MyGenServer do
  use Umbra.GenServer

  def __start__(linked, state, opts) do
    {_, opts} = Keyword.pop(opts, :debug)
    opts = opts ++ [debug: [:trace]]
    super(linked, state, opts)
  end
end

The Umbra.Extension.NameSetter extension did set a Umbra.GenServer.__start__/3 override to automatically set the process name thanks to the Umbra.Extension.NameSetter.__get_process_name__/1 callback.

Basically this callback only do:

GenServer.start(__MODULE__, state, opts) # or start_link if `linked` == true