gleam_otp

# Gleam OTP

Fault tolerant multi-core programs with OTP, the BEAM actor framework.

[![Package Version](https://img.shields.io/hexpm/v/gleam_otp)](https://hex.pm/packages/gleam_otp)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gleam_otp/)

Gleam programs running on the BEAM typically make use of OTP, Erlang's
actor-based application framework. This package provides opinionated bindings
to many of the core concepts of OTP, providing robust and type safe APIs for
Gleam.

This package is not a distinct OTP-inspired framework. The regular Erlang/OTP
APIs can be use with and alongside this package without trouble.

```shell
gleam add gleam_otp@1
```
```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))
}
```

This package is designed with a few primary goals:

- Full type safety of actors and messages.
- Be compatible with Erlang’s OTP actor framework.
- Provide fault tolerance and self-healing through supervisors.
- Have equivalent performance to Erlang’s OTP.

This package documents its abstractions and functionality, but you likely should
read the documentation or other material on Erlang/OTP to get a fuller
understanding of OTP, the problems it solves, and the motivations for its
design.

Not all Erlang/OTP functionality is included in this library. Some is not
possible to represent in a type safe way, so it is not included. Other features
are still in development, such as further process supervision strategies.

## Common types of actor

This library provides several different types of actor that can be used in
Gleam programs.

### Process

The process is the lowest level building block of OTP, all other actors are
built on top of processes either directly or indirectly. Typically this
abstraction would not be used very often in Gleam applications, favour
other actor types that provide more functionality.

Gleam's [process](https://hexdocs.pm/gleam_erlang/gleam/erlang/process.html) module is defined in the `gleam_erlang` library.

### Actor

The `actor` is the most commonly used process type in Gleam and serves as a good
building block for other abstractions. Like Erlang's `gen_server` it handles
OTP's system messages automatically to enable OTP's debugging and tracing
functionality.

[Documentation](https://hexdocs.pm/gleam_otp/gleam/otp/actor.html)

### Supervisor

Supervisors are processes that start and then supervise other processes.
They can restart them if they crash, and terminate them when the application is
shutting down.

Supervisors can start other supervisors, resulting in a hierarchical process
structure called a supervision tree, providing fault tolerance and monitoring
benefits to a Gleam application.

- [gleam/otp/static_supervisor](https://hexdocs.pm/gleam_otp/gleam/otp/static_supervisor.html) documentation.
- [gleam/otp/factory_supervisor](https://hexdocs.pm/gleam_otp/gleam/otp/factory_supervisor.html) documentation.

## Learning OTP

This package has limited documentation for OTP itself, so attempting to use it
without first studying the framework itself is likely to result in some
confusion and sub-optimal code.

## System messages

OTP system messages are special messages used by some debugging APIs. Actors do
not yet support all OTP system messages, so some of the more niche of these
APIs may not be fully functional. If you find that you have a need for one of
the unimplemented system messages, open an issue and we will implement support
for it.

## What about other parts of OTP?

This package provides reliable typed bindings to a core subset of the Erlang
OTP framework, enough for the majority of OTP code. If you wish to use other
parts of the framework you can use the Erlang APIs directly, or you can use
other packages that provide bindings to more functionality.

Remember, OTP is one framework shared between all BEAM languages! There is no
special Gleam version of OTP, and no reason to be limited to certain packages
or APIs.