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/process.{type Pid}
import gleam/otp/static_supervisor as sup

pub fn start_supervisor() {
  sup.new(sup.OneForOne)
  |> sup.add(sup.worker_child("db", start_database_connection))
  |> sup.add(sup.worker_child("workers", start_workers))
  |> sup.add(sup.worker_child("web", start_http_server))
  |> sup.start_link
}

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 </>

pub opaque type Builder

ChildBuilder

opaque </>

pub opaque type ChildBuilder

ChildType

</>

pub type ChildType {
  Worker(shutdown_ms: Int)
  Supervisor
}

Constructors

```
Worker(shutdown_ms: Int)
```
Arguments
- shutdown_ms
  
  The number of milliseconds the child is given to shut down. The supervisor tells the child process to terminate by calling exit(Child,shutdown) and then wait for an exit signal with reason shutdown back from the child process. If no exit signal is received within the specified number of milliseconds, the child process is unconditionally terminated using exit(Child,kill).
```
Supervisor
```

Restart

</>

Restart defines when a terminated child process must be restarted.

pub type Restart {
  Permanent
  Transient
  Temporary
}

Constructors

```
Permanent
```
A permanent child process is always restarted.
```
Transient
```
A transient child process is restarted only if it terminates abnormally, that is, with another exit reason than normal, shutdown, or {shutdown,Term}.
```
Temporary
```
A temporary child process is never restarted (even when the supervisor’s restart strategy is RestForOne or OneForAll and a sibling’s death causes the temporary process to be terminated).

Strategy

</>

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.

Functions

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

restart

</>

pub fn restart(
  child: ChildBuilder,
  restart: Restart,
) -> ChildBuilder

When the child is to be restarted. See the Restart documentation for more.

The default value for significance is Permenent.

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.

significant

</>

pub fn significant(
  child: ChildBuilder,
  significant: Bool,
) -> ChildBuilder

This defines if a child is considered significant for automatic self-shutdown of the supervisor.

You most likely do not want to consider any children significant.

This will be ignored if the supervisor auto shutdown is set to Never, which is the default.

The default value for significance is False.

start_link

</>

pub fn start_link(builder: Builder) -> Result(Pid, Dynamic)

supervisor_child

</>

pub fn supervisor_child(
  id id: String,
  run starter: fn() -> Result(Pid, a),
) -> ChildBuilder

A special child that is a supervisor itself.

id is used to identify the child specification internally by the supervisor. Notice that this identifier on occations has been called “name”. As far as possible, the terms “identifier” or “id” are now used but to keep backward compatibility, some occurences of “name” can still be found, for example in error messages.

timeout

</>

pub fn timeout(child: ChildBuilder, ms ms: Int) -> ChildBuilder

This defines the amount of milliseconds a child has to shut down before being brutal killed by the supervisor.

If not set the default for a child is 5000ms.

This will be ignored if the child is a supervisor itself.

worker_child

</>

pub fn worker_child(
  id id: String,
  run starter: fn() -> Result(Pid, a),
) -> ChildBuilder

A regular child that is not also a supervisor.

Example

Constructors

Constructors

Arguments

Constructors

Constructors