Umbra v0.0.4 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 :

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

Functions

This macro is used to create a fallback for __get_pid__/1 and __init__/1 callback.

This macro is used to implements the requested behaviour, callbacks and generate start/2 and start_link/2 functions.

Callbacks

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

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

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 Functions

Link to this macro

__before_compile__(env)

View Source (macro)

This macro is used to create a fallback for __get_pid__/1 and __init__/1 callback.

Link to this macro

__using__(opts)

View Source (macro)

This macro is used to implements the requested behaviour, callbacks and generate start/2 and start_link/2 functions.

Link to this section Callbacks

Link to this callback

__get_pid__(pid_or_state)

View Source

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.

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.

Link to this callback

__start__(linked, state, opts)

View Source

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