9. Diagnostic feedback

9.1. Introduction

.intro: This document describes how to use the diagnostic feedback mechanism in the Memory Pool System.

.sources: Initially abased on [RHSK_2007-04-13] and [RHSK_2007-04-18].

9.2. Overview

Diagnostic feedback is information created by the MPS diagnostic system for the purpose of helping MPS programmers and client programmers.

Such a piece of information is called “a diagnostic”. (See also .parts.)

A diagnostic is not intended to be visible to end users, or readable by them.

A diagnostic is not intended to be stable from one release to the next: it may be modified or removed at any time.

9.3. Requirements

MPS diagnostic feedback code must do these things:

• calculate, store, and propagate data;

• collate, synthesise, and format it into a human-useful diagnostic;

• control (for example, filter) output of diagnostics;

• use a channel to get the diagnostic out.

9.4. Usage

To get diagnostic output from the MPS, you must use a variety with diagnostics compiled-in. Currently, that means variety.cool. See config.h.

There are two mechanism for getting diagnostic output:

1. Automatically via the telemetry system. See design.mps.telemetry, and the “Telemetry” chapter in the manual.

2. Manually via the debugger. In the debugger, set break points at the places where you want to inspect data structures (or wait for the debugger to be entered via an abort() call or unhandled segmentation fault). Then at the debugger command prompt, run Describe() commands of your choice. For example:

   (gdb) run
   Starting program: mv2test
   Reading symbols for shared libraries +............................. done
   cbs.c:94: MPS ASSERTION FAILED: !cbs->inCBS
   
   Program received signal SIGABRT, Aborted.
   0x00007fff83e42d46 in __kill ()
   (gdb) frame 12
   #12 0x000000010000b1fc in MVTFree (pool=0x103ffe160, base=0x101dfd000, size=5024) at poolmv2.c:711
   711         Res res = CBSInsert(MVTCBS(mvt), base, limit);
   (gdb) p MVTDescribe(mvt, mps_lib_get_stdout(), 0)
   MVT 0000000103FFE160 {
     minSize: 8
     meanSize: 42
     maxSize: 8192
     fragLimit: 30
     reuseSize: 16384
     fillSize: 8192
     availLimit: 90931
     abqOverflow: FALSE
     splinter: TRUE
     splinterBase: 0000000106192FF0
     splinterLimit: 0000000106193000
     size: 303104
     allocated: 262928
     available: 40176
     unavailable: 0
     # ... etc ...
   }
   

9.5. How to write a diagnostic

9.5.1. Compile away in non-diag varieties; no side effects

Wrap code with the STATISTIC and METER macros, to make sure that non-diagnostic varieties do not execute diagnostic-generating code.

Diagnostic-generating code must have no side effects.

9.5.2. Writing good paragraph text

Make your diagnostics easy to understand! Other people will read your diagnostics! Make them clear and helpful. Do not make them terse and cryptic. If you use symbols, print a key in the diagnostic.

9.6. How the MPS diagnostic system works

9.6.1. Parts of the MPS diagnostic system

.parts: The following facilities are considered part of the MPS diagnostic system:

• the Describe() methods.

• the STATISTIC macros (see mpm.h);

• the METER macros and meter subsystem.

9.6.2. Statistics

.stat: The statistic system collects information about the behaviour and performance of the MPS that may be useful for MPS developers and customers, but which is not needed by the MPS itself for internal decision-making.

.stat.remove: The space needed for these statistics, and the code for maintaining them, can therefore be removed (compiled out) in some varieties.

.stat.config: Statistics are compiled in if CONFIG_STATS is defined (in the cool variety) and compiled out if CONFIG_STATS_NONE is defined (in the hot and rash varieties).

STATISTIC_DECL(decl)

.stat.decl: The STATISTIC_DECL macro is used to wrap the declaration of storage for a statistic. Note that the expansion supplies a terminating semi-colon and so it must not be followed by a semi-colon in use. This is so that it can be used in structure declarations.

STATISTIC(gather)

.stat.gather: The STATISTIC macro is used to gather statistics. The argument is a statement and the expansion followed by a semicolon is syntactically a statement. The macro expends to NOOP in non-statistical varieties. (Note that it can’t use DISCARD_STAT to check the syntax of the statement because it is expected to use fields that have been compiled away by STATISTIC_DECL, and these will cause compilation errors.)

.stat.gather.effect: The argument to the STATISTIC macro is not executed in non-statistical varieties and must have no side effects, except for updates to fields that are declared in STATISTIC_DECL, and telemetry output containing the values of such fields.

STATISTIC_WRITE(format, arg)

.stat.write: The STATISTIC_WRITE macro is used in WriteF() argument lists to output the values of statistics.

9.6.3. Related systems

The MPS diagnostic system is separate from the following other MPS systems:

• The telemetry-log-events system. This emits much more data, in a less human-readable form, requires MPS-aware external tools, and is more stable from release to release). In non-diagnostic telemetry varieties, the telemetry-log-events system emits events that log all normal MPS actions. In diagnostic telemetry varieties, it may emit additional events containing diagnostic information. Additionally, the telemetry-log-events stream might in future be available as a channel for emitting human-readable text diagnostics. See also design.mps.telemetry.

• The MPS message system. This is present in all varieties, and manages asynchronous communication from the MPS to the client program). However, the MPS message system might in future also be available as a channel for emitting diagnostics. See also design.mps.message.

9.7. References

RHSK_2007-04-13

Richard Kistruck. 2007-04-13. “diagnostic feedback from the MPS”.

RHSK_2007-04-18

Richard Kistruck. 2007-04-18. “Diverse types of diagnostic feedback”.