Gleam OTP

https://gleam-otp.hexdocs.pm/1.3.0/
Admin
Gleam OTP provides robust, type-safe bindings to the core concepts of Erlang's OTP framework for...
Tokens:9,637
Snippets:141
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Implement an Actor

Source: https://gleam-otp.hexdocs.pm/1.3.0

Example demonstrating how to start an actor, send messages, and perform synchronous calls using the actor module.

```gleam
import gleam/erlang/process.{type Subject}
import gleam/otp/actor

pub fn main() {
  // Start an actor
  let assert Ok(actor) =
    actor.new(0)
    |> actor.on_message(handle_message)
    |> actor.start

  // Send some messages to the actor
  actor.send(actor.data, Add(5))
  actor.send(actor.data, Add(3))

  // Send a message and get a reply
  assert actor.call(actor.data, waiting: 10, sending: Get) == 8
}

pub fn handle_message(state: Int, message: Message) -> actor.Next(Int, Message) {
  case message {
    Add(i) -> {
      let state = state + i
      actor.continue(state)
    }
    Get(reply) -> {
      actor.send(reply, state)
      actor.continue(state)
    }
  }
}

pub type Message {
  Add(Int)
  Get(Subject(Int))
}
```

--------------------------------

### start

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Start the supervisor process.

```APIDOC
## start(builder: Builder) -> Result(actor.Started(Supervisor), actor.StartError)

### Description
Start a new supervisor process with the configuration and children specified within the builder. The supervisor will be linked to the parent process.
```

--------------------------------

### start

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Starts an actor from a given Builder.

```APIDOC
## start

### Signature
`pub fn start(builder: Builder(state, msg, return)) -> Result(Started(return), StartError)`

### Description
Starts an actor from a given `Builder`. On failure, `start` returns a `StartError`.
```

--------------------------------

### Start a supervisor process

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Starts the supervisor process based on the current builder configuration. Prefer using supervised for supervision trees.

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

--------------------------------

### Start a static supervisor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Demonstrates initializing a supervisor with a restart strategy and adding child processes.

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

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

```gleam
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() -> actor.StartResult(Supervisor) {
  supervisor.new(supervisor.OneForOne)
  |> supervisor.add(database_pool.supervised())
  |> supervisor.add(http_server.supervised())
  |> supervisor.start
}
```

--------------------------------

### Started constructor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Constructor for the Started type.

```gleam
Started(pid: process.Pid, data: data)
```

--------------------------------

### Start an actor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Starts an actor from a given Builder. Returns a StartError on failure.

```gleam
pub fn start(
  builder: Builder(state, msg, return),
) -> Result(Started(return), StartError)
```

--------------------------------

### Start a child process

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Launch a new child process using the supervisor's template and a provided argument.

```gleam
pub fn start_child(
  supervisor: Supervisor(child_argument, child_data),
  argument: child_argument,
) -> Result(actor.Started(child_data), actor.StartError)
```

--------------------------------

### start_child

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Starts a new child process using the supervisor's template.

```APIDOC
## start_child(supervisor, argument)

### Description
Start a new child using the supervisor’s child template and the given argument.

### Parameters
- **supervisor** (Supervisor) - The supervisor instance.
- **argument** (child_argument) - The argument to pass to the child template.
```

--------------------------------

### Install Gleam OTP

Source: https://gleam-otp.hexdocs.pm/1.3.0

Command to add the gleam_otp package to a project.

```bash
gleam add gleam_otp@1
```

--------------------------------

### Start a child process dynamically

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Use factory_supervisor.get_by_name to retrieve the supervisor and factory_supervisor.start_child to spawn a new child process.

```gleam
import gleam/http/request.{type Request}
import gleam/http/response.{type Response}
import gleam/otp/factory_supervisor
import my_app

/// In our example this function is called each time a HTTP request is 
/// received by the web server.
pub fn handle_request(req: Request(_), reporters: Name(_)) -> Response(_) {
  // Get a reference to the supervisor using the name
  let supervisor = factory_supervisor.get_by_name(reporters)

  // Start a new child process under the supervisor, passing the request path 
  // to use as the argument for the child-starting template function.
  let start_result = factory_supervisor.start_child(supervisor, request.path)

  // A response is sent to the HTTP client.
  // The child starting template function returns a result, with the error case
  // being used when children fail to start. Because of this the `start_child`
  // function also returns a result, so it must be handled too.
  case start_result {
    Ok(_) -> response.new(200)
    Error(_) -> response.new(500)
  }
}
```

--------------------------------

### Implementing an Actor-based Stack

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Demonstrates starting an actor, sending messages for state mutation, and performing synchronous calls to retrieve data.

```gleam
pub fn main() {
  // Start the actor with initial state of an empty list, and the
  // `handle_message` callback function (defined below).
  // We assert that it starts successfully.
  // 
  // In real-world Gleam OTP programs we would likely write a wrapper functions
  // called `start`, `push` `pop`, `shutdown` to start and interact with the
  // Actor. We are not doing that here for the sake of showing how the Actor 
  // API works.
  let assert Ok(actor) =
    actor.new([]) |> actor.on_message(handle_message) |> actor.start
  let subject = actor.data

  // We can send a message to the actor to push elements onto the stack.
  process.send(subject, Push("Joe"))
  process.send(subject, Push("Mike"))
  process.send(subject, Push("Robert"))

  // The `Push` message expects no response, these messages are sent purely for
  // the side effect of mutating the state held by the actor.
  //
  // We can also send the `Pop` message to take a value off of the actor's
  // stack. This message expects a response, so we use `process.call` to send a
  // message and wait until a reply is received.
  //
  // In this instance we are giving the actor 10 milliseconds to reply, if the
  // `call` function doesn't get a reply within this time it will panic and
  // crash the client process.
  let assert Ok("Robert") = process.call(subject, 10, Pop)
  let assert Ok("Mike") = process.call(subject, 10, Pop)
  let assert Ok("Joe") = process.call(subject, 10, Pop)

  // The stack is now empty, so if we pop again the actor replies with an error.
  let assert Error(Nil) = process.call(subject, 10, Pop)

  // Lastly, we can send a message to the actor asking it to shut down.
  process.send(subject, Shutdown)
}
```

```gleam
// First step of implementing the stack Actor is to define the message type that
// it can receive.
//
// The type of the elements in the stack is not fixed so a type parameter
// is used for it instead of a concrete type such as `String` or `Int`.
pub type Message(element) {
  // The `Shutdown` message is used to tell the actor to stop.
  // It is the simplest message type, it contains no data.
  //
  // Most the time we don't define an API to shut down an actor, but in this
  // example we do to show how it can be done.
  Shutdown

  // The `Push` message is used to add a new element to the stack.
  // It contains the item to add, the type of which is the `element`
  // parameterised type.
  Push(push: element)

  // The `Pop` message is used to remove an element from the stack.
  // It contains a `Subject`, which is used to send the response back to the
  // message sender. In this case the reply is of type `Result(element, Nil)`.
  Pop(reply_with: Subject(Result(element, Nil)))
}

// The last part is to implement the `handle_message` callback function.
//
// This function is called by the Actor for each message it receives.
// Actors are single threaded only doing one thing at a time, so they handle
// messages sequentially one at a time, in the order they are received.
//
// The function takes the current state and a message, and returns a data
// structure that indicates what to do next, along with the new state.
fn handle_message(
  stack: List(e),
  message: Message(e),
) -> actor.Next(List(e), Message(e)) {
  case message {
    // For the `Shutdown` message we return the `actor.stop` value, which causes
    // the actor to discard any remaining messages and stop.
    // We may choose to do some clean-up work here, but this actor doesn't need
    // to do this.
    Shutdown -> actor.stop()

    // For the `Push` message we add the new element to the stack and return
    // `actor.continue` with this new stack, causing the actor to process any
    // queued messages or wait for more.
    Push(value) -> {
      let new_state = [value, ..stack]
      actor.continue(new_state)
    }

    // For the `Pop` message we attempt to remove an element from the stack,
    // sending it or an error back to the caller, before continuing.
    Pop(client) -> {
      case stack {
        [] -> {
          // When the stack is empty we can't pop an element, so we send an
          // error back.
          process.send(client, Error(Nil))
          actor.continue([])
        }

        [first, ..rest] -> {
          // Otherwise we send the first element back and use the remaining
          // elements as the new state.
          process.send(client, Ok(first))
          actor.continue(rest)
        }
      }
    }
  }
}
```

--------------------------------

### Define Started type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

The value returned to the parent when an actor starts successfully.

```gleam
pub type Started(data) {
  Started(pid: process.Pid, data: data)
}
```

--------------------------------

### Define StartResult type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

A convenience type for the result of starting an actor process.

```gleam
pub type StartResult(data) =
  Result(Started(data), StartError)
```

--------------------------------

### Start a factory supervisor in a supervision tree

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Use factory.worker_child and factory.supervised to add a factory supervisor to your application's supervision tree.

```gleam
import gleam/erlang/process.{type Name}
import gleam/otp/actor.{type StartResult}
import gleam/otp/factory_supervisor as factory
import gleam/otp/static_supervisor as supervisor
import my_app

/// This function starts the application's supervision tree.
///
/// It takes a name as an argument that is used by the factory supervisor.
///
pub fn start_supervision_tree(reporters_name: Name(_)) -> StartResult(_) {
  // Define a named factory supervisor that can create new child processes
  // using the `my_app.start_reporter_actor` function, which is defined
  // elsewhere in the program.
  let reporter_factory_supervisor =
    factory.worker_child(my_app.start_reporter_actor)
    |> factory.named(reporters_name)
    |> factory.supervised

  // This web server process takes the name, so it can contact the factory
  // supervisor to command it to start new processes as needed.
  let web_server = my_app.supervised_web_server(reporters_name)

  // Create the top-level static supervisor with the supervisor and web
  // server as its children
  supervisor.new(supervisor.RestForOne)
  |> supervisor.add(reporter_factory_supervisor)
  |> supervisor.add(web_server)
  |> supervisor.start
}
```

--------------------------------

### new_with_initialiser

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Creates a builder for an actor with a custom initializer that runs before the actor starts handling messages. It enforces a timeout for the initialization process.

```APIDOC
## new_with_initialiser

### Signature
`pub fn new_with_initialiser(timeout: Int, initialise: fn(process.Subject(message)) -> Result(Initialised(state, message, return), String)) -> Builder(state, message, return)`

### Description
Creates a builder for an actor with a custom initialiser that runs before the start function returns to the parent. If the initialiser exceeds the specified timeout, the actor is killed and an error is returned to the parent.
```

--------------------------------

### map_data Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Transforms the data of a started child process.

```gleam
pub fn map_data(
  child: ChildSpecification(a),
  transform: fn(a) -> b,
) -> ChildSpecification(b)
```

--------------------------------

### Get Supervisor by Name Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Retrieves a reference to a supervisor using its registered name.

```gleam
pub fn get_by_name(
  name: process.Name(Message(child_argument, child_data)),
) -> Supervisor(child_argument, child_data)
```

--------------------------------

### Register a named supervisor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Assign a name to the supervisor for easier process discovery. If the name is already registered, the supervisor will fail to start.

```gleam
pub fn named(
  builder: Builder(child_argument, child_data),
  name: process.Name(Message(child_argument, child_data)),
) -> Builder(child_argument, child_data)
```

--------------------------------

### Get process state

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Retrieves the state of an OTP compatible process for debugging purposes. Requires Erlang/OTP 26.1 or newer.

```gleam
pub fn get_state(from from: process.Pid) -> dynamic.Dynamic
```

--------------------------------

### new

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Create a new supervisor builder.

```APIDOC
## new(strategy: Strategy) -> Builder

### Description
Create a new supervisor builder, ready for further configuration.
```

--------------------------------

### Create a new supervisor builder

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Initializes a new supervisor builder with a specified strategy.

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

--------------------------------

### returning

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Adds data to be returned to the parent process during actor initialization.

```APIDOC
## returning

### Signature
`pub fn returning(initialised: Initialised(state, message, old_return), return: return) -> Initialised(state, message, return)`

### Description
Adds the data to return to the parent process. This is typically used to return a subject that the actor will receive messages over.
```

--------------------------------

### Configure a supervisor child

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Set up a template for children that are themselves supervisors. These children have no shutdown timeout.

```gleam
pub fn supervisor_child(
  template: fn(child_argument) -> Result(
    actor.Started(child_data),
    actor.StartError,
  ),
) -> Builder(child_argument, child_data)
```

--------------------------------

### initialised

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Sets the post-initialisation state of the actor.

```APIDOC
## pub fn initialised(state: state) -> Initialised(state, message, Nil)

### Description
Takes the post-initialisation state of the actor. This state will be passed to the on_message callback each time a message is received.
```

--------------------------------

### Configure a worker child

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Set up a template for standard worker processes. Use this for non-supervisor children.

```gleam
pub fn worker_child(
  template: fn(child_argument) -> Result(
    actor.Started(child_data),
    actor.StartError,
  ),
) -> Builder(child_argument, child_data)
```

--------------------------------

### Configure supervisor restart strategy

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Set the restart strategy for children. Defaults to supervision.Transient if not specified.

```gleam
pub fn restart_strategy(
  builder: Builder(argument, data),
  restart_strategy: supervision.Restart,
) -> Builder(argument, data)
```

--------------------------------

### Define StartError type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Represents potential errors during actor startup.

```gleam
pub type StartError {
  InitTimeout
  InitFailed(String)
  InitExited(process.ExitReason)
}
```

--------------------------------

### new

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Creates a builder for an actor without a custom initialiser. Returns a subject to the parent for sending messages.

```APIDOC
## pub fn new(state: state) -> Builder(state, message, process.Subject(message))

### Description
Create a builder for an actor without a custom initialiser. The actor returns a subject to the parent that can be used to send messages to the actor.
```

--------------------------------

### supervised

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Create a child specification for the supervisor.

```APIDOC
## supervised(builder: Builder) -> supervision.ChildSpecification(Supervisor)

### Description
Create a ChildSpecification that adds this supervisor as the child of another, making it part of the application’s supervision tree.
```

--------------------------------

### Create an actor with a custom initializer

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Initializes an actor with a custom function that runs before message handling begins, with a specified timeout.

```gleam
pub fn new_with_initialiser(
  timeout: Int,
  initialise: fn(process.Subject(message)) -> Result(
    Initialised(state, message, return),
    String,
  ),
) -> Builder(state, message, return)
```

--------------------------------

### add

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Add a child to the supervisor.

```APIDOC
## add(builder: Builder, child: supervision.ChildSpecification(data)) -> Builder

### Description
Add a child to the supervisor.
```

--------------------------------

### Create a new actor builder

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Initializes a builder for an actor without a custom initializer, returning a subject for message communication.

```gleam
pub fn new(
  state: state,
) -> Builder(state, message, process.Subject(message))
```

--------------------------------

### resume

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Requests a suspended OTP compatible process to resume normal operation.

```APIDOC
## resume(pid: process.Pid) -> Nil

### Description
Request a suspended OTP compatible process to resume, causing it to handle all messages rather than only system messages.

### Parameters
- **pid** (process.Pid) - Required - The process identifier of the target process.
```

--------------------------------

### StartError constructors

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Individual constructors for the StartError type.

```gleam
InitTimeout
```

```gleam
InitFailed(String)
```

```gleam
InitExited(process.ExitReason)
```

--------------------------------

### selecting

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Adds a selector for the actor to receive messages with. Messages not matched by the selector are discarded with a warning.

```APIDOC
## selecting

### Signature
`pub fn selecting(initialised: Initialised(state, old_message, return), selector: process.Selector(message)) -> Initialised(state, message, return)`

### Description
Adds a selector for the actor to receive messages with. If a message is received by the actor but not selected for with the selector then the actor will discard it and log a warning.
```

--------------------------------

### Initialize actor state

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Sets the post-initialization state of the actor, which is passed to the on_message callback.

```gleam
pub fn initialised(
  state: state,
) -> Initialised(state, message, Nil)
```

--------------------------------

### named

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Registers the supervisor with a name, allowing other processes to contact it.

```APIDOC
## named(builder, name)

### Description
Provide a name for the supervisor to be registered with when started, enabling it be more easily contacted by other processes.

### Parameters
- **builder** (Builder) - The supervisor builder instance.
- **name** (process.Name) - The name to register the supervisor with.
```

--------------------------------

### Return data to the parent process

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Attaches data, such as a subject, to be returned to the parent process upon actor initialization.

```gleam
pub fn returning(
  initialised: Initialised(state, message, old_return),
  return: return,
) -> Initialised(state, message, return)
```

--------------------------------

### Resume process

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Requests a suspended process to resume normal message handling.

```gleam
pub fn resume(pid: process.Pid) -> Nil
```

--------------------------------

### restart_strategy

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Configures the restart strategy for children managed by the supervisor.

```APIDOC
## restart_strategy(builder, restart_strategy)

### Description
Configure the strategy for restarting children when they exit. Defaults to supervision.Transient.

### Parameters
- **builder** (Builder) - The supervisor builder instance.
- **restart_strategy** (supervision.Restart) - The restart strategy to apply.
```

--------------------------------

### Restart Strategy Definition

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Defines when a terminated child process should be restarted.

```gleam
pub type Restart {
  Permanent
  Transient
  Temporary
}
```

```gleam
Permanent
```

```gleam
Transient
```

```gleam
Temporary
```

--------------------------------

### Add supervisor to a tree

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Create a child specification to add this supervisor to another supervision tree. This is the recommended way to manage supervisors.

```gleam
pub fn supervised(
  builder: Builder(child_argument, child_data),
) -> supervision.ChildSpecification(
  Supervisor(child_argument, child_data),
)
```

--------------------------------

### get_by_name

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Retrieves a reference to a supervisor using its registered process name.

```APIDOC
## get_by_name

### Signature
`pub fn get_by_name(name: process.Name(Message(child_argument, child_data))) -> Supervisor(child_argument, child_data)`

### Description
Get a reference to a supervisor using its registered name. If no supervisor is associated with the provided name, subsequent operations using this reference will fail.
```

--------------------------------

### restart_tolerance

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Set the restart intensity and period for the supervisor.

```APIDOC
## restart_tolerance(builder: Builder, intensity: Int, period: Int) -> Builder

### Description
Defines a maximum restart tolerance to prevent infinite loops. If more than intensity restarts occur within period seconds, the supervisor terminates.
```

--------------------------------

### Strategy constructors

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Individual constructors for the Strategy type.

```gleam
OneForOne
```

```gleam
OneForAll
```

```gleam
RestForOne
```

--------------------------------

### restart Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Sets the restart strategy for a child specification.

```gleam
pub fn restart(
  child: ChildSpecification(data),
  restart: Restart,
) -> ChildSpecification(data)
```

--------------------------------

### Suspend process

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Requests a process to suspend and only handle system messages.

```gleam
pub fn suspend(pid: process.Pid) -> Nil
```

--------------------------------

### Configure auto-shutdown

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Configures the supervisor to shut down automatically when significant children terminate.

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

--------------------------------

### continue

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Indicates the actor should continue processing messages.

```APIDOC
## pub fn continue(state: state) -> Next(state, message)

### Description
Indicate the actor should continue, processing any waiting or future messages.
```

--------------------------------

### Add a child to the supervisor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Adds a child process specification to the supervisor builder.

```gleam
pub fn add(
  builder: Builder,
  child: supervision.ChildSpecification(data),
) -> Builder
```

--------------------------------

### Define Strategy type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Defines the restart strategies available for the supervisor.

```gleam
pub type Strategy {
  OneForOne
  OneForAll
  RestForOne
}
```

--------------------------------

### timeout

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Configures the shutdown timeout for children.

```APIDOC
## timeout(builder, ms)

### Description
Configure the amount of milliseconds a child has to shut down before being killed. Defaults to 5000ms.

### Parameters
- **builder** (Builder) - The supervisor builder instance.
- **ms** (Int) - Timeout in milliseconds.
```

--------------------------------

### get_state

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Retrieves the state of a given OTP compatible process. This function is intended for debugging purposes and requires Erlang/OTP 26.1 or newer.

```APIDOC
## get_state(from: process.Pid) -> dynamic.Dynamic

### Description
Get the state of a given OTP compatible process. This function is only intended for debugging.

### Parameters
- **from** (process.Pid) - Required - The process identifier of the target process.
```

--------------------------------

### Define StatusInfo type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Contains status information for an OTP process.

```gleam
pub type StatusInfo {
  StatusInfo(
    module: atom.Atom,
    parent: process.Pid,
    mode: Mode,
    debug_state: DebugState,
    state: dynamic.Dynamic,
  )
}
```

```gleam
StatusInfo(
  module: atom.Atom,
  parent: process.Pid,
  mode: Mode,
  debug_state: DebugState,
  state: dynamic.Dynamic,
)
```

--------------------------------

### auto_shutdown

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Configure automatic shutdown behavior.

```APIDOC
## auto_shutdown(builder: Builder, value: AutoShutdown) -> Builder

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

--------------------------------

### send

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Sends a message over a given channel.

```APIDOC
## send

### Signature
`pub fn send(subject: process.Subject(msg), msg: msg) -> Nil`

### Description
Send a message over a given channel. This is a re-export of `process.send`, for the sake of convenience.
```

--------------------------------

### Set restart tolerance

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Defines the maximum number of restarts allowed within a specific time period to prevent infinite restart loops.

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

--------------------------------

### supervisor_child

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Configures the supervisor to manage other supervisors.

```APIDOC
## supervisor_child(template)

### Description
Configure a supervisor with a template that will start children that are also supervisors.
```

--------------------------------

### supervisor Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Creates a child specification for a child that is itself a supervisor.

```gleam
pub fn supervisor(
  run start: fn() -> Result(actor.Started(data), actor.StartError),
) -> ChildSpecification(data)
```

--------------------------------

### Define Initialised type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

The type returned from an actor's initializer, containing state, selector, and return data.

```gleam
pub opaque type Initialised(state, message, data)
```

--------------------------------

### Define AutoShutdown configuration

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Defines the auto-shutdown behavior for a supervisor based on significant child termination.

```gleam
pub type AutoShutdown {
  Never
  AnySignificant
  AllSignificant
}
```

--------------------------------

### Set child shutdown timeout

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Specify the time in milliseconds a child has to shut down before being killed. Defaults to 5000ms.

```gleam
pub fn timeout(
  builder: Builder(argument, data),
  ms ms: Int,
) -> Builder(argument, data)
```

--------------------------------

### named

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Registers an actor with a specific name, allowing it to be addressed by that name.

```APIDOC
## pub fn named(builder: Builder(state, message, return), name: process.Name(message)) -> Builder(state, message, return)

### Description
Provide a name for the actor to be registered with when started, enabling it to receive messages via a named subject. If the name is already registered to another process then the actor will fail to start.
```

--------------------------------

### Create debug state

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Creates a DebugState from a list of DebugOption values.

```gleam
pub fn debug_state(a: List(DebugOption)) -> DebugState
```

--------------------------------

### suspend

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Requests an OTP compatible process to suspend, restricting it to only handle system messages.

```APIDOC
## suspend(pid: process.Pid) -> Nil

### Description
Request an OTP compatible process to suspend, causing it to only handle system messages.

### Parameters
- **pid** (process.Pid) - Required - The process identifier of the target process.
```

--------------------------------

### Name an actor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Registers an actor with a name, allowing it to be addressed by that name. Fails if the name is already registered.

```gleam
pub fn named(
  builder: Builder(state, message, return),
  name: process.Name(message),
) -> Builder(state, message, return)
```

--------------------------------

### Call function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Sends a synchronous message to an actor and waits for a response.

```gleam
pub fn call(
  subject: process.Subject(message),
  waiting timeout: Int,
  sending make_message: fn(process.Subject(reply)) -> message,
) -> reply
```

--------------------------------

### worker Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Creates a child specification for a regular worker process.

```gleam
pub fn worker(
  run start: fn() -> Result(actor.Started(data), actor.StartError),
) -> ChildSpecification(data)
```

--------------------------------

### with_selector

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Provides a selector to change the messages that the actor is handling going forward.

```APIDOC
## with_selector

### Signature
`pub fn with_selector(value: Next(state, message), selector: process.Selector(message)) -> Next(state, message)`

### Description
Provide a selector to change the messages that the actor is handling going forward. This replaces any selector that was previously given in the actor’s `init` callback, or in any previous `Next` value.
```

--------------------------------

### Count Children Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Returns the number of children currently under the supervisor.

```gleam
pub fn count_children(
  factory: Supervisor(child_argument, child_data),
) -> Int
```

--------------------------------

### worker_child

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Configures the supervisor to manage worker processes.

```APIDOC
## worker_child(template)

### Description
Configure a supervisor with a child-starting template function for worker processes.
```

--------------------------------

### AutoShutdown constructors

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

Individual constructors for the AutoShutdown type.

```gleam
Never
```

```gleam
AnySignificant
```

```gleam
AllSignificant
```

--------------------------------

### Select messages for an actor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Adds a selector for the actor to receive specific messages. Messages not selected are discarded with a warning.

```gleam
pub fn selecting(
  initialised: Initialised(state, old_message, return),
  selector: process.Selector(message),
) -> Initialised(state, message, return)
```

--------------------------------

### Set the actor message handler

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Defines the callback function that processes incoming messages sequentially for the actor.

```gleam
pub fn on_message(
  builder: Builder(state, message, return),
  handler: fn(state, message) -> Next(state, message),
) -> Builder(state, message, return)
```

--------------------------------

### restart_tolerance

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Sets the maximum number of restarts allowed within a specific time period.

```APIDOC
## restart_tolerance(builder, intensity, period)

### Description
Defines the maximum restart intensity (MaxR) within a period (MaxT) to prevent infinite restart loops.

### Parameters
- **builder** (Builder) - The supervisor builder instance.
- **intensity** (Int) - Maximum number of restarts allowed.
- **period** (Int) - Time period in seconds.
```

--------------------------------

### Define Builder type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

The opaque builder type used for configuring a supervisor.

```gleam
pub opaque type Builder
```

--------------------------------

### Define DebugOption type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Represents debugging options for a process.

```gleam
pub type DebugOption {
  NoDebug
}
```

```gleam
NoDebug
```

--------------------------------

### call

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Sends a synchronous message to an actor process and waits for a reply within a specified timeout.

```APIDOC
## call

### Description
Sends a synchronous message to a process and waits for a response. If the reply is not received within the specified timeout, the calling process crashes.

### Signature
`pub fn call(subject: process.Subject(message), waiting timeout: Int, sending make_message: fn(process.Subject(reply)) -> message) -> reply`

### Parameters
- **subject** (process.Subject(message)) - The subject of the receiving process.
- **timeout** (Int) - The duration in milliseconds to wait for a reply.
- **make_message** (fn(process.Subject(reply)) -> message) - A function that creates the message to send, accepting a subject for the reply.
```

--------------------------------

### Send a message to an actor

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Sends a message over a given channel. This is a convenience re-export of process.send.

```gleam
pub fn send(subject: process.Subject(msg), msg: msg) -> Nil
```

--------------------------------

### Continue actor processing

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Indicates the actor should continue processing waiting or future messages.

```gleam
pub fn continue(state: state) -> Next(state, message)
```

--------------------------------

### timeout Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Sets the shutdown timeout in milliseconds for a worker child.

```gleam
pub fn timeout(
  child: ChildSpecification(data),
  ms ms: Int,
) -> ChildSpecification(data)
```

--------------------------------

### Define the Port type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/port.html

Represents a port used for external communication.

```gleam
pub type Port
```

--------------------------------

### stop

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Indicates the actor should stop and shut down.

```APIDOC
## stop

### Signature
`pub fn stop() -> Next(state, message)`

### Description
Indicate the actor should stop and shut-down, handling no further messages. The reason for exiting is `Normal`.
```

--------------------------------

### Define Builder type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

The opaque type used for building actor state, messages, and return values.

```gleam
pub opaque type Builder(state, message, return)
```

--------------------------------

### Define Mode type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Represents the operational mode of a process.

```gleam
pub type Mode {
  Running
  Suspended
}
```

```gleam
Running
```

```gleam
Suspended
```

--------------------------------

### Define Next type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

The type used to indicate the next action after handling a message.

```gleam
pub opaque type Next(state, message)
```

--------------------------------

### Stop an actor normally

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Indicates the actor should stop and shut down with a Normal exit reason.

```gleam
pub fn stop() -> Next(state, message)
```

--------------------------------

### Define SystemMessage type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Represents messages sent to a process to control its system state.

```gleam
pub type SystemMessage {
  Resume(fn() -> Nil)
  Suspend(fn() -> Nil)
  GetState(fn(dynamic.Dynamic) -> Nil)
  GetStatus(fn(StatusInfo) -> Nil)
}
```

```gleam
Resume(fn() -> Nil)
```

```gleam
Suspend(fn() -> Nil)
```

```gleam
GetState(fn(dynamic.Dynamic) -> Nil)
```

```gleam
GetStatus(fn(StatusInfo) -> Nil)
```

--------------------------------

### on_message

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Sets the message handler for the actor, which is invoked sequentially for each received message.

```APIDOC
## on_message

### Signature
`pub fn on_message(builder: Builder(state, message, return), handler: fn(state, message) -> Next(state, message)) -> Builder(state, message, return)`

### Description
Sets the message handler for the actor. This callback function is called each time the actor receives a message, processing them sequentially.
```

--------------------------------

### ChildSpecification Type Definition

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Defines the structure for a child process specification within an OTP supervisor.

```gleam
pub type ChildSpecification(data) {
  ChildSpecification(
    start: fn() -> Result(actor.Started(data), actor.StartError),
    restart: Restart,
    significant: Bool,
    child_type: ChildType,
  )
}
```

```gleam
ChildSpecification(
  start: fn() -> Result(actor.Started(data), actor.StartError),
  restart: Restart,
  significant: Bool,
  child_type: ChildType,
)
```

--------------------------------

### Define Supervisor type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/static_supervisor.html

The opaque type representing a reference to a running supervisor.

```gleam
pub opaque type Supervisor
```

--------------------------------

### count_children

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

Returns the number of children currently under the supervisor. Note that this value may be inaccurate if the supervisor is heavily overloaded.

```APIDOC
## count_children

### Signature
`pub fn count_children(factory: Supervisor(child_argument, child_data)) -> Int`

### Description
Returns the number of children under the supervisor. This function runs at a constant speed regardless of the number of children.
```

--------------------------------

### ChildType Definition

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Defines the type of child process, either a worker with a shutdown timeout or a supervisor.

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

```gleam
Worker(shutdown_ms: Int)
```

```gleam
Supervisor
```

--------------------------------

### Update actor selector

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Changes the messages the actor handles going forward by replacing the previous selector.

```gleam
pub fn with_selector(
  value: Next(state, message),
  selector: process.Selector(message),
) -> Next(state, message)
```

--------------------------------

### Define DebugState type

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/system.html

Represents the internal state of the process debugger.

```gleam
pub type DebugState
```

--------------------------------

### stop_abnormal

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Indicates the actor is in a bad state and should shut down.

```APIDOC
## stop_abnormal

### Signature
`pub fn stop_abnormal(reason: String) -> Next(state, message)`

### Description
Indicate the actor is in a bad state and should shut down. It will not handle any new messages, and any linked processes will also exit abnormally. The provided reason will be given and propagated.
```

--------------------------------

### Message Type Definition

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/factory_supervisor.html

The message type used by a factory supervisor, primarily relevant when using a registered name.

```gleam
pub type Message(child_argument, child_data)
```

--------------------------------

### Stop an actor abnormally

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/actor.html

Indicates the actor should shut down due to a bad state. Linked processes will also exit with the provided reason.

```gleam
pub fn stop_abnormal(reason: String) -> Next(state, message)
```

--------------------------------

### significant Function

Source: https://gleam-otp.hexdocs.pm/1.3.0/gleam/otp/supervision.html

Configures whether a child is considered significant for automatic supervisor shutdown.

```gleam
pub fn significant(
  child: ChildSpecification(data),
  significant: Bool,
) -> ChildSpecification(data)
```
Tokens:
Raw