Tarearbol.DynamicManager behaviour (tarearbol v1.2.1) View Source

The scaffold implementation to dynamically manage many similar tasks running as processes.

It creates a main supervisor, managing the GenServer holding the state and DynamicSupervisor handling chidren. It has a strategy :rest_for_one, assuming that if the process holding the state crashes, the children will be restarted.

Typically one calls use Tarearbol.DynamicManager and implements at least children_specs/0 callback and receives back supervised tree with a state and many processes controlled by DynamicSupervisor.

To see how it works you might try

defmodule DynamicManager do
  use Tarearbol.DynamicManager

  def children_specs do
    for i <- 1..10, do: {"foo_#{i}", []}, into: %{}
  end
end

{:ok, pid} = DynamicManager.start_link()

The above would spawn 10 children with IDs "foo_1".."foo_10".


DynamicManager also allows dynamic workers management. It exports three functions

@spec put(id :: id(), opts :: Enum.t()) :: pid()
@spec del(id :: id()) :: :ok
@spec get(id :: id()) :: Enum.t()

The semantics of put/2 arguments is the same as a single child_spec, del/1 and get/1 receive the unique ID of the child and shutdown it or return it’s payload respectively.

Link to this section Summary

Types

Identifier of the child process

Callbacks

The method to implement for explicit GenServer.call/3 on the wrapping worker.

The method to implement for explicit GenServer.cast/2 on the wrapping worker.

This function is called to retrieve the map of children with name as key and a workers as the value.

Declares an instance-wide callback to report state; if the startup process takes a while, it’d be run in handle_continue/2 and this function will be called after it finishes so that the application might start using it.

Declares a callback to report slow process (when the scheduler cannot process in a reasonable time).

The main function, doing all the job, supervised.

The method that will be called before the worker is terminated.

Link to this section Types

Specs

id() :: any()

Identifier of the child process

Link to this section Callbacks

Link to this callback

call(message, from, {})

View Source (since 1.2.0)

Specs

call(
  message :: any(),
  from :: GenServer.from(),
  {id :: id(), payload :: term()}
) :: any()

The method to implement for explicit GenServer.call/3 on the wrapping worker.

Link to this callback

cast(message, {})

View Source (since 1.2.1)

Specs

cast(message :: any(), {id :: id(), payload :: term()}) :: :ok

The method to implement for explicit GenServer.cast/2 on the wrapping worker.

Link to this callback

children_specs()

View Source (since 0.9.0)

Specs

children_specs() :: %{required(binary()) => Enum.t()}

This function is called to retrieve the map of children with name as key and a workers as the value.

The value must be an enumerable with keys among:

  • :payload (passed as second argument to perform/2, default nil)
  • :timeout (time between iterations of perform/2, default 1 second)
  • :lull (threshold to notify latency in performing, default 1.1 (the threshold is :lull times the :timeout))

This function should not care about anything save for producing side effects.

It will be backed by DynamicSupervisor. The value it returns will be put into the state under children key.

Link to this callback

handle_state_change(state)

View Source (since 0.9.0)

Specs

handle_state_change(state :: :down | :up | :starting | :unknown) ::
  :ok | :restart

Declares an instance-wide callback to report state; if the startup process takes a while, it’d be run in handle_continue/2 and this function will be called after it finishes so that the application might start using it.

If the application is not interested in receiving state updates, e. g. when all it needs from runners is a side effect, there is a default implementation that does nothing.

Link to this callback

handle_timeout(state)

View Source (since 0.9.5)

Specs

handle_timeout(state :: map()) :: any()

Declares a callback to report slow process (when the scheduler cannot process in a reasonable time).

Link to this callback

perform(id, payload)

View Source (since 0.9.0)

Specs

perform(id :: id(), payload :: term()) :: any()

The main function, doing all the job, supervised.

It will be called with the child id as first argument and the payload option to child spec as second argument (defaulting to nil, can also be ignored if not needed).

Return values

perform/2 might return

  • :halt if it wants to be killed
  • {:ok, result} to store the last result and reschedule with default timeout
  • {:replace, id, payload} to replace the current worker with the new one
  • {{:timeout, timeout}, result} to store the last result and reschedule in given timeout interval
  • or deprecated anything else will be treated as a result
Link to this callback

terminate(reason, {})

View Source (since 1.2.0)

Specs

terminate(reason :: term(), {id :: id(), payload :: term()}) :: any()

The method that will be called before the worker is terminated.