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)