static_supervisor

Bindings to Erlang/OTP’s supervisor module.

For further detail see the Erlang documentation: https://www.erlang.org/doc/apps/stdlib/supervisor.html.

Example

import gleam/erlang/actor
import gleam/otp/static_supervisor.{type Supervisor} as supervisor
import app/database_pool
import app/http_server

pub fn start_supervisor() ->  {
  supervisor.new(supervisor.OneForOne)
  |> supervisor.add(database_pool.supervised())
  |> supervisor.add(http_server.supervised())
  |> supervisor.start
}

Types

AutoShutdown

</>

A supervisor can be configured to automatically shut itself down with exit reason shutdown when significant children terminate with the auto_shutdown key in the above map.

pub type AutoShutdown {
  Never
  AnySignificant
  AllSignificant
}

Constructors

```
Never
```
Automic shutdown is disabled. This is the default setting.

With auto_shutdown set to never, child specs with the significant flag set to true are considered invalid and will be rejected.
```
AnySignificant
```
The supervisor will shut itself down when any significant child terminates, that is, when a transient significant child terminates normally or when a temporary significant child terminates normally or abnormally.
```
AllSignificant
```
The supervisor will shut itself down when all significant children have terminated, that is, when the last active significant child terminates. The same rules as for any_significant apply.

Builder

opaque </>

A builder for configuring and starting a supervisor. See each of the functions that take this type for details of the configuration possible.

Example

import gleam/erlang/actor
import gleam/otp/static_supervisor.{type Supervisor} as supervisor
import app/database_pool
import app/http_server

pub fn start_supervisor() ->  {
  supervisor.new(supervisor.OneForOne)
  |> supervisor.add(database_pool.supervised())
  |> supervisor.add(http_server.supervised())
  |> supervisor.start
}

pub opaque type Builder

Strategy

</>

How the supervisor should react when one of its children terminates.

pub type Strategy {
  OneForOne
  OneForAll
  RestForOne
}

Constructors

```
OneForOne
```
If one child process terminates and is to be restarted, only that child process is affected. This is the default restart strategy.
```
OneForAll
```
If one child process terminates and is to be restarted, all other child processes are terminated and then all child processes are restarted.
```
RestForOne
```
If one child process terminates and is to be restarted, the ‘rest’ of the child processes (that is, the child processes after the terminated child process in the start order) are terminated. Then the terminated child process and all child processes after it are restarted.

Supervisor

opaque </>

A reference to the running supervisor. In future this could be used to send commands to the supervisor to perform certain actions, but today no such APIs have been exposed.

This supervisor wrap Erlang/OTP’s supervisor module, and as such it does not use subjects for message sending. If it was implemented in Gleam a subject might be used instead of this type.

pub opaque type Supervisor

Values

auto_shutdown

</>

pub fn auto_shutdown(
  builder: Builder,
  value: AutoShutdown,
) -> Builder

A supervisor can be configured to automatically shut itself down with exit reason shutdown when significant children terminate.

new

</>

pub fn new(strategy strategy: Strategy) -> Builder

Create a new supervisor builder, ready for further configuration.

restart_tolerance

</>

pub fn restart_tolerance(
  builder: Builder,
  intensity intensity: Int,
  period period: Int,
) -> Builder

To prevent a supervisor from getting into an infinite loop of child process terminations and restarts, a maximum restart intensity is defined using two integer values specified with keys intensity and period in the above map. Assuming the values MaxR for intensity and MaxT for period, then, if more than MaxR restarts occur within MaxT seconds, the supervisor terminates all child processes and then itself. The termination reason for the supervisor itself in that case will be shutdown.

Intensity defaults to 1 and period defaults to 5.

start

</>

pub fn start(
  builder: Builder,
) -> Result(actor.Started(Supervisor), actor.StartError)

Start a new supervisor process with the configuration and children specified within the builder.

Typically you would use the supervised function to add your supervisor to a supervision tree instead of using this function directly.

The supervisor will be linked to the parent process that calls this function.

If any child fails to start the supevisor first terminates all already started child processes with reason shutdown and then terminate itself and returns an error.

supervised

</>

pub fn supervised(
  builder: Builder,
) -> supervision.ChildSpecification(Supervisor)

Create a ChildSpecification that adds this supervisor as the child of another, making it fault tolerant and part of the application’s supervision tree. You should prefer to starting unsupervised supervisors with the start function.

If any child fails to start the supevisor first terminates all already started child processes with reason shutdown and then terminate itself and returns an error.