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.
-
What is
code_change/3for?Answer
Translating a process state to a new version
The callback turns the old state into the shape the new code expects.
-
What does
code_change/3answer?Answer
{ok, NewState}The process continues with the state the callback returns.
-
Which arguments does
code_change/3receive?Answer
Old version, state and an extra term
The extra term comes from the upgrade instructions and is usually the empty list.
-
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.
-
What does the catch-all clause of
code_change/3do?Answer
Passes the state through unchanged
An unknown version needs no migration, so the state is returned as it was.
-
What does
code:ensure_loaded/1do?Answer
Loads a module unless it is loaded already
It answers
{module, Name}when the module is available, and loads it if needed. -
What does
code:which/1answer?Answer
The path of the beam file
It names the file the loader would use, or
non_existing. -
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.
-
What does
code:soft_purge/1do?Answer
Removes the old version if no process runs it
It is the polite purge;
code:purgeis the one that kills the remaining processes. -
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