.TH erts_alloc_config 3erl "runtime_tools 1.15.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
erts_alloc_config \- Configuration tool for erts_alloc
.SH DESCRIPTION
.LP

.RS -4
.B
Note:
.RE
\fIerts_alloc_config\fR\& is currently an experimental tool and might be subject to backward incompatible changes\&.

.LP
erts_alloc(3erl) is an Erlang Run-Time System internal memory allocator library\&. \fIerts_alloc_config\fR\& is intended to be used to aid creation of an erts_alloc(3erl) configuration that is suitable for a limited number of runtime scenarios\&. The configuration that \fIerts_alloc_config\fR\& produce is intended as a suggestion, and may need to be adjusted manually\&.
.LP
The configuration is created based on information about a number of runtime scenarios\&. It is obviously impossible to foresee every runtime scenario that can occur\&. The important scenarios are those that cause maximum or minimum load on specific memory allocators\&. Load in this context is total size of memory blocks allocated\&.
.LP
The current implementation of \fIerts_alloc_config\fR\& concentrate on configuration of multi-block carriers\&. Information gathered when a runtime scenario is saved is mainly current and maximum use of multi-block carriers\&. If a parameter that change the use of multi-block carriers is changed, a previously generated configuration is invalid and \fIerts_alloc_config\fR\& needs to be run again\&. It is mainly the single block carrier threshold that effects the use of multi-block carriers, but other single-block carrier parameters might as well\&. If another value of a single block carrier parameter than the default is desired, use the desired value when running \fIerts_alloc_config\fR\&\&.
.LP
A configuration is created in the following way:
.RS 2
.TP 2
*
Pass the +Mea config command-line flag to the Erlang runtime system you are going to use for creation of the allocator configuration\&. It will disable features that prevent \fIerts_alloc_config\fR\& from doing its job\&. Note, you should \fInot\fR\& use this flag when using the created configuration\&. Also note that it is important that you use the same amount of schedulers when creating the configuration as you are going the use on the system using the configuration\&.
.LP
.TP 2
*
Run your applications with different scenarios (the more the better) and save information about each scenario by calling save_scenario/0\&. It may be hard to know when the applications are at an (for \fIerts_alloc_config\fR\&) important runtime scenario\&. A good approach may therefore be to call save_scenario/0 repeatedly, e\&.g\&. once every tenth second\&. Note that it is important that your applications reach the runtime scenarios that are important for \fIerts_alloc_config\fR\& when you are saving scenarios; otherwise, the configuration may perform bad\&.
.LP
.TP 2
*
When you have covered all scenarios, call make_config/1 in order to create a configuration\&. The configuration is written to a file that you have chosen\&. This configuration file can later be read by an Erlang runtime-system at startup\&. Pass the command line argument -args_file FileName to the erl(1) command\&.
.LP
.TP 2
*
The configuration produced by \fIerts_alloc_config\fR\& may need to be manually adjusted as already stated\&. Do not modify the file produced by \fIerts_alloc_config\fR\&; instead, put your modifications in another file and load this file after the file produced by \fIerts_alloc_config\fR\&\&. That is, put the -args_file FileName argument that reads your modification file later on the command-line than the -args_file FileName argument that reads the configuration file produced by \fIerts_alloc_config\fR\&\&. If a memory allocation parameter appear multiple times, the last version of will be used, i\&.e\&., you can override parameters in the configuration file produced by \fIerts_alloc_config\fR\&\&. Doing it this way simplifies things when you want to rerun \fIerts_alloc_config\fR\&\&.
.LP
.RE

.LP

.RS -4
.B
Note:
.RE
The configuration created by \fIerts_alloc_config\fR\& may perform bad, ever horrible, for runtime scenarios that are very different from the ones saved when creating the configuration\&. You are, therefore, advised to rerun \fIerts_alloc_config\fR\& if the applications run when the configuration was made are changed, or if the load on the applications have changed since the configuration was made\&. You are also advised to rerun \fIerts_alloc_config\fR\& if the Erlang runtime system used is changed\&.

.LP
\fIerts_alloc_config\fR\& saves information about runtime scenarios and performs computations in a server that is automatically started\&. The server register itself under the name \fI\&'__erts_alloc_config__\&'\fR\&\&.
.SH EXPORTS
.LP
.B
save_scenario() -> ok | {error, Error}
.br
.RS
.LP
Types:

.RS 3
Error = term()
.br
.RE
.RE
.RS
.LP
\fIsave_scenario/0\fR\& saves information about the current runtime scenario\&. This information will later be used when make_config/0, or make_config/1 is called\&.
.LP
The first time \fIsave_scenario/0\fR\& is called a server will be started\&. This server will save runtime scenarios\&. All saved scenarios can be removed by calling stop/0\&.
.RE

.LP
.B
make_config() -> ok | {error, Error}
.br
.RS
.LP
Types:

.RS 3
Error = term()
.br
.RE
.RE
.RS
.LP
This is the same as calling make_config(group_leader())\&.
.RE

.LP
.B
make_config(FileNameOrIODev) -> ok | {error, Error}
.br
.RS
.LP
Types:

.RS 3
FileNameOrIODev = string() | io_device()
.br
Error = term()
.br
.RE
.RE
.RS
.LP
\fImake_config/1\fR\& uses the information previously saved by save_scenario/0 in order to produce an \fIerts_alloc\fR\& configuration\&. At least one scenario have had to be saved\&. All scenarios previously saved will be used when creating the configuration\&.
.LP
If \fIFileNameOrIODev\fR\& is a \fIstring()\fR\&, \fImake_config/1\fR\& will use \fIFileNameOrIODev\fR\& as a filename\&. A file named \fIFileNameOrIODev\fR\& is created and the configuration will be written to that file\&. If \fIFileNameOrIODev\fR\& is an io_device() (see the documentation of the module io), the configuration will be written to the io device\&.
.RE

.LP
.B
stop() -> ok | {error, Error}
.br
.RS
.LP
Types:

.RS 3
Error = term()
.br
.RE
.RE
.RS
.LP
Stops the server that saves runtime scenarios\&.
.RE

.SH "SEE ALSO"

.LP
erts_alloc(3erl), erl(1), io(3erl)