NAME

       erts_alloc_config - Configuration tool for erts_alloc

DESCRIPTION

   Warning:
       This  (experimental)  tool  no  longer  produces  good configurations and cannot be fixed in a reasonably
       backwards compatible manner. It has therefore been scheduled for removal in OTP 26.0.

       erts_alloc(3erl) is an Erlang Run-Time System internal memory  allocator  library.  erts_alloc_config  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  erts_alloc_config  produce  is  intended  as  a
       suggestion, and may need to be adjusted manually.

       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.

       The  current  implementation  of  erts_alloc_config 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 erts_alloc_config 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 erts_alloc_config.

       A configuration is created in the following way:

         * 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  erts_alloc_config  from  doing
           its  job.  Note, you should not 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.

         * 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
           erts_alloc_config)   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 erts_alloc_config when you are saving
           scenarios; otherwise, the configuration may perform bad.

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

         * The configuration produced by erts_alloc_config may need to be manually adjusted as  already  stated.
           Do not modify the file produced by erts_alloc_config; instead, put your modifications in another file
           and load this file after the file produced by erts_alloc_config. 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  erts_alloc_config.  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 erts_alloc_config. Doing it this way simplifies things when you
           want to rerun erts_alloc_config.

   Note:
       The configuration created by erts_alloc_config 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  erts_alloc_config  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
       erts_alloc_config if the Erlang runtime system used is changed.

       erts_alloc_config saves information about runtime scenarios and performs computations in a server that is
       automatically started. The server register itself under the name '__erts_alloc_config__'.

EXPORTS

       save_scenario() -> ok | {error, Error}

              Types:

                 Error = term()

              save_scenario/0  saves information about the current runtime scenario. This information will later
              be used when make_config/0, or make_config/1 is called.

              The first time save_scenario/0 is called a server will be started. This server will  save  runtime
              scenarios. All saved scenarios can be removed by calling stop/0.

       make_config() -> ok | {error, Error}

              Types:

                 Error = term()

              This is the same as calling make_config(group_leader()).

       make_config(FileNameOrIODev) -> ok | {error, Error}

              Types:

                 FileNameOrIODev = string() | io_device()
                 Error = term()

              make_config/1  uses  the  information  previously  saved by save_scenario/0 in order to produce an
              erts_alloc configuration. At least one scenario have had to be  saved.  All  scenarios  previously
              saved will be used when creating the configuration.

              If  FileNameOrIODev  is  a  string(), make_config/1 will use FileNameOrIODev as a filename. A file
              named FileNameOrIODev is  created  and  the  configuration  will  be  written  to  that  file.  If
              FileNameOrIODev is an io_device() (see the documentation of the module io), the configuration will
              be written to the io device.

       stop() -> ok | {error, Error}

              Types:

                 Error = term()

              Stops the server that saves runtime scenarios.

SEE ALSO

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

Ericsson AB                                    runtime_tools 1.19                        erts_alloc_config(3erl)