1erts_alloc_config(3)       Erlang Module Definition       erts_alloc_config(3)
2
3
4

NAME

6       erts_alloc_config - Configuration tool for erts_alloc
7

DESCRIPTION

9   Note:
10       erts_alloc_config  is  currently an experimental tool and might be sub‐
11       ject to backward incompatible changes.
12
13
14       erts_alloc(3) is an Erlang Run-Time System  internal  memory  allocator
15       library. erts_alloc_config is intended to be used to aid creation of an
16       erts_alloc(3) configuration that is suitable for a  limited  number  of
17       runtime  scenarios. The configuration that erts_alloc_config produce is
18       intended as a suggestion, and may need to be adjusted manually.
19
20       The configuration is created based on information  about  a  number  of
21       runtime  scenarios. It is obviously impossible to foresee every runtime
22       scenario that can occur. The important scenarios are those  that  cause
23       maximum  or  minimum  load  on specific memory allocators. Load in this
24       context is total size of memory blocks allocated.
25
26       The current implementation of erts_alloc_config concentrate on configu‐
27       ration  of  multi-block  carriers.  Information gathered when a runtime
28       scenario is saved is mainly current and maximum use of multi-block car‐
29       riers.  If  a  parameter that change the use of multi-block carriers is
30       changed, a previously generated configuration is invalid  and  erts_al‐
31       loc_config needs to be run again. It is mainly the single block carrier
32       threshold that effects the use of multi-block carriers, but other  sin‐
33       gle-block  carrier parameters might as well. If another value of a sin‐
34       gle block carrier parameter than the default is desired,  use  the  de‐
35       sired value when running erts_alloc_config.
36
37       A configuration is created in the following way:
38
39         * Pass the +Mea config command-line flag to the Erlang runtime system
40           you are going to use for creation of the  allocator  configuration.
41           It  will disable features that prevent erts_alloc_config from doing
42           its job. Note, you should not use this flag when using the  created
43           configuration. Also note that it is important that you use the same
44           amount of schedulers when creating the configuration as you are go‐
45           ing the use on the system using the configuration.
46
47         * Run  your  applications with different scenarios (the more the bet‐
48           ter) and save information about each scenario by calling  save_sce‐
49           nario/0.  It  may  be  hard to know when the applications are at an
50           (for erts_alloc_config) important runtime scenario. A good approach
51           may  therefore be to call save_scenario/0 repeatedly, e.g. once ev‐
52           ery tenth second. Note that it is important that your  applications
53           reach  the runtime scenarios that are important for erts_alloc_con‐
54           fig when you are saving scenarios; otherwise, the configuration may
55           perform bad.
56
57         * When you have covered all scenarios, call make_config/1 in order to
58           create a configuration. The configuration is written to a file that
59           you  have  chosen.  This configuration file can later be read by an
60           Erlang runtime-system at startup. Pass the  command  line  argument
61           -args_file FileName to the erl(1) command.
62
63         * The configuration produced by erts_alloc_config may need to be man‐
64           ually adjusted as already stated. Do not modify the  file  produced
65           by  erts_alloc_config;  instead,  put your modifications in another
66           file and load this file after the file produced by  erts_alloc_con‐
67           fig.  That is, put the -args_file FileName argument that reads your
68           modification file later on the  command-line  than  the  -args_file
69           FileName  argument  that  reads  the configuration file produced by
70           erts_alloc_config. If a memory allocation parameter appear multiple
71           times, the last version of will be used, i.e., you can override pa‐
72           rameters in the configuration file produced  by  erts_alloc_config.
73           Doing it this way simplifies things when you want to rerun erts_al‐
74           loc_config.
75
76   Note:
77       The configuration created by erts_alloc_config may  perform  bad,  ever
78       horrible,  for  runtime scenarios that are very different from the ones
79       saved when creating the configuration. You are, therefore,  advised  to
80       rerun  erts_alloc_config if the applications run when the configuration
81       was made are changed, or if the load on the applications  have  changed
82       since  the  configuration  was  made.  You  are  also  advised to rerun
83       erts_alloc_config if the Erlang runtime system used is changed.
84
85
86       erts_alloc_config saves information about runtime  scenarios  and  per‐
87       forms  computations  in  a  server  that  is automatically started. The
88       server register itself under the name '__erts_alloc_config__'.
89

EXPORTS

91       save_scenario() -> ok | {error, Error}
92
93              Types:
94
95                 Error = term()
96
97              save_scenario/0 saves information about the current runtime sce‐
98              nario.  This  information will later be used when make_config/0,
99              or make_config/1 is called.
100
101              The first time  save_scenario/0  is  called  a  server  will  be
102              started. This server will save runtime scenarios. All saved sce‐
103              narios can be removed by calling stop/0.
104
105       make_config() -> ok | {error, Error}
106
107              Types:
108
109                 Error = term()
110
111              This is the same as calling make_config(group_leader()).
112
113       make_config(FileNameOrIODev) -> ok | {error, Error}
114
115              Types:
116
117                 FileNameOrIODev = string() | io_device()
118                 Error = term()
119
120              make_config/1 uses the information previously saved by save_sce‐
121              nario/0  in  order  to  produce  an erts_alloc configuration. At
122              least one scenario have had to be saved.  All  scenarios  previ‐
123              ously saved will be used when creating the configuration.
124
125              If  FileNameOrIODev  is a string(), make_config/1 will use File‐
126              NameOrIODev as a filename. A file named FileNameOrIODev is  cre‐
127              ated  and  the  configuration  will  be written to that file. If
128              FileNameOrIODev is an io_device() (see the documentation of  the
129              module io), the configuration will be written to the io device.
130
131       stop() -> ok | {error, Error}
132
133              Types:
134
135                 Error = term()
136
137              Stops the server that saves runtime scenarios.
138

SEE ALSO

140       erts_alloc(3), erl(1), io(3)
141
142
143
144Ericsson AB                   runtime_tools 1.17          erts_alloc_config(3)
Impressum