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

from_erlang_start_result

</>

pub fn from_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.

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,
  Dynamic,
)

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_starter

</>

pub fn wrap_erlang_starter(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.