Gleam OTP

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

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.

gleam add gleam_otp@1

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

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 documentation.
• gleam/otp/factory_supervisor documentation.

Limitations and known issues

Actors do not yet support all OTP system messages, so some of the OTP debugging APIs may not be fully functional. These unsupported messages are discarded by actors. 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.

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.