docs/doxygen/lib/logging.md

   1 Logging {#page_logging}
   2 =======
   3
   4 Currently, mdrun is using a combination of direct C-style I/O into `fplog` and
   5 `stderr`, and the facilities described here.  However, more and more should get
   6 moved to this interface in the future.
   7
   8 The parts that make up the logging system are shown below.
   9
  10 \dot
  11     digraph logging_overview {
  12         builder [label="LoggerBuilder", URL="\ref gmx::LoggerBuilder"]
  13         owner [label="LoggerOwner", URL="\ref gmx::LoggerOwner"]
  14         logger [label="MDLogger", URL="\ref gmx::MDLogger"]
  15         target [label="ILogTarget", URL="\ref gmx::ILogTarget"]
  16         user [label="using code"]
  17
  18         builder -> owner [label="builds"]
  19         owner -> logger
  20         owner -> target [label="owns"]
  21         logger -> target [label="references"]
  22         user -> builder [label="set logging targets"]
  23         user -> logger [label="write with\nGMX_LOG()"]
  24     }
  25 \enddot
  26
  27 To initialize the logging system, the using code creates an instance of
  28 gmx::LoggerBuilder, and sets the desired logging targets with provided methods.
  29 Once all targets have been initialized, the code calls
  30 gmx::LoggerBuilder::build() and gets a gmx::LoggerOwner, which is responsible
  31 of managing the memory allocated for the logger.
  32
  33 To log information, the using code uses an gmx::MDLogger returned by
  34 gmx::LoggerOwner::logger() with the ::GMX_LOG macro.  Code that writes to the
  35 log only needs to know of this class (and helper classes used to implement the
  36 macro), which is a relatively simple container for references to the logging
  37 targets.  If there is no log target that would consume the information written
  38 with ::GMX_LOG, the whole statement evaluates to a conditional that reads the
  39 log target from a member variable and compares it against `nullptr`.  All the
  40 code that formats the output is skipped in this case.
  41
  42 Currently the implementation is geared to making ::GMX_LOG behavior stable, and
  43 to be relatively extensible.  However, using any other approach than ::GMX_LOG
  44 for writing to the log should first think about how the API could be best
  45 organized for that.
  46
  47 All information written to the log is composed of _log entries_.  Each
  48 ::GMX_LOG statement writes a single log entry, meaning that newlines are
  49 automatically added.
  50
  51 The logging methods are not thread-safe, so it is the responsibility of the
  52 calling code to only use them from a single thread or otherwise synchronize
  53 access.