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.

  1. Which behaviour does the application callback module implement?

    Answer

    application

    The module declares -behaviour(application) and exports start/2 and stop/1.

  2. What must start/2 return?

    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.

  3. When does stop/1 run?

    Answer

    After the tree is gone

    The supervisor has already stopped the children, so stop/1 is only the last cleanup.

  4. Which file names the version, the dependencies and the callback module?

    Answer

    The app file, counter_app.app.src

    The app file is the application resource; rebar3 reads the .app.src form and writes the .app.

  5. Which key points at the callback module?

    Answer

    {mod, {counter_app_app, []}}

    mod holds the callback module and the arguments handed to start/2.

  6. 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.

  7. What does rebar3 new app counter_app write?

    Answer

    A callback, a supervisor, an app.src file and a config

    The app template scaffolds the whole OTP application skeleton.

  8. What fills the modules key of the built app file?

    Answer

    The build tool

    rebar3 writes the list of compiled modules into the final .app file under _build.

  9. 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.

  10. Why is counter:value() 1 after one counter:increment() in the session?

    Answer

    The cast added one to the state 0 from init/1

    init(0) starts the state at zero and the increment cast 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

Banner image