NAME

       erts_alloc_config - Configuration tool for erts_alloc

DESCRIPTION

   Note:
       erts_alloc_config  is  currently  an  experimental  tool  and might be subject to backward
       incompatible changes.

       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)