eensy/otp/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
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
opaquepub opaque type Builder
ChildBuilder
opaquepub opaque type ChildBuilder
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 usingexit(Child,kill)
.
-
-
Supervisor
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
orOneForAll
and a sibling’s death causes the temporary process to be terminated).
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
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.
pub fn new(strategy strategy: Strategy) -> Builder
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 restart is Permenent
.
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.
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
.
pub fn start_link(builder: Builder) -> Result(Pid, Dynamic)
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.
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.
pub fn worker_child(
id id: String,
run starter: fn() -> Result(Pid, a),
) -> ChildBuilder
A regular child that is not also a supervisor.
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.