Documentation for module cp_log_handling

various routines to log and control the output. The idea is that decisions about where to log should not be done in the code that generates the log, but should be globally changeable a central place. So some care has been taken to have enough information about the place from where the log comes so that in the future intelligent and flexible decisions can be taken by the logger, without having to change other code.

source: cp_log_handling.F
Loading...

public Types:

cp_logger_p_type
...
cp_logger_type
type of a logger, at the moment it contains just a print level starting at which level it should be logged (0 note, 1 warning, 2 failure, 3 fatal) it could be expanded with the ability to focus on one or more module/object/thread/processor

Generic procedures:

cp_to_string

public Subroutines/Functions:

adds a default logger. MUST be called before logging occours
FUNCTION
INTEGER
cp_default_logger_stack_size
...
returns the default logger
initializes a logger
generates a unique filename (ie adding eventual suffixes and process ids)
returns the unit nr for the ionode (-1 on all other processors) skips as well checks if the procs calling this function is not the ionode
asks the default unit number of the given logger. try to use cp_logger_get_unit_nr
FUNCTION
INTEGER
cp_logger_get_unit_nr (logger, local)
returns the unit nr for the requested kind of log.
releases this logger
retains the given logger (to be called to keep a shared copy of the logger)
sets various attributes of the given logger
changes the logging level. Log messages with a level less than the one given wo not be printed.
FUNCTION
LOGICAL
cp_logger_would_log (logger, level)
this function can be called to check if the logger would log a message with the given level from the given source you should use this function if you do direct logging (without using cp_logger_log), or if you want to know if the generation of some costly log info is necessary
the cousin of cp_add_default_logger, decrements the stack, so that the default logger is what it has been

Parameters:

INTEGER
:: cp_failure_level = 2
INTEGER
:: cp_fatal_level = 3
INTEGER
:: cp_note_level = 0
INTEGER
:: cp_warning_level = 1

public Types:

TYPE :: cp_logger_p_type

...


POINTER :: p => NULL() ...

TYPE :: cp_logger_type

type of a logger, at the moment it contains just a print level starting at which level it should be logged (0 note, 1 warning, 2 failure, 3 fatal) it could be expanded with the ability to focus on one or more module/object/thread/processor


INTEGER
:: id_nr unique number to identify the logger
INTEGER
:: ref_count reference count (see cp2k/doc/ReferenceCounting.html)
INTEGER
:: print_level the level starting at which something gets printed
INTEGER
:: default_local_unit_nr default unit for local logging (-1 if not yet initialized). Local logging guarantee to each task its own file.
INTEGER
:: default_global_unit_nr default unit for global logging (-1 if not yet initialized). This unit is valid only on the processor with %para_env%mepos==%para_env%source.
LOGICAL
:: close_local_unit_on_dealloc if the local unit should be closed when this logger is deallocated
LOGICAL
:: close_global_unit_on_dealloc whether the global unit should be closed when this logger is deallocated
:: suffix a short string that is used as suffix in all the filenames created by this logger. Can be used to guarantee the unicity of generated filename
:: local_filename the root of the name of the file used for local logging (can be different from the name of the file corresponding to default_local_unit_nr, only the one used if the unit needs to be opened)
:: global_filename the root of the name of the file used for global logging (can be different from the name of the file corresponding to default_global_unit_nr, only the one used if the unit needs to be opened)
POINTER :: para_env the parallel environement for the output. this might be a super environment of your computation environment i.e. be very careful not to do global operations like broadcast with a subset of its processors (use your computation environment instead).
POINTER :: iter_info ...


Generic procedure cp_to_string

...

INTEGER,
INTENT(in)
:: i ×
REAL(dp),
INTENT(in)
:: val ×
LOGICAL,
INTENT(in)
:: val ×

SUBROUTINEcp_add_default_logger(logger)

adds a default logger. MUST be called before logging occours

Arguments:
POINTER
:: logger ...

FUNCTIONcp_default_logger_stack_size()

...

Return Value ::
INTEGER

FUNCTIONcp_get_default_logger()

returns the default logger

Return Value ::

SUBROUTINEcp_logger_create(logger, para_env, print_level, default_global_unit_nr, default_local_unit_nr, global_filename, local_filename, close_global_unit_on_dealloc, iter_info, close_local_unit_on_dealloc, suffix, template_logger)

initializes a logger

Arguments:
POINTER
:: logger the logger to initialize
OPTIONAL, POINTER
:: para_env the parallel environment (this is most likely the global parallel environment
INTEGER,
INTENT(in),
OPTIONAL
:: print_level the level starting with which something is written (defaults to cp_note_level)
INTEGER,
INTENT(in),
OPTIONAL
:: default_global_unit_nr the default unit_nr for output (if not given, and no file is given defaults to the standard output)
INTEGER,
INTENT(in),
OPTIONAL
:: default_local_unit_nr the default unit number for local (i.e. task) output. If not given defaults to a out.taskid file created upon
CHARACTER(*),
INTENT(in),
OPTIONAL
:: global_filename a new file to open (can be given instread of the global_unit_nr)
CHARACTER(*),
INTENT(in),
OPTIONAL
:: local_filename a new file to open (with suffix and para_env%mepos appended). Can be given instread of the default_local_unit_nr). the file is created only upon the first local logging request
LOGICAL,
INTENT(in),
OPTIONAL
:: close_global_unit_on_dealloc if the unit should be closed when the logger is deallocated (defaults to true if a local_filename is given, to false otherwise)
OPTIONAL, POINTER
:: iter_info ...
LOGICAL,
INTENT(in),
OPTIONAL
:: close_local_unit_on_dealloc if the unit should be closed when the logger is deallocated (defaults to true)
CHARACTER(*),
INTENT(in),
OPTIONAL
:: suffix the suffix that should be added to all the generated filenames
OPTIONAL, POINTER
:: template_logger a logger from where to take the unspecified things

SUBROUTINEcp_logger_generate_filename(logger, res, root, postfix, local)

generates a unique filename (ie adding eventual suffixes and process ids)

Arguments:
POINTER
:: logger ...
CHARACTER(*),
INTENT(inout)
:: res the resulting string
CHARACTER(*),
INTENT(in)
:: root the start of filename
CHARACTER(*),
INTENT(in)
:: postfix the end of the name
LOGICAL,
INTENT(in),
OPTIONAL
:: local if the name should be local to this task (defaults to false)

FUNCTIONcp_logger_get_default_io_unit(logger)

returns the unit nr for the ionode (-1 on all other processors) skips as well checks if the procs calling this function is not the ionode

Return Value ::
INTEGER
Arguments:
OPTIONAL, POINTER
:: logger the logger you want to log in

RECURSIVE FUNCTIONcp_logger_get_default_unit_nr(logger, local, skip_not_ionode)

asks the default unit number of the given logger. try to use cp_logger_get_unit_nr

Return Value ::
INTEGER
Arguments:
OPTIONAL, POINTER
:: logger the logger you want info from
LOGICAL,
INTENT(in),
OPTIONAL
:: local if you want the local unit nr (defaults to false)
LOGICAL,
INTENT(in),
OPTIONAL
:: skip_not_ionode ...

FUNCTIONcp_logger_get_unit_nr(logger, local)

returns the unit nr for the requested kind of log.

Return Value ::
INTEGER
Arguments:
POINTER
:: logger the logger you want to log in
LOGICAL,
INTENT(in),
OPTIONAL
:: local if true returns a local logger (one per task), otherwise returns a global logger (only the process with para_env%mepos== para_env%source should write to the global logger). Defaults to false

SUBROUTINEcp_logger_release(logger)

releases this logger

Arguments:
POINTER
:: logger the logger to release

SUBROUTINEcp_logger_retain(logger)

retains the given logger (to be called to keep a shared copy of the logger)

Arguments:
POINTER
:: logger the logger to retain

SUBROUTINEcp_logger_set(logger, local_filename, global_filename)

sets various attributes of the given logger

Arguments:
POINTER
:: logger the logger you want to change
CHARACTER(*),
INTENT(in),
OPTIONAL
:: local_filename the root of the name of the file used for local logging
CHARACTER(*),
INTENT(in),
OPTIONAL
:: global_filename the root of the name of the file used for global logging

SUBROUTINEcp_logger_set_log_level(logger, level)

changes the logging level. Log messages with a level less than the one given wo not be printed.

Arguments:
POINTER
:: logger the logger to change
INTEGER,
INTENT(in)
:: level the new logging level for the logger

FUNCTIONcp_logger_would_log(logger, level)

this function can be called to check if the logger would log a message with the given level from the given source you should use this function if you do direct logging (without using cp_logger_log), or if you want to know if the generation of some costly log info is necessary

Return Value ::
LOGICAL
Arguments:
POINTER
:: logger the logger you want to log in
INTEGER,
INTENT(in)
:: level describes the of the message: cp_fatal_level(3), cp_failure_level(2), cp_warning_level(1), cp_note_level(0).

SUBROUTINEcp_rm_default_logger()

the cousin of cp_add_default_logger, decrements the stack, so that the default logger is what it has been

FUNCTIONcp_int_to_string(i)

converts an int to a string (should be a variable length string, but that does not work with all the compilers)

Return Value ::
CHARACTER(6)
Arguments:
INTEGER,
INTENT(in)
:: i the integer to convert

FUNCTIONcp_real_dp_to_string(val)

convert a double precision real in a string (should be a variable length string, but that does not work with all the compilers)

Return Value ::
CHARACTER(11)
Arguments:
REAL(dp),
INTENT(in)
:: val the number to convert

FUNCTIONcp_logical_to_string(val)

convert a logical in a string ('T' or 'F')

Return Value ::
CHARACTER(1)
Arguments:
LOGICAL,
INTENT(in)
:: val the number to convert