supervised function

Author: lpil

CHANGELOG.md

@@ -10,6 +10,7 @@
 - In the `gleam/otp/static_supervisor` module:
   - The `start_link` module has been removed.
   - The `start` module has been added.
+  - The `supervised` module has been added.
   - Types and functions for defining child specifications have been moved to the
     `supervision` module.
   - Child ids are now generated, removing possibility of a collision.

src/gleam/otp/static_supervisor.gleam

@@ -144,8 +144,11 @@ pub fn auto_shutdown(builder: Builder, value: AutoShutdown) -> Builder {
 /// 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, ideally another supervisor.
+/// function.
 ///
 /// If any child fails to start the supevisor first terminates all already
 /// started child processes with reason shutdown and then terminate itself and
@@ -171,6 +174,19 @@ pub fn start(
   }
 }
 
+/// 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.
+///
+pub fn supervised(builder: Builder) -> ChildSpecification(Supervisor) {
+  supervision.supervisor(fn() { start(builder) })
+}
+
 @external(erlang, "gleam_otp_external", "convert_erlang_start_error")
 fn convert_erlang_start_error(dynamic: Dynamic) -> actor.StartError
 

src/gleam/otp/supervision.gleam

@@ -51,7 +51,9 @@ pub type ChildSpecification(data) {
   )
 }
 
-/// A regular child that is not also a supervisor.
+/// A regular child process.
+///
+/// You should use this unless your process is also a supervisor.
 ///
 pub fn worker(
   run start: fn() -> Result(actor.Started(data), actor.StartError),