Modules (BEAM)

Erlang supports hot code loading, which means you can update a module while your system is running without stopping or restarting the system. This is very convenient during development and debugging. Depending on how you deploy your system it can also be useful when maintaining and running a 24/7 system by allowing you to upgrade a module without stopping the system.

When new code is loaded, the old version remains in memory until there are no processes executing it. Once that’s the case, the old code is purged from the system. Note that if you load a third version of a module before the first version has been purged, then the default behavior of the system is to kill any process that references (has a call on the stack) the first version.

You can load a module into the system dynamically using the code:load_file(Module) function. After a new module is loaded then any fully qualified calls (i.e. Module:function), also called remote calls, will go to the new version. Note that if you have a server loop without a remote call then it will continue running the old code.

The code server is a part of the BEAM virtual machine responsible for managing loaded modules and their code.

(Stenman 2025, 129 chap.6 part.6.1)

In short, the runtime keeps at most two versions of a module at any time:

• current: what every new remote call (Module:function(...)) resolves to.
• old: kept alive only while some process still has it on its stack.

Local calls (function(...)) stay inside whatever version the caller is already running, which is why long-running server loops must make a remote call (e.g. ?MODULE:loop(State)) to ever pick up new code.

  loop(State) ->
    receive
      upgrade -> ?MODULE:loop(State);  % remote call: jumps to the new version
      Msg     -> loop(handle(Msg, State)) % local call: stays on current version
    end.

All sizes are big-endian, and every area is prefixed by its size, so a file can be parsed sequentially while it is read from disk.

  BEAMHeader = <<
    IffHeader:4/unit:8 = "FOR1",
    Size:32/big,                  % how many more bytes follow
    FormType:4/unit:8 = "BEAM"
  >>

  BEAMChunk = <<
    ChunkName:4/unit:8,           % "Code", "AtU8", "StrT", "LitT", ...
    ChunkSize:32/big,             % size of ChunkData, excluding padding
    ChunkData:ChunkSize/unit:8,   % format defined by ChunkName
    Padding4:0..3/unit:8
  >>

Thanks to Erlang's bit syntax, a minimal reader that splits a file into its chunks fits in a handful of lines:

  -module(beamfile1).
  -export([read/1]).

  read(Filename) ->
     {ok, File} = file:read_file(Filename),
     <<"FOR1",
       Size:32/integer,
       "BEAM",
       Chunks/binary>> = File,
     {Size, read_chunks(Chunks, [])}.

  read_chunks(<<N,A,M,E, Size:32/integer, Tail/binary>>, Acc) ->
     %% Align each chunk on even 4 bytes
     ChunkLength = align_by_four(Size),
     <<Chunk:ChunkLength/binary, Rest/binary>> = Tail,
     read_chunks(Rest, [{[N,A,M,E], Size, Chunk}|Acc]);
  read_chunks(<<>>, Acc) -> lists:reverse(Acc).

  align_by_four(N) -> (4 * ((N+3) div 4)).

Instruction arguments in the Code chunk are stored with a compact, size-oriented encoding (beam_asm:encode/2 in the compiler application). It is optimised for file size, not for in-memory layout: on load, every value expands to a full machine word or Erlang term.

The low 3 bits of the first byte are the tag:

The extended tag (z) covers lists (e.g. the jump table of select_val), floating point registers, allocation lists, literals and, since OTP 25, registers with type hints.

The remaining bits encode the value depending on its size:

  value < 16        : [ Value:4    | 0   | Tag:3 ]                 1 byte
  value < 2048      : [ ValueHi:3  | 0 1 | Tag:3 ] [ ValueLo:8 ]   2 bytes
  2..8 bytes        : [ Bytes-2:3  | 1 1 | Tag:3 ] [ Data ... ]
  > 8 bytes         : [ 1 1 1 1 1  |       Tag:3 ] [ u-encoded (Bytes-9) ] [ Data ... ]

(Stenman 2025, chap. 6 part.6.2)

• Compression: compiling with +compressed (or compile:file(M, [compressed])) gzips the whole .beam. Execution speed is unaffected since code is decompressed at load time, but loading becomes slower: a disk-space vs. load-time trade-off.
• Encrypted debug info: {debug_info_key, Key} encrypts the debug info chunk (des3_cbc), so tools like the Debugger and Xref still work for whoever holds the key. beam_lib gets the key from a function registered with beam_lib:crypto_key_fun/1 or from an .erlang.crypt file.