beam.couchred.com · a reading companion

Inside the BEAM

Deep-dives into the Erlang runtime, one subsystem at a time, straight from the OTP sources.

Personal notes written while reading Erik Stenman's The BEAM Book. They assume you know Erlang/OTP, and nothing about the internals.

The book sets the reading order. These pages take one topic at a time and go deeper, down to the bytes, bits and C structs. They are built only from the OTP source code, its git history and the original specifications, never from the book's text. Every example is generated fresh, and every claim is checked against the current source.

Every deep-dive follows the same four steps:

  1. The problem: what is being solved, and why.
  2. The design choice: what the alternatives were, and why the current answer is a good one.
  3. The ideas: the handful of concepts that explain the low-level details.
  4. The details: the exact layout, with real examples you can poke at.

About the book

The BEAM Book is a wonderful piece of work. Erik Stenman started writing it in 2013, and it grew into the guide the Erlang runtime never had: a patient, thorough tour from processes and tagged terms to the loader, the scheduler and the garbage collector. Many people contributed along the way, but it's his persistence and generosity that made it whole. He made the full text freely available under a Creative Commons licence.

If these pages are useful to you, the book is the reason they exist. Please buy a printed copy to support the author and say thank you. Then star the repository, and send fixes if you find something to improve.

Find the printed edition Read it online The book on GitHub

  1. 01

    The BEAM File

    Published · The BEAM Book, ch. 6

    What erlc actually writes to disk: an EA IFF 85 container, its chunks, the compact term encoding, and a 528-byte module annotated byte by byte.

    beam_asm.erl · beam_lib.erl · beam_file.c · genop.tab

  2. 02

    Terms and Tags

    Planned · The BEAM Book, ch. 4

    How a single machine word can be an atom, a small integer, a pointer to a tuple, or a list cell. Then how maps change shape as they grow, from flatmaps to HAMTs.

    erl_term.h · erl_term.c · erl_map.h · erl_map.c