Code loading

code_change/3

A running process can switch to a new version of its module without stopping. The runtime keeps the old code and the new code side by side, the process keeps its state, and the module gets a chance to translate that state: the code_change/3 callback. It receives the old version, the current state and an extra term from the upgrade script, and answers {ok, NewState}. Save this module as counter_change.erl.

-module(counter_change). -behaviour(gen_server). -export([start/0, bump/0, value/0, change/1]). -export([init/1, handle_call/3, handle_cast/2, code_change/3]). start() -> {ok, _Pid} = gen_server:start_link({local, ?MODULE}, ?MODULE, 0, []), ok. bump() -> gen_server:cast(?MODULE, bump). value() -> gen_server:call(?MODULE, value). change(OldVsn) -> ok = sys:suspend(?MODULE), Result = sys:change_code(?MODULE, ?MODULE, OldVsn, []), ok = sys:resume(?MODULE), Result. init(State) -> {ok, State}. handle_call(value, _From, State) -> {reply, State, State}. handle_cast(bump, State) -> {noreply, State + 1}. code_change(old_vsn, State, _Extra) -> {ok, State + 1}; code_change(_OldVsn, State, _Extra) -> {ok, State}.

The second clause is the contract every gen_server implements: an unknown version passes the state through untouched. This module makes the change visible instead, and adds one to the counter when it sees old_vsn.

Upgrade in a session

sys:change_code asks the process to run its code_change/3, and the process has to be suspended first, so that no message is handled halfway through the upgrade. The sequence is suspend, change, resume, and the counter proves that the state went through the callback.

erlc counter_change.erl
erl

1> counter_change:start().
ok
2> counter_change:bump().
ok
3> counter_change:value().
1
4> counter_change:change(old_vsn).
ok
5> counter_change:value().
2

A real upgrade does the same thing under the control of the release handler: it loads the new beam, asks each process to change code, and only then makes the new version current. The appup file of the application says which modules change and how, and the vsn field of the app file of lesson 36 names the version the handler compares.

Loading code

code:ensure_loaded loads a module from the code path unless it is loaded already, and code:which names the file the loader would use. Normally rebar3 and the release handler do this for you, and a node that loads a module by hand is either a shell or an upgrade script.

erl

1> code:ensure_loaded(counter_change).
{module,counter_change}
2> filename:basename(code:which(counter_change)).
"counter_change.beam"

Two versions of one module can be loaded at the same time: the current one and the old one. A process that was running the old code keeps running it until it makes a fully qualified call into the module, and the loader refuses a third version until the old one is purged. code:soft_purge removes the old version when no process still runs it, and code:purge kills the processes that do. A hot upgrade is really that bookkeeping, done in the right order.

Release upgrades

A release bundles the VM, the applications and a boot script, and an upgrade package adds the new beams plus a relup file. The release handler reads the relup steps, loads the new code, calls sys:change_code on the processes that need it, and applies the appup instructions of each application.

The practical rules for code that must survive an upgrade: keep the state a plain term, put every migration in code_change/3, keep the atom names stable, and test the upgrade path from the previous release, not only a fresh start. rebar3 relup builds the package, and rebar3 release builds the release itself.

Next: Distributed Erlang

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is code_change/3 for?

    Answer

    Translating a process state to a new version

    The callback turns the old state into the shape the new code expects.

  2. What does code_change/3 answer?

    Answer

    {ok, NewState}

    The process continues with the state the callback returns.

  3. Which arguments does code_change/3 receive?

    Answer

    Old version, state and an extra term

    The extra term comes from the upgrade instructions and is usually the empty list.

  4. Why must the process be suspended before sys:change_code?

    Answer

    So no message is handled halfway through the upgrade

    A suspended process handles the system message alone, then resumes with the new state.

  5. What does the catch-all clause of code_change/3 do?

    Answer

    Passes the state through unchanged

    An unknown version needs no migration, so the state is returned as it was.

  6. What does code:ensure_loaded/1 do?

    Answer

    Loads a module unless it is loaded already

    It answers {module, Name} when the module is available, and loads it if needed.

  7. What does code:which/1 answer?

    Answer

    The path of the beam file

    It names the file the loader would use, or non_existing.

  8. How many versions of a module can be loaded at once?

    Answer

    Two: the current and the old

    The runtime keeps the old version for the processes that still run it, and refuses a third.

  9. What does code:soft_purge/1 do?

    Answer

    Removes the old version if no process runs it

    It is the polite purge; code:purge is the one that kills the remaining processes.

  10. Which file tells the release handler how to upgrade an application?

    Answer

    The appup file of the application

    The appup script lists the modules and the instructions for each upgrade step.

The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev