Diagnostic feedback

author Richard Kistruck
date 2007-06-28
index terms pair: diagnostic feedback; design
revision //info.ravenbrook.com/project/mps/version/1.114/design/diag.txt#1
status incomplete design
tag design.mps.diag

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].

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.

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.

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 ...
    }
    

How to write a diagnostic

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.

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.

How the MPS diagnostic system works

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.

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".

Document History

  • 2007-06-28 Richard Kistruck Create. Telemetry-log-events system is a possible channel.
  • 2007-06-29 Richard Kistruck Feedback (not output), each "a diagnostic". Parts of the system; related systems. Link to initial design email.
  • 2007-08-14 Richard Kistruck (Diag Filtering). Expand section: How to see some MPS diagnostic output, with what a diagnostic is, and how to filter it. New section: How to write a diagnostic. Various minor updates and corrections.
  • 2013-05-23 GDR Converted to reStructuredText.
  • 2013-06-05 GDR DIAG part of the system has been removed.