supervisor

A supervisor that can pass state from older children to younger ones.

If you don’t need this consider using the gleam/otp/static_supervisor module instead.

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 You Some Erlang chapter on distributed applications.

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

Constructors

```
Normal
```
```
Takeover(Node)
```
```
Failover(Node)
```

ApplicationStop

</>

pub type ApplicationStop

ChildSpec

opaque </>

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, argument, returning)

Children

opaque </>

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

opaque </>

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 fn application_stopped() -> ApplicationStop

returning

</>

pub fn returning(
  child: ChildSpec(a, b, c),
  updater: fn(b, Subject(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(Subject(Message), StartError)

Start a supervisor from a given init function.

The init argument passed to children will be Nil and the maximum restart intensity will be 1 restart per 5 seconds (the same as the default for Erlang supervisors). If you wish to specify these values, see the start_spec function and the Spec type.

Examples

let worker = worker(my_actor.start)

let children = fn(children) {
  children
  |> add(worker)
  |> add(worker)
}

start(children)

start_spec

</>

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

Start a supervisor from a given specification.

Examples

let worker = worker(my_actor.start)

let children = fn(children) {
  children
  |> add(worker)
  |> add(worker)
}

start_spec(Spec(
  argument: initial_state,
  frequency_period: 1,
  max_frequency: 5,
  init: children,
))

supervisor

</>

pub fn supervisor(
  start: fn(a) -> Result(Subject(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(Subject(a), StartError),
) -> Result(Pid, Dynamic)

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

worker

</>

pub fn worker(
  start: fn(a) -> Result(Subject(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.

Examples

worker(fn(argument) {
 my_actor.start(argument)
})