gleam/otp/supervisor

Types

ApplicationStartMode

A type used to describe the situation in which an Erlang based application is starting.

For more information see the Erlang distributed application documentation and the Learn Your Some Erlang chapter on distributed applications.

pub type ApplicationStartMode {
  Normal
  Takeover(Node)
  Failover(Node)
}

Constructors

  • Normal
  • Takeover(Node)
  • Failover(Node)

ApplicationStop

pub external type ApplicationStop

ChildSpec

This type contains all the information required to start a new child and add it to the Children.

This is typically created with the worker function.

pub opaque type ChildSpec(msg, argment, returning)

Children

This type represents the starting children of a supervisor within the init function.

pub opaque type Children(argument)

ErlangStartResult

An Erlang supervisor compatible process start result.

pub type ErlangStartResult =
  actor.ErlangStartResult

Message

pub opaque type Message

Spec

This data structure holds all the values required by the start_spec function in order to create an supervisor.

If you do not need to configure the behaviour of your supervisor consider using the start function.

pub type Spec(argument, return) {
  Spec(
    argument: argument,
    max_frequency: Int,
    frequency_period: Int,
    init: fn(Children(argument)) -> Children(return),
  )
}

Constructors

  • Spec( argument: argument, max_frequency: Int, frequency_period: Int, init: fn(Children(argument)) -> Children(return), )

StartResult

The result of starting a Gleam actor.

This type is compatible with Gleam supervisors. If you wish to convert it to a type compatible with Erlang supervisors see the ErlangStartResult type and erlang_start_result function.

pub type StartResult(msg) =
  actor.StartResult(msg)

Functions

add

pub fn add(
  children: Children(a),
  child_spec: ChildSpec(b, a, c),
) -> Children(c)

Add a child to the collection of children of the supervisor

This function starts the child from the child spec.

application_stopped

pub external fn application_stopped() -> ApplicationStop

returning

pub fn returning(
  child: ChildSpec(a, b, c),
  updater: fn(b, Sender(a)) -> d,
) -> ChildSpec(a, b, d)

As each child is added to a supervisors children a new argument is prepared with which to start the next child. By default argument is the same as the previous argument, but this function can be used to change it to something else by passing a function that takes the previous argument and the sender of the previous child.

start

pub fn start(
  init: fn(Children(Nil)) -> Children(a),
) -> Result(Sender(Message), StartError)

Start a supervisor from a given init function.

If you wish to have more control over the configuration of the supervisor see the start_spec function.

start_spec

pub fn start_spec(
  spec: Spec(a, b),
) -> Result(Sender(Message), StartError)

Start a supervisor from a given specification.

supervisor

pub fn supervisor(
  start: fn(a) -> Result(Sender(b), StartError),
) -> ChildSpec(b, a, a)

Prepare a new supervisor type child.

If you wish to prepare a new non-supervisor type child see the worker function.

If you wish to change the type of the argument for later children see the returning function.

Note: Gleam supervisors do not yet support different shutdown periods per child so this function is currently identical in behaviour to worker. It is recommended to use this function for supervisor children nevertheless so the correct shut down behaviour is used in later releases of this library.

to_erlang_start_result

pub fn to_erlang_start_result(
  res: Result(Sender(a), StartError),
) -> Result(Pid, StartError)

Convert a Gleam actor start result into an Erlang supervisor compatible process start result.

worker

pub fn worker(
  start: fn(a) -> Result(Sender(b), StartError),
) -> ChildSpec(b, a, a)

Prepare a new worker type child.

If you wish to prepare a new supervisor type child see the supervisor function.

If you wish to change the type of the argument for later children see the returning function.

wrap_erlang_start_function

pub fn wrap_erlang_start_function(
  start: fn() -> Result(Pid, a),
) -> fn() -> Result(Sender(b), StartError)

Processes written in Erlang or other BEAM languages use bare processes rather than channels, so the value returned from their process start functions are not compatible with Gleam supervisors. This function can be used to wrap the start function so it can be used with a Gleam supervisor.

wrap_erlang_start_result

pub fn wrap_erlang_start_result(
  start: Result(Pid, a),
) -> Result(Sender(b), StartError)

Processes written in Erlang or other BEAM languages use bare processes rather than channels, so the value returned from their process start functions are not compatible with Gleam supervisors. This function can be used to wrap the return value so it can be used with a Gleam supervisor.