OTP applications
Counter and supervisor
An application is the unit OTP starts, stops and upgrades: a name, a version, and a tree of processes started by one supervisor. The pieces are the counter of lesson 34 and the supervisor of lesson 35, plus one callback module. Save these two modules as counter.erl and counter_app_sup.erl.
-module(counter).
-behaviour(gen_server).
-export([start_link/0, increment/0, value/0]).
-export([init/1, handle_call/3, handle_cast/2]).
start_link() ->
gen_server:start_link({local, ?MODULE}, ?MODULE, 0, []).
increment() ->
gen_server:cast(?MODULE, increment).
value() ->
gen_server:call(?MODULE, value).
init(State) ->
{ok, State}.
handle_call(value, _From, State) ->
{reply, State, State}.
handle_cast(increment, State) ->
{noreply, State + 1}.
-module(counter_app_sup).
-behaviour(supervisor).
-export([start_link/0, init/1]).
start_link() ->
supervisor:start_link({local, ?MODULE}, ?MODULE, []).
init([]) ->
Children = [
#{id => counter,
start => {counter, start_link, []},
restart => permanent,
shutdown => 5000,
type => worker,
modules => [counter]}
],
{ok, {{one_for_one, 5, 10}, Children}}.
The app behaviour
The callback module implements the application behaviour. The application controller calls start/2 with the start type and the arguments from the app file, and expects the pid of the top supervisor back. stop/1 runs after the tree is gone, and is the place for a last flush or a log line, not for stopping children: the supervisor does that already. Save this module as counter_app_app.erl.
-module(counter_app_app).
-behaviour(application).
-export([start/2, stop/1]).
start(_StartType, _StartArgs) ->
counter_app_sup:start_link().
stop(_State) ->
ok.
Start it by hand
Without an app file you can still call the callback yourself, and that is exactly what the controller does with it: start the supervisor, hand its pid back. The counter then lives in the tree and answers as in lesson 34.
erlc counter.erl counter_app_sup.erl counter_app_app.erl
erl
1> {ok, Sup} = counter_app_app:start(normal, []), is_pid(Sup).
true
2> counter:increment().
ok
3> counter:value().
1
4> counter_app_app:stop([]).
ok
The last call only returns ok: it does not stop the tree, because the caller owns the supervisor here, not the application controller. With a real app file the controller stops the tree before it calls stop/1.
The app file
The app file makes the module an application: it names the version, lists the applications that must be running first, and points at the callback module. rebar3 keeps the source as app.src, writes the modules list into the built copy, and leaves the vsn as the source declares it. Save this file as counter_app.app.src.
{application, counter_app, [
{description, "An OTP application"},
{vsn, "0.1.0"},
{registered, []},
{mod, {counter_app_app, []}},
{applications, [
kernel,
stdlib
]},
{env, []},
{modules, []},
{licenses, ["Apache-2.0"]},
{links, []}
]}.
The vsn field is the application version, and the release tools compare it when they upgrade a running system, together with the code_change callback of lesson 44. The modules key is the list of modules the application owns, and the release tools use it to check that nothing is missing. The env key holds the default application environment, which application:get_env reads and application:set_env overrides at run time.
A rebar3 app
The app template writes all of this in one command: the callback, a supervisor, the app.src file and the config. The name you pass becomes the folder, the application name and the prefix of both modules.
rebar3 new app counter_app
===> Writing counter_app/src/counter_app_app.erl
===> Writing counter_app/src/counter_app_sup.erl
===> Writing counter_app/src/counter_app.app.src
===> Writing counter_app/rebar.config
===> Writing counter_app/.gitignore
===> Writing counter_app/LICENSE.md
===> Writing counter_app/README.md
The compile task builds every module into _build and writes the final app file next to the beams, with the modules list filled in. Copy your counter and supervisor into the src folder of that project and the application is complete.
cd counter_app
rebar3 compile
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling counter_app
Start type
The first argument of start/2 is the start type: normal for a boot, {takeover, Node} when a distributed node takes over an application from a dead one, and {failover, Node} when it restarts it somewhere else. Nearly every application ignores it, as this one does, and only the release handler of a clustered system reads it.
Next: Files and IO
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which behaviour does the application callback module implement?
Answer
applicationThe module declares
-behaviour(application)and exportsstart/2andstop/1. -
What must
start/2return?Answer
The pid of the top supervisor in an ok tuple
The controller links to that pid, so it has to be the supervisor of the whole tree.
-
When does
stop/1run?Answer
After the tree is gone
The supervisor has already stopped the children, so
stop/1is only the last cleanup. -
Which file names the version, the dependencies and the callback module?
Answer
The app file,
counter_app.app.srcThe app file is the application resource; rebar3 reads the
.app.srcform and writes the.app. -
Which key points at the callback module?
Answer
{mod, {counter_app_app, []}}modholds the callback module and the arguments handed tostart/2. -
Which key lists the applications that must be started first?
Answer
{applications, [kernel, stdlib]}The controller starts the listed applications before it starts this one.
-
What does
rebar3 new app counter_appwrite?Answer
A callback, a supervisor, an app.src file and a config
The app template scaffolds the whole OTP application skeleton.
-
What fills the
moduleskey of the built app file?Answer
The build tool
rebar3 writes the list of compiled modules into the final
.appfile under_build. -
Which start type marks a takeover from a dead node?
Answer
{takeover, Node}A takeover moves the application to a node that is already running; a failover starts it somewhere new.
-
Why is
counter:value()1 after onecounter:increment()in the session?Answer
The cast added one to the state 0 from
init/1init(0)starts the state at zero and theincrementcast adds one.
The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) and rebar3 3.27.3 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev