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
@@ -55,15 +55,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.
@@ -82,14 +82,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.
@@ -209,30 +209,30 @@
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
+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).
+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
+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
@@ -256,47 +256,47 @@
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"}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}]}]
-}.{"2",
+ [{"1", [{load_module, m}]}],
+ [{"1", [{load_module, m}]}]
+}.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.
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)
@@ -99,29 +99,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.
Note
The name(s) of the user-defined residence module(s) must be listed in the
Modulespart 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
@@ -180,24 +180,24 @@
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}]}]
-}.
+
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 +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
@@ -212,34 +212,34 @@
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]}}
+ ]}],
/usr/share/doc/packages/erlang27-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/erlang27-doc/doc/system/Erlang System Documentation.epub/OEBPS/benchmarking.xhtml" 2026-08-05 08:52:40.000000000 +0000
+++ "new//usr/share/doc/packages/erlang27-doc/doc/system/Erlang System Documentation.epub/OEBPS/benchmarking.xhtml" 2026-08-05 08:52:40.000000000 +0000
@@ -53,8 +53,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.
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),
+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([]) ->
+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(<<>>) -> [].
+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(<<>>) -> [].
@@ -128,7 +128,7 @@
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
+
{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
@@ -162,15 +162,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
@@ -213,9 +213,9 @@
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
+
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 @@ -230,24 +230,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(<<>>) ->
+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?
@@ -263,13 +263,13 @@
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
- after_zero(T);
-after_zero(<<>>) ->
+ after_zero(T);
+after_zero(<<>>) ->
<<>>.
The warning for the first clause says that the creation of a sub binary cannot
be delayed, because it will be returned. The warning for the second clause says
that a sub binary will not be created (yet).
@@ -279,14 +279,14 @@
Unused Variables
The compiler figures out if a variable is unused. The same code is generated for
-each of the following functions:
count1(<<_,T/binary>>, Count) -> count1(T, Count+1);
-count1(<<>>, Count) -> Count.
+each of the following functions:count1(<<_,T/binary>>, Count) -> count1(T, Count+1);
+count1(<<>>, Count) -> Count.
-count2(<<H,T/binary>>, Count) -> count2(T, Count+1);
-count2(<<>>, Count) -> Count.
+count2(<<H,T/binary>>, Count) -> count2(T, Count+1);
+count2(<<>>, Count) -> Count.
-count3(<<_H,T/binary>>, Count) -> count3(T, Count+1);
-count3(<<>>, Count) -> Count.
In each iteration, the first 8 bits in the binary will be skipped, not matched
+
count3(<<_H,T/binary>>, Count) -> count3(T, Count+1);
+count3(<<>>, Count) -> Count.
In each iteration, the first 8 bits in the binary will be skipped, not matched
out.