How to start and stop the code for the application, including its supervision -tree, is described by two callback functions:
start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State}
-stop(State)start/2 is called when starting the application and is to create the
+tree, is described by two callback functions:start(StartType, StartArgs) -> {ok, Pid} | {ok, Pid, State}
+stop(State)start/2 is called when starting the application and is to create the
supervision tree by starting the top supervisor. It is expected to return the
pid of the top supervisor and an optional term, State, which defaults to
[]. This term is passed as is to stop/1.StartType is usually the atom normal. It has other values only in the case
@@ -40,15 +40,15 @@
necessary cleaning up. The actual stopping of the application, that is,
shutting down the supervision tree, is handled automatically as described in
Starting and Stopping Applications.Example of an application callback module for packaging the supervision tree -from Supervisor Behaviour:
-module(ch_app).
--behaviour(application).
+from Supervisor Behaviour:-module(ch_app).
+-behaviour(application).
--export([start/2, stop/1]).
+-export([start/2, stop/1]).
-start(_Type, _Args) ->
- ch_sup:start_link().
+start(_Type, _Args) ->
+ ch_sup:start_link().
-stop(_State) ->
+stop(_State) ->
ok.
A library application that cannot be started or stopped does not need any
application callback module.
Application Resource File
To define an application, an application specification is created, which is
put in an application resource file, or in short an .app file:
{application, Application, [Opt1,...,OptN]}.
Application, an atom, is the name of the application. The file must be named
@@ -61,14 +61,14 @@
in this case ch_app and [], respectively. This means that the following is
called when the application is to be started:ch_app:start(normal, [])
The following is called when the application is stopped:
ch_app:stop([])
When using systools, the Erlang/OTP tools for packaging code (see Section
Releases), the keys description, vsn, modules,
-registered, and applications are also to be specified:
{application, ch_app,
- [{description, "Channel allocator"},
- {vsn, "1"},
- {modules, [ch_app, ch_sup, ch3]},
- {registered, [ch3]},
- {applications, [kernel, stdlib, sasl]},
- {mod, {ch_app,[]}}
- ]}.
description - A short description, a string. Defaults to "".vsn - Version number, a string. Defaults to "".modules - All modules introduced by this application. systools uses
+registered, and applications are also to be specified:{application, ch_app,
+ [{description, "Channel allocator"},
+ {vsn, "1"},
+ {modules, [ch_app, ch_sup, ch3]},
+ {registered, [ch3]},
+ {applications, [kernel, stdlib, sasl]},
+ {mod, {ch_app,[]}}
+ ]}.
description - A short description, a string. Defaults to "".vsn - Version number, a string. Defaults to "".modules - All modules introduced by this application. systools uses
this list when generating boot scripts and tar files. A module must only
be included in one application. Defaults to [].registered - All names of registered processes in the application.
systools uses this list to detect name clashes between applications.
@@ -158,24 +158,24 @@
controller process, registered as application_controller.All operations on applications are coordinated by the application
controller. Use module application in Kernel to load, unload, start, and
stop applications.
Loading and Unloading Applications
Before an application can be started, it must be loaded. The application
-controller reads and stores the information from the .app file:
1> application:load(ch_app).
+controller reads and stores the information from the .app file:1> application:load(ch_app).
ok
-2> application:loaded_applications().
-[{kernel,"ERTS CXC 138 10","2.8.1.3"},
- {stdlib,"ERTS CXC 138 10","1.11.4.3"},
- {ch_app,"Channel allocator","1"}]
An application that has been stopped, or has never been started, can be
+2>
application:loaded_applications().
+[{kernel,"ERTS CXC 138 10","2.8.1.3"},
+ {stdlib,"ERTS CXC 138 10","1.11.4.3"},
+ {ch_app,"Channel allocator","1"}]
An application that has been stopped, or has never been started, can be
unloaded. The information about the application is erased from the internal
-database of the application controller.
3> application:unload(ch_app).
+database of the application controller.3> application:unload(ch_app).
ok
-4> application:loaded_applications().
-[{kernel,"ERTS CXC 138 10","2.8.1.3"},
- {stdlib,"ERTS CXC 138 10","1.11.4.3"}]
Note
Loading/unloading an application does not load/unload the code used by the
-application. Code loading is handled in the usual way by the code server.
Starting and Stopping Applications
An application is started by calling:
5> application:start(ch_app).
-ok
-6> application:which_applications().
-[{kernel,"ERTS CXC 138 10","2.8.1.3"},
- {stdlib,"ERTS CXC 138 10","1.11.4.3"},
- {ch_app,"Channel allocator","1"}]
If the application is not already loaded, the application controller first loads
+4>
application:loaded_applications().
+[{kernel,"ERTS CXC 138 10","2.8.1.3"},
+ {stdlib,"ERTS CXC 138 10","1.11.4.3"}]
Note
Loading/unloading an application does not load/unload the code used by the
+application. Code loading is handled in the usual way by the code server.
Starting and Stopping Applications
An application is started by calling:
5> application:start(ch_app).
+ok
+6> application:which_applications().
+[{kernel,"ERTS CXC 138 10","2.8.1.3"},
+ {stdlib,"ERTS CXC 138 10","1.11.4.3"},
+ {ch_app,"Channel allocator","1"}]
If the application is not already loaded, the application controller first loads
it using application:load/1. It checks the value of the applications key to
ensure that all applications that are to be started before this application are
running.
Following that, the application controller creates an application master for
@@ -193,47 +193,47 @@
on; the entire tree is terminated in reversed start order. The application
master then calls the application callback function stop/1 in the module
defined by the mod key.
Configuring an Application
An application can be configured using configuration parameters. These are a
-list of {Par,Val} tuples specified by a key env in the .app file:
{application, ch_app,
- [{description, "Channel allocator"},
- {vsn, "1"},
- {modules, [ch_app, ch_sup, ch3]},
- {registered, [ch3]},
- {applications, [kernel, stdlib, sasl]},
- {mod, {ch_app,[]}},
- {env, [{file, "/usr/local/log"}]}
- ]}.
Par is to be an atom. Val is any term. The application can retrieve the
+list of {Par,Val} tuples specified by a key env in the .app file:
{application, ch_app,
+ [{description, "Channel allocator"},
+ {vsn, "1"},
+ {modules, [ch_app, ch_sup, ch3]},
+ {registered, [ch3]},
+ {applications, [kernel, stdlib, sasl]},
+ {mod, {ch_app,[]}},
+ {env, [{file, "/usr/local/log"}]}
+ ]}.
Par is to be an atom. Val is any term. The application can retrieve the
value of a configuration parameter by calling application:get_env(App, Par) or
a number of similar functions. For more information, see module application
in Kernel.
Example:
% erl
-Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
+Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
-Eshell V5.2.3.6 (abort with ^G)
-1> application:start(ch_app).
+Eshell V5.2.3.6 (abort with ^G)
+1> application:start(ch_app).
ok
-2> application:get_env(ch_app, file).
-{ok,"/usr/local/log"}
The values in the .app file can be overridden by values in a system
+2>
application:get_env(ch_app, file).
+{ok,"/usr/local/log"}The values in the .app file can be overridden by values in a system
configuration file. This is a file that contains configuration parameters for
-relevant applications:
[{Application1, [{Par11,Val11},...]},
+relevant applications:[{Application1, [{Par11,Val11},...]},
...,
- {ApplicationN, [{ParN1,ValN1},...]}].
The system configuration is to be called Name.config and Erlang is to be
+
{ApplicationN, [{ParN1,ValN1},...]}].The system configuration is to be called Name.config and Erlang is to be
started with the command-line argument -config Name. For details, see
config in Kernel.
Example:
A file test.config is created with the following contents:
[{ch_app, [{file, "testlog"}]}].The value of file overrides the value of file as defined in the .app file:
% erl -config test
-Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
+Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
-Eshell V5.2.3.6 (abort with ^G)
-1> application:start(ch_app).
+Eshell V5.2.3.6 (abort with ^G)
+1> application:start(ch_app).
ok
-2> application:get_env(ch_app, file).
-{ok,"testlog"}If release handling is used, exactly one system +2> application:get_env(ch_app, file). +{ok,"testlog"}
If release handling is used, exactly one system
configuration file is to be used and that file is to be called sys.config.
The values in the .app file and the values in a system configuration file can
be overridden directly from the command line:
% erl -ApplName Par1 Val1 ... ParN ValNExample:
% erl -ch_app file '"testlog"'
-Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
+Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
-Eshell V5.2.3.6 (abort with ^G)
-1> application:start(ch_app).
+Eshell V5.2.3.6 (abort with ^G)
+1> application:start(ch_app).
ok
-2> application:get_env(ch_app, file).
-{ok,"testlog"}A start type is defined when starting the application:
application:start(Application, Type)application:start(Application) is the same as calling
+2> application:get_env(ch_app, file).
+{ok,"testlog"}
A start type is defined when starting the application:
application:start(Application, Type)application:start(Application) is the same as calling
application:start(Application, temporary). The type can also be permanent or
transient:
normal, this is reported
/usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/appup_cookbook.xhtml differs (HTML document, ASCII text, with very long lines (1058))
--- "old//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/appup_cookbook.xhtml" 2026-08-05 05:56:49.000000000 +0000
+++ "new//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/appup_cookbook.xhtml" 2026-08-05 05:56:49.000000000 +0000
@@ -20,20 +20,20 @@
This section includes examples of .appup files for typical cases of
upgrades/downgrades done in runtime.
When a functional module has been changed, for example, if a new function has been added or a bug has been corrected, simple code replacement is sufficient, -for example:
{"2",
- [{"1", [{load_module, m}]}],
- [{"1", [{load_module, m}]}]
-}.In a system implemented according to the OTP design principles, all processes, +for example:
{"2",
+ [{"1", [{load_module, m}]}],
+ [{"1", [{load_module, m}]}]
+}.In a system implemented according to the OTP design principles, all processes,
except system processes and special processes, reside in one of the behaviours
supervisor, gen_server, gen_statem, gen_event, or gen_fsm.
These belong to the STDLIB application and upgrading/downgrading normally
requires a runtime system restart.
Thus, OTP provides no support for changing residence modules except in the case of special processes.
A callback module is a functional module, and for code extensions simple code replacement is sufficient.
Example
When adding a function to ch3, as described in the example in
-Release Handling, ch_app.appup looks as follows:
{"2",
- [{"1", [{load_module, ch3}]}],
- [{"1", [{load_module, ch3}]}]
-}.OTP also supports changing the internal state of behaviour processes; see
+Release Handling, ch_app.appup looks as follows:
{"2",
+ [{"1", [{load_module, ch3}]}],
+ [{"1", [{load_module, ch3}]}]
+}.OTP also supports changing the internal state of behaviour processes; see Changing Internal State.
In this case, simple code replacement is not sufficient. The process must
explicitly transform its state using the callback function code_change/3 before
switching to the new version of the callback module. Thus, synchronized code
@@ -41,21 +41,21 @@
gen_server Behaviour. The internal state is a term
Chs representing the available channels. Assume you want to add a counter N,
which keeps track of the number of alloc requests so far. This means that the
-format must be changed to {Chs,N}.
The .appup file can look as follows:
{"2",
- [{"1", [{update, ch3, {advanced, []}}]}],
- [{"1", [{update, ch3, {advanced, []}}]}]
-}.The third element of the update instruction is a tuple {advanced,Extra},
+format must be changed to {Chs,N}.
The .appup file can look as follows:
{"2",
+ [{"1", [{update, ch3, {advanced, []}}]}],
+ [{"1", [{update, ch3, {advanced, []}}]}]
+}.The third element of the update instruction is a tuple {advanced,Extra},
which says that the affected processes are to do a state transformation before
loading the new version of the module. This is done by the processes calling the
callback function code_change/3 (see gen_server in STDLIB).
-The term Extra, in this case [], is passed as is to the function:
-module(ch3).
+The term Extra, in this case [], is passed as is to the function:-module(ch3).
...
--export([code_change/3]).
+-export([code_change/3]).
...
-code_change({down, _Vsn}, {Chs, N}, _Extra) ->
- {ok, Chs};
-code_change(_Vsn, Chs, _Extra) ->
- {ok, {Chs, 0}}.
The first argument is {down,Vsn} if there is a downgrade, or Vsn if there is
+
code_change({down, _Vsn}, {Chs, N}, _Extra) ->
+ {ok, Chs};
+code_change(_Vsn, Chs, _Extra) ->
+ {ok, {Chs, 0}}.The first argument is {down,Vsn} if there is a downgrade, or Vsn if there is
a upgrade. The term Vsn is fetched from the 'original' version of the module,
that is, the version you are upgrading from, or downgrading to.
The version is defined by the module attribute vsn, if any. There is no such
attribute in ch3, so in this case the version is the checksum (a huge integer)
@@ -66,29 +66,29 @@
can occur during release upgrade if the new version of m1 is loaded first and
calls ch3:available/0 before the new version of ch3 is loaded.
Thus, ch3 must be loaded before m1, in the upgrade case, and conversely in
the downgrade case. m1 is said to be dependent on ch3. In a release
-handling instruction, this is expressed by the DepMods element:
{load_module, Module, DepMods}
-{update, Module, {advanced, Extra}, DepMods}DepMods is a list of modules, on which Module is dependent.
Example
The module m1 in application myapp is dependent on ch3 when
+handling instruction, this is expressed by the DepMods element:
{load_module, Module, DepMods}
+{update, Module, {advanced, Extra}, DepMods}DepMods is a list of modules, on which Module is dependent.
Example
The module m1 in application myapp is dependent on ch3 when
upgrading from "1" to "2", or downgrading from "2" to "1":
myapp.appup:
-{"2",
- [{"1", [{load_module, m1, [ch3]}]}],
- [{"1", [{load_module, m1, [ch3]}]}]
-}.
+{"2",
+ [{"1", [{load_module, m1, [ch3]}]}],
+ [{"1", [{load_module, m1, [ch3]}]}]
+}.
ch_app.appup:
-{"2",
- [{"1", [{load_module, ch3}]}],
- [{"1", [{load_module, ch3}]}]
-}.If instead m1 and ch3 belong to the same application, the .appup file can
-look as follows:
{"2",
- [{"1",
- [{load_module, ch3},
- {load_module, m1, [ch3]}]}],
- [{"1",
- [{load_module, ch3},
- {load_module, m1, [ch3]}]}]
-}.m1 is dependent on ch3 also when downgrading. systools knows the
+{"2",
+ [{"1", [{load_module, ch3}]}],
+ [{"1", [{load_module, ch3}]}]
+}.
If instead m1 and ch3 belong to the same application, the .appup file can
+look as follows:
{"2",
+ [{"1",
+ [{load_module, ch3},
+ {load_module, m1, [ch3]}]}],
+ [{"1",
+ [{load_module, ch3},
+ {load_module, m1, [ch3]}]}]
+}.m1 is dependent on ch3 also when downgrading. systools knows the
difference between up- and downgrading and generates a correct relup, where
ch3 is loaded before m1 when upgrading, but m1 is loaded before ch3 when
downgrading.
In this case, simple code replacement is not sufficient. When a new version of a @@ -97,22 +97,22 @@ synchronized code replacement must be used.
The name(s) of the user-defined residence module(s) must be listed in the
Modules part of the child specification for the special process. Otherwise
the release handler cannot find the process.
Example
Consider the example ch4 in sys and proc_lib.
-When started by a supervisor, the child specification can look as follows:
{ch4, {ch4, start_link, []},
- permanent, brutal_kill, worker, [ch4]}If ch4 is part of the application sp_app and a new version of the module is
+When started by a supervisor, the child specification can look as follows:
{ch4, {ch4, start_link, []},
+ permanent, brutal_kill, worker, [ch4]}If ch4 is part of the application sp_app and a new version of the module is
to be loaded when upgrading from version "1" to "2" of this application,
-sp_app.appup can look as follows:
{"2",
- [{"1", [{update, ch4, {advanced, []}}]}],
- [{"1", [{update, ch4, {advanced, []}}]}]
-}.The update instruction must contain the tuple {advanced,Extra}. The
+sp_app.appup can look as follows:
{"2",
+ [{"1", [{update, ch4, {advanced, []}}]}],
+ [{"1", [{update, ch4, {advanced, []}}]}]
+}.The update instruction must contain the tuple {advanced,Extra}. The
instruction makes the special process call the callback function
system_code_change/4, a function the user must implement. The term Extra, in
-this case [], is passed as is to system_code_change/4:
-module(ch4).
+this case [], is passed as is to system_code_change/4:-module(ch4).
...
--export([system_code_change/4]).
+-export([system_code_change/4]).
...
-system_code_change(Chs, _Module, _OldVsn, _Extra) ->
- {ok, Chs}.
- The first argument is the internal state
State, passed from
+
system_code_change(Chs, _Module, _OldVsn, _Extra) ->
+ {ok, Chs}.State, passed from
function sys:handle_system_msg(Request, From, Parent, Module, Deb, State), and called by the special
process when a system message is received. In ch4, the internal
state is the set of available channels Chs.ch4).Vsn or {down,Vsn}, as described for
@@ -129,18 +129,18 @@
of upgrade and downgrade. Then the new return value of init/1 can be checked
and the internal state be changed accordingly.The following upgrade instruction is used for supervisors:
{update, Module, supervisor}Example
To change the restart strategy of ch_sup (from
Supervisor Behaviour) from one_for_one to one_for_all,
-change the callback function init/1 in ch_sup.erl:
-module(ch_sup).
+change the callback function init/1 in ch_sup.erl:-module(ch_sup).
...
-init(_Args) ->
- {ok, {#{strategy => one_for_all, ...}, ...}}.
The file ch_app.appup:
{"2",
- [{"1", [{update, ch_sup, supervisor}]}],
- [{"1", [{update, ch_sup, supervisor}]}]
-}.
Changing Child Specifications
The instruction, and thus the .appup file, when changing an existing child
-specification, is the same as when changing properties as described earlier:
{"2",
- [{"1", [{update, ch_sup, supervisor}]}],
- [{"1", [{update, ch_sup, supervisor}]}]
-}.
The changes do not affect existing child processes. For example, changing the
+
init(_Args) ->
+ {ok, {#{strategy => one_for_all, ...}, ...}}.The file ch_app.appup:
{"2",
+ [{"1", [{update, ch_sup, supervisor}]}],
+ [{"1", [{update, ch_sup, supervisor}]}]
+}.The instruction, and thus the .appup file, when changing an existing child
+specification, is the same as when changing properties as described earlier:
{"2",
+ [{"1", [{update, ch_sup, supervisor}]}],
+ [{"1", [{update, ch_sup, supervisor}]}]
+}.The changes do not affect existing child processes. For example, changing the start function only specifies how the child process is to be restarted, if needed later on.
The id of the child specification cannot be changed.
Changing the Modules field of the child specification can affect the release
handling process itself, as this field is used to identify which processes are
@@ -149,39 +149,39 @@
Child processes are not automatically started or terminated, this must be done
using apply instructions.
Example
Assume a new child process m1 is to be added to ch_sup when
upgrading ch_app from "1" to "2". This means m1 is to be deleted when
-downgrading from "2" to "1":
{"2",
- [{"1",
- [{update, ch_sup, supervisor},
- {apply, {supervisor, restart_child, [ch_sup, m1]}}
- ]}],
- [{"1",
- [{apply, {supervisor, terminate_child, [ch_sup, m1]}},
- {apply, {supervisor, delete_child, [ch_sup, m1]}},
- {update, ch_sup, supervisor}
- ]}]
-}.The order of the instructions is important.
The supervisor must be registered as ch_sup for the script to work. If the
+downgrading from "2" to "1":
{"2",
+ [{"1",
+ [{update, ch_sup, supervisor},
+ {apply, {supervisor, restart_child, [ch_sup, m1]}}
+ ]}],
+ [{"1",
+ [{apply, {supervisor, terminate_child, [ch_sup, m1]}},
+ {apply, {supervisor, delete_child, [ch_sup, m1]}},
+ {update, ch_sup, supervisor}
+ ]}]
+}.The order of the instructions is important.
The supervisor must be registered as ch_sup for the script to work. If the
supervisor is not registered, it cannot be accessed directly from the script.
/usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/benchmarking.xhtml differs (HTML document, ASCII text, with very long lines (793))
--- "old//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/benchmarking.xhtml" 2026-08-05 05:56:49.000000000 +0000
+++ "new//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/benchmarking.xhtml" 2026-08-05 05:56:49.000000000 +0000
@@ -44,8 +44,8 @@
crypto:strong_rand_bytes(100). 1 1915 Ki 522 ns 90%
rand:bytes/1 is still faster when we generate 100 bytes at the time,
but the relative difference is smaller.
% erlperf 'rand:bytes(1000).' 'crypto:strong_rand_bytes(1000).'
Code || QPS Time Rel
-crypto:strong_rand_bytes(1000). 1 1518 Ki 658 ns 100%
-rand:bytes(1000). 1 284 Ki 3521 ns 19%When we generate 1000 bytes at the time, crypto:strong_rand_bytes/1 is
+crypto:strong_rand_bytes(1000). 1 1518 Ki 658 ns 100%
+rand:bytes(1000). 1 284 Ki 3521 ns 19%
When we generate 1000 bytes at the time, crypto:strong_rand_bytes/1 is
now the fastest.
Benchmarks can measure wall-clock time or CPU time.
timer:tc/3 measures wall-clock time. The advantage with wall-clock time is
that I/O, swapping, and other activities in the operating system kernel are
included in the measurements. The disadvantage is that the measurements often
/usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/binaryhandling.xhtml differs (HTML document, ASCII text, with very long lines (943))
--- "old//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/binaryhandling.xhtml" 2026-08-05 05:56:49.000000000 +0000
+++ "new//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/binaryhandling.xhtml" 2026-08-05 05:56:49.000000000 +0000
@@ -20,35 +20,35 @@
This section gives a few examples on how to handle binaries in an efficient way. The sections that follow take an in-depth look at how binaries are implemented and how to best take advantages of the optimizations done by the compiler and -runtime system.
Binaries can be efficiently built in the following way:
DO
my_list_to_binary(List) ->
- my_list_to_binary(List, <<>>).
+runtime system.Binaries can be efficiently built in the following way:
DO
my_list_to_binary(List) ->
+ my_list_to_binary(List, <<>>).
-my_list_to_binary([H|T], Acc) ->
- my_list_to_binary(T, <<Acc/binary,H>>);
-my_list_to_binary([], Acc) ->
+my_list_to_binary([H|T], Acc) ->
+ my_list_to_binary(T, <<Acc/binary,H>>);
+my_list_to_binary([], Acc) ->
Acc.
Appending data to a binary as in the example is efficient because it is
specially optimized by the runtime system to avoid copying the Acc binary
-every time.
Prepending data to a binary in a loop is not efficient:
DO NOT
rev_list_to_binary(List) ->
- rev_list_to_binary(List, <<>>).
+every time.Prepending data to a binary in a loop is not efficient:
DO NOT
rev_list_to_binary(List) ->
+ rev_list_to_binary(List, <<>>).
-rev_list_to_binary([H|T], Acc) ->
- rev_list_to_binary(T, <<H,Acc/binary>>);
-rev_list_to_binary([], Acc) ->
+rev_list_to_binary([H|T], Acc) ->
+ rev_list_to_binary(T, <<H,Acc/binary>>);
+rev_list_to_binary([], Acc) ->
Acc.
This is not efficient for long lists because the Acc binary is copied every
-time. One way to make the function more efficient is like this:
DO NOT
rev_list_to_binary(List) ->
- rev_list_to_binary(lists:reverse(List), <<>>).
+time. One way to make the function more efficient is like this:DO NOT
rev_list_to_binary(List) ->
+ rev_list_to_binary(lists:reverse(List), <<>>).
-rev_list_to_binary([H|T], Acc) ->
- rev_list_to_binary(T, <<Acc/binary,H>>);
-rev_list_to_binary([], Acc) ->
- Acc.
Another way to avoid copying the binary each time is like this:
DO
rev_list_to_binary([H|T]) ->
- RevTail = rev_list_to_binary(T),
- <<RevTail/binary,H>>;
-rev_list_to_binary([]) ->
- <<>>.
Note that in each of the DO examples, the binary to be appended to is always
-given as the first segment.
Binaries can be efficiently matched in the following way:
DO
my_binary_to_list(<<H,T/binary>>) ->
- [H|my_binary_to_list(T)];
-my_binary_to_list(<<>>) -> [].
How Binaries are Implemented
Internally, binaries and bitstrings are implemented in the same way. In this
+
rev_list_to_binary([H|T], Acc) ->
+ rev_list_to_binary(T, <<Acc/binary,H>>);
+rev_list_to_binary([], Acc) ->
+ Acc.
Another way to avoid copying the binary each time is like this:
DO
rev_list_to_binary([H|T]) ->
+ RevTail = rev_list_to_binary(T),
+ <<RevTail/binary,H>>;
+rev_list_to_binary([]) ->
+ <<>>.
Note that in each of the DO examples, the binary to be appended to is always
+given as the first segment.
Binaries can be efficiently matched in the following way:
DO
my_binary_to_list(<<H,T/binary>>) ->
+ [H|my_binary_to_list(T)];
+my_binary_to_list(<<>>) -> [].
How Binaries are Implemented
Internally, binaries and bitstrings are implemented in the same way. In this
section, they are called binaries because that is what they are called in the
emulator source code.
Four types of binary objects are available internally:
Two are containers for binary data and are called:
- Refc binaries (short for reference-counted binaries)
- Heap binaries
Two are merely references to a part of a binary and are called:
- sub binaries
- match contexts
Change
In Erlang/OTP 27, the handling of binaries and bitstrings were
rewritten. To fully leverage those changes in the run-time system,
@@ -75,21 +75,21 @@
Instead of creating a sub binary, the match context is kept.
The compiler can only do this optimization if it knows that the match context
will not be shared. If it would be shared, the functional properties (also
called referential transparency) of Erlang would break.
Constructing Binaries
Appending to a binary or bitstring in the following way is specially optimized
-to avoid copying the binary:
<<Binary/binary, ...>>
+to avoid copying the binary:<<Binary/binary, ...>>
%% - OR -
-<<Binary/bitstring, ...>>
This optimization is applied by the runtime system in a way that makes it
+
<<Binary/bitstring, ...>>
This optimization is applied by the runtime system in a way that makes it
effective in most circumstances (for exceptions, see
Circumstances That Force Copying). The
optimization in its basic form does not need any help from the compiler.
However, the compiler add hints to the runtime system when it is safe to apply
the optimization in a more efficient way.
Change
The compiler support for making the optimization more efficient was added in
Erlang/OTP 26.
To explain how the basic optimization works, let us examine the following code
-line by line:
Bin0 = <<0>>, %% 1
-Bin1 = <<Bin0/binary,1,2,3>>, %% 2
-Bin2 = <<Bin1/binary,4,5,6>>, %% 3
-Bin3 = <<Bin2/binary,7,8,9>>, %% 4
-Bin4 = <<Bin1/binary,17>>, %% 5 !!!
-{Bin4,Bin3} %% 6
Line 1 (marked with the %% 1 comment), assigns a
+line by line:
Bin0 = <<0>>, %% 1
+Bin1 = <<Bin0/binary,1,2,3>>, %% 2
+Bin2 = <<Bin1/binary,4,5,6>>, %% 3
+Bin3 = <<Bin2/binary,7,8,9>>, %% 4
+Bin4 = <<Bin1/binary,17>>, %% 5 !!!
+{Bin4,Bin3} %% 6
Line 1 (marked with the %% 1 comment), assigns a
heap binary to the Bin0 variable.
Line 2 is an append operation. As Bin0 has not been involved in an append
operation, a new refc binary is created and
the contents of Bin0 is copied into it. The ProcBin part of the refc
@@ -117,15 +117,15 @@
for every append operation, the runtime system must create a sub binary.
When the compiler can determine that none of those situations need to be handled
and that the append operation cannot possibly fail, the compiler generates code
that causes the runtime system to apply a more efficient variant of the
-optimization.
Example:
-module(repack).
--export([repack/1]).
+optimization.Example:
-module(repack).
+-export([repack/1]).
-repack(Bin) when is_binary(Bin) ->
- repack(Bin, <<>>).
+repack(Bin) when is_binary(Bin) ->
+ repack(Bin, <<>>).
-repack(<<C:8,T/binary>>, Result) ->
- repack(T, <<Result/binary,C:16>>);
-repack(<<>>, Result) ->
+repack(<<C:8,T/binary>>, Result) ->
+ repack(T, <<Result/binary,C:16>>);
+repack(<<>>, Result) ->
Result.
The repack/2 function only keeps a single version of the binary, so there is
never any need to copy the binary. The compiler rewrites the creation of the
empty binary in repack/1 to instead create a refc binary with 256 bytes
@@ -139,26 +139,26 @@
operation will be forced to copy the binary. In most cases, the binary object
will be shrunk at the same time to reclaim the extra space allocated for
growing.
When appending to a binary as follows, only the binary returned from the latest
-append operation will support further cheap append operations:
Bin = <<Bin0,...>>
In the code fragment in the beginning of this section, appending to Bin will
+append operation will support further cheap append operations:
Bin = <<Bin0,...>>
In the code fragment in the beginning of this section, appending to Bin will
be cheap, while appending to Bin0 will force the creation of a new binary and
copying of the contents of Bin0.
If a binary is sent as a message to a process or port, the binary will be shrunk
and any further append operation will copy the binary data into a new binary.
For example, in the following code fragment Bin1 will be copied in the third
-line:
Bin1 = <<Bin0,...>>,
+line:Bin1 = <<Bin0,...>>,
PortOrPid ! Bin1,
-Bin = <<Bin1,...>> %% Bin1 will be COPIED
The same happens if you insert a binary into an Ets table, send it to a port
+
Bin = <<Bin1,...>> %% Bin1 will be COPIED
The same happens if you insert a binary into an Ets table, send it to a port
using erlang:port_command/2, or pass it to
enif_inspect_binary in a NIF.
Matching a binary will also cause it to shrink and the next append operation
-will copy the binary data:
Bin1 = <<Bin0,...>>,
-<<X,Y,Z,T/binary>> = Bin1,
-Bin = <<Bin1,...>> %% Bin1 will be COPIED
The reason is that a match context contains a
+will copy the binary data:
Bin1 = <<Bin0,...>>,
+<<X,Y,Z,T/binary>> = Bin1,
+Bin = <<Bin1,...>> %% Bin1 will be COPIED
The reason is that a match context contains a
direct pointer to the binary data.
If a process simply keeps binaries (either in "loop data" or in the process
dictionary), the garbage collector can eventually shrink the binaries. If only
one such binary is kept, it will not be shrunk. If the process later appends to
a binary that has been shrunk, the binary object will be reallocated to make
-place for the data to be appended.
Matching Binaries
Let us revisit the example in the beginning of the previous section:
DO
my_binary_to_list(<<H,T/binary>>) ->
- [H|my_binary_to_list(T)];
-my_binary_to_list(<<>>) -> [].
The first time my_binary_to_list/1 is called, a
+place for the data to be appended.
Matching Binaries
Let us revisit the example in the beginning of the previous section:
DO
my_binary_to_list(<<H,T/binary>>) ->
+ [H|my_binary_to_list(T)];
+my_binary_to_list(<<>>) -> [].
The first time my_binary_to_list/1 is called, a
match context is created. The match context
points to the first byte of the binary. 1 byte is matched out and the match
context is updated to point to the second byte in the binary.
At this point it would make sense to create a
@@ -173,24 +173,24 @@
there is no longer any reference to it).
To summarize, my_binary_to_list/1 only needs to create one match context and
no sub binaries.
Notice that the match context in my_binary_to_list/1 was discarded when the
entire binary had been traversed. What happens if the iteration stops before it
-has reached the end of the binary? Will the optimization still work?
after_zero(<<0,T/binary>>) ->
+has reached the end of the binary? Will the optimization still work?after_zero(<<0,T/binary>>) ->
T;
-after_zero(<<_,T/binary>>) ->
- after_zero(T);
-after_zero(<<>>) ->
- <<>>.
Yes, it will. The compiler will remove the building of the sub binary in the
+
after_zero(<<_,T/binary>>) ->
+ after_zero(T);
+after_zero(<<>>) ->
+ <<>>.
Yes, it will. The compiler will remove the building of the sub binary in the
second clause:
...
-after_zero(<<_,T/binary>>) ->
- after_zero(T);
-...
But it will generate code that builds a sub binary in the first clause:
after_zero(<<0,T/binary>>) ->
+after_zero(<<_,T/binary>>) ->
+ after_zero(T);
+...
But it will generate code that builds a sub binary in the first clause:
after_zero(<<0,T/binary>>) ->
T;
...
Therefore, after_zero/1 builds one match context and one sub binary (assuming
-it is passed a binary that contains a zero byte).
Code like the following will also be optimized:
all_but_zeroes_to_list(Buffer, Acc, 0) ->
- {lists:reverse(Acc),Buffer};
-all_but_zeroes_to_list(<<0,T/binary>>, Acc, Remaining) ->
- all_but_zeroes_to_list(T, Acc, Remaining-1);
-all_but_zeroes_to_list(<<Byte,T/binary>>, Acc, Remaining) ->
- all_but_zeroes_to_list(T, [Byte|Acc], Remaining-1).
The compiler removes building of sub binaries in the second and third clauses,
+it is passed a binary that contains a zero byte).
Code like the following will also be optimized:
all_but_zeroes_to_list(Buffer, Acc, 0) ->
+ {lists:reverse(Acc),Buffer};
+all_but_zeroes_to_list(<<0,T/binary>>, Acc, Remaining) ->
+ all_but_zeroes_to_list(T, Acc, Remaining-1);
+all_but_zeroes_to_list(<<Byte,T/binary>>, Acc, Remaining) ->
+ all_but_zeroes_to_list(T, [Byte|Acc], Remaining-1).
The compiler removes building of sub binaries in the second and third clauses,
and it adds an instruction to the first clause that converts Buffer from a
match context to a sub binary (or do nothing if Buffer is a binary already).
But in more complicated code, how can one know whether the optimization is
applied or not?
Option bin_opt_info
Use the bin_opt_info option to have the compiler print a lot of information
@@ -200,24 +200,24 @@
practical approach.
The warnings look as follows:
./efficiency_guide.erl:60: Warning: NOT OPTIMIZED: binary is returned from the function
./efficiency_guide.erl:62: Warning: OPTIMIZED: match context reused
To make it clearer exactly what code the warnings refer to, the warnings in the
following examples are inserted as comments after the clause they refer to, for
-example:
after_zero(<<0,T/binary>>) ->
+example:after_zero(<<0,T/binary>>) ->
%% BINARY CREATED: binary is returned from the function
T;
-after_zero(<<_,T/binary>>) ->
+after_zero(<<_,T/binary>>) ->
%% OPTIMIZED: match context reused
/usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/bit_syntax.xhtml differs (HTML document, ASCII text, with very long lines (1935))
--- "old//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/bit_syntax.xhtml" 2026-08-05 05:56:49.000000000 +0000
+++ "new//usr/share/doc/packages/erlang-doc/doc/system/Erlang System Documentation.epub/OEBPS/bit_syntax.xhtml" 2026-08-05 05:56:49.000000000 +0000
@@ -19,34 +19,34 @@
Bit Syntax
Introduction
The complete specification for the bit syntax appears in the
Reference Manual.
In Erlang, a Bin is used for constructing binaries and matching binary patterns.
-A Bin is written with the following syntax:
<<E1, E2, ... En>>
A Bin is a low-level sequence of bits or bytes. The purpose of a Bin is to
-enable construction of binaries:
Bin = <<E1, E2, ... En>>
All elements must be bound. Or match a binary:
<<E1, E2, ... En>> = Bin
Here, Bin is bound and the elements are bound or unbound, as in any match.
A Bin does not need to consist of a whole number of bytes.
A bitstring is a sequence of zero or more bits, where the number of bits does
+A Bin is written with the following syntax:
<<E1, E2, ... En>>
A Bin is a low-level sequence of bits or bytes. The purpose of a Bin is to
+enable construction of binaries:
Bin = <<E1, E2, ... En>>
All elements must be bound. Or match a binary:
<<E1, E2, ... En>> = Bin
Here, Bin is bound and the elements are bound or unbound, as in any match.
A Bin does not need to consist of a whole number of bytes.
A bitstring is a sequence of zero or more bits, where the number of bits does
not need to be divisible by 8. If the number of bits is divisible by 8, the
bitstring is also a binary.
Each element specifies a certain segment of the bitstring. A segment is a set
of contiguous bits of the binary (not necessarily on a byte boundary). The first
element specifies the initial segment, the second element specifies the
following segment, and so on.
The following examples illustrate how binaries are constructed, or matched, and
how elements and tails are specified.
Examples
Example 1: A binary can be constructed from a set of constants or a string
-literal:
Bin11 = <<1, 17, 42>>,
-Bin12 = <<"abc">>
This gives two binaries of size 3, with the following evaluations:
binary_to_list(Bin11) evaluates to [1, 17, 42].binary_to_list(Bin12) evaluates to [97, 98, 99].
Example 2:Similarly, a binary can be constructed from a set of bound
+literal:
Bin11 = <<1, 17, 42>>,
+Bin12 = <<"abc">>
This gives two binaries of size 3, with the following evaluations:
binary_to_list(Bin11) evaluates to [1, 17, 42].binary_to_list(Bin12) evaluates to [97, 98, 99].
Example 2:Similarly, a binary can be constructed from a set of bound
variables:
A = 1, B = 17, C = 42,
-Bin2 = <<A, B, C:16>>
This gives a binary of size 4. Here, a size expression is used for the
+
Bin2 = <<A, B, C:16>>
This gives a binary of size 4. Here, a size expression is used for the
variable C to specify a 16-bits segment of Bin2.
binary_to_list(Bin2) evaluates to [1, 17, 00, 42].
Example 3: A Bin can also be used for matching. D, E, and F are unbound
-variables, and Bin2 is bound, as in Example 2:
<<D:16, E, F/binary>> = Bin2
This gives D = 273, E = 00, and F binds to a binary of size 1:
+variables, and Bin2 is bound, as in Example 2:
<<D:16, E, F/binary>> = Bin2
This gives D = 273, E = 00, and F binds to a binary of size 1:
binary_to_list(F) = [42].
Example 4: The following is a more elaborate example of matching. Here,
Dgram is bound to the consecutive bytes of an IP datagram of IP protocol
-version 4. The ambition is to extract the header and the data of the datagram:
-define(IP_VERSION, 4).
--define(IP_MIN_HDR_LEN, 5).
+version 4. The ambition is to extract the header and the data of the datagram:-define(IP_VERSION, 4).
+-define(IP_MIN_HDR_LEN, 5).
-DgramSize = byte_size(Dgram),
+DgramSize = byte_size(Dgram),
case Dgram of
- <<?IP_VERSION:4, HLen:4, SrvcType:8, TotLen:16,
+ <<?IP_VERSION:4, HLen:4, SrvcType:8, TotLen:16,
ID:16, Flgs:3, FragOff:13,
TTL:8, Proto:8, HdrChkSum:16,
SrcIP:32,
- DestIP:32, RestDgram/binary>> when HLen>=5, 4*HLen=<DgramSize ->
- OptsLen = 4*(HLen - ?IP_MIN_HDR_LEN),
- <<Opts:OptsLen/binary,Data/binary>> = RestDgram,
+ DestIP:32, RestDgram/binary>> when HLen>=5, 4*HLen=<DgramSize ->
+ OptsLen = 4*(HLen - ?IP_MIN_HDR_LEN),
+ <<Opts:OptsLen/binary,Data/binary>> = RestDgram,
...
end.
Here, the segment corresponding to the Opts variable has a type modifier,
specifying that Opts is to bind to a binary. All other variables have the
@@ -88,18 +88,18 @@
alignment rules for individual segments of type integer and float. For
binaries and bitstrings without size, the unit specifies the alignment. Since
the default alignment for the binary type is 8, the size of a binary segment
-must be a multiple of 8 bits, that is, only whole bytes.
Example:
<<Bin/binary,Bitstring/bitstring>>
The variable Bin must contain a whole number of bytes, because the binary
+must be a multiple of 8 bits, that is, only whole bytes.
Example:
<<Bin/binary,Bitstring/bitstring>>
The variable Bin must contain a whole number of bytes, because the binary
type defaults to unit:8. A badarg exception is generated if Bin consist
of, for example, 17 bits.
The Bitstring variable can consist of any number of bits, for example, 0, 1,
8, 11, 17, 42, and so on. This is because the default unit for bitstrings
is 1.
For clarity, it is recommended not to change the unit size for binaries.
Instead, use binary when you need byte alignment and bitstring when you need
bit alignment.
The following example successfully constructs a bitstring of 7 bits, provided
-that all of X and Y are integers:
<<X:1,Y:6>>
As mentioned earlier, segments have the following general syntax:
Value:Size/TypeSpecifierList
When constructing binaries, Value and Size can be any Erlang expression.
+that all of X and Y are integers:
<<X:1,Y:6>>
As mentioned earlier, segments have the following general syntax:
Value:Size/TypeSpecifierList
When constructing binaries, Value and Size can be any Erlang expression.
However, for syntactical reasons, both Value and Size must be enclosed in
parenthesis if the expression consists of anything more than a single literal or
-a variable. The following gives a compiler syntax error:
<<X+1:8>>
This expression must be rewritten into the following, to be accepted by the
-compiler:
<<(X+1):8>>
Including Literal Strings
A literal string can be written instead of an element:
<<"hello">>
This is syntactic sugar for the following:
<<$h,$e,$l,$l,$o>>
Matching Binaries
This section describes the rules for matching binaries, using the bit syntax.
There can be zero or more segments in a binary pattern. A binary pattern can
+a variable. The following gives a compiler syntax error:
<<X+1:8>>
This expression must be rewritten into the following, to be accepted by the
+compiler:
<<(X+1):8>>
Including Literal Strings
A literal string can be written instead of an element:
<<"hello">>
This is syntactic sugar for the following:
<<$h,$e,$l,$l,$o>>
Matching Binaries
This section describes the rules for matching binaries, using the bit syntax.
There can be zero or more segments in a binary pattern. A binary pattern can
occur wherever patterns are allowed, including inside other patterns. Binary
patterns cannot be nested. The pattern <<>> matches a zero length binary.
Each segment in a binary can consist of zero or more bits. A segment of type
binary must have a size evenly divisible by 8 (or divisible by the unit size,
@@ -107,23 +107,23 @@
restrictions on the size. A segment of type float must have size 64 or 32.
As mentioned earlier, segments have the following general syntax:
Value:Size/TypeSpecifierList
When matching Value, value must be either a variable or an integer, or a
floating point literal. Expressions are not allowed.
Size must be a
guard expression, which can use
-literals and previously bound variables. The following is not allowed:
foo(N, <<X:N,T/binary>>) ->
- {X,T}.
The two occurrences of N are not related. The compiler will complain that the
-N in the size field is unbound.
The correct way to write this example is as follows:
foo(N, Bin) ->
- <<X:N,T/binary>> = Bin,
- {X,T}.
Note
Before OTP 23, Size was restricted to be an integer or a variable bound to
+literals and previously bound variables. The following is not allowed:
foo(N, <<X:N,T/binary>>) ->
+ {X,T}.
The two occurrences of N are not related. The compiler will complain that the
+N in the size field is unbound.
The correct way to write this example is as follows:
foo(N, Bin) ->
+ <<X:N,T/binary>> = Bin,
+ {X,T}.
Note
Before OTP 23, Size was restricted to be an integer or a variable bound to
an integer.
Binding and Using a Size Variable
There is one exception to the rule that a variable that is used as size must be
previously bound. It is possible to match and bind a variable, and use it as a
-size within the same binary pattern. For example:
bar(<<Sz:8,Payload:Sz/binary-unit:8,Rest/binary>>) ->
- {Payload,Rest}.
Here Sz is bound to the value in the first byte of the binary. Sz is then
-used at the number of bytes to match out as a binary.
Starting in OTP 23, the size can be a guard expression:
bar(<<Sz:8,Payload:((Sz-1)*8)/binary,Rest/binary>>) ->
- {Payload,Rest}.
Here Sz is the combined size of the header and the payload, so we will need to
-subtract one byte to get the size of the payload.
Getting the Rest of the Binary or Bitstring
To match out the rest of a binary, specify a binary field without size:
foo(<<A:8,Rest/binary>>) ->
The size of the tail must be evenly divisible by 8.
To match out the rest of a bitstring, specify a field without size:
foo(<<A:8,Rest/bitstring>>) ->
There are no restrictions on the number of bits in the tail.
Appending to a Binary
Appending to a binary in an efficient way can be done as follows:
triples_to_bin(T) ->
- triples_to_bin(T, <<>>).
+size within the same binary pattern. For example:bar(<<Sz:8,Payload:Sz/binary-unit:8,Rest/binary>>) ->
+ {Payload,Rest}.
Here Sz is bound to the value in the first byte of the binary. Sz is then
+used at the number of bytes to match out as a binary.
Starting in OTP 23, the size can be a guard expression:
bar(<<Sz:8,Payload:((Sz-1)*8)/binary,Rest/binary>>) ->
+ {Payload,Rest}.
Here Sz is the combined size of the header and the payload, so we will need to
+subtract one byte to get the size of the payload.
Getting the Rest of the Binary or Bitstring
To match out the rest of a binary, specify a binary field without size:
foo(<<A:8,Rest/binary>>) ->
The size of the tail must be evenly divisible by 8.
To match out the rest of a bitstring, specify a field without size:
foo(<<A:8,Rest/bitstring>>) ->
There are no restrictions on the number of bits in the tail.
Appending to a Binary
Appending to a binary in an efficient way can be done as follows:
triples_to_bin(T) ->
+ triples_to_bin(T, <<>>).
-triples_to_bin([{X,Y,Z} | T], Acc) ->
- triples_to_bin(T, <<Acc/binary,X:32,Y:32,Z:32>>);
-triples_to_bin([], Acc) ->
+triples_to_bin([{X,Y,Z} | T], Acc) ->
+ triples_to_bin(T, <<Acc/binary,X:32,Y:32,Z:32>>);
+triples_to_bin([], Acc) ->
Acc.