.. mode: -*- rst -*-

Diagnostic feedback
===================

:Tag: design.mps.diag
:Author: Richard Kistruck
:Date: 2007-06-28
:Status: incomplete design
:Revision: $Id: //info.ravenbrook.com/project/mps/version/1.113/design/diag.txt#1 $
:Copyright: See `Copyright and License`_.
:Index terms: pair: diagnostic feedback; design


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:

#. Automatically via the telemetry system. See design.mps.telemetry,
   and the "Telemetry" chapter in the manual.

#. 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())
        MVT 0000000103FFE160
        {
          minSize: 8 
          meanSize: 42 
          maxSize: 8192 
          fragLimit: 30 
          reuseSize: 16384 
          fillSize: 8192 
          availLimit: 1110835 
          abqOverflow: FALSE 
          splinter: TRUE 
          splinterSeg: 0000000103FEE780 
          splinterBase: 0000000101D7ABB8 
          splinterLimit: 0000000101D7B000 
          # ... 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.


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.



References
----------

.. [RHSK_2007-04-13] Richard Kistruck. 2007-04-13. "`diagnostic feedback from the MPS <https://info.ravenbrook.com/mail/2007/04/13/13-07-45/0.txt>`_".

.. [RHSK_2007-04-18] Richard Kistruck. 2007-04-18. "`Diverse types of diagnostic feedback <http://info.ravenbrook.com/mail/2007/04/18/10-58-49/0.txt>`_".


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.

.. _GDR: http://www.ravenbrook.com/consultants/gdr/


Copyright and License
---------------------

Copyright © 2013-2014 Ravenbrook Limited. All rights reserved.
<http://www.ravenbrook.com/>. This is an open source license. Contact
Ravenbrook for commercial licensing options.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

#. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

#. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

#. Redistributions in any form must be accompanied by information on how
   to obtain complete source code for this software and any
   accompanying software that uses this software.  The source code must
   either be included in the distribution or be available for no more than
   the cost of distribution plus a nominal fee, and must be freely
   redistributable under reasonable conditions.  For an executable file,
   complete source code means the source code for all modules it contains.
   It does not include source code for modules or files that typically
   accompany the major components of the operating system on which the
   executable file runs.

**This software is provided by the copyright holders and contributors
"as is" and any express or implied warranties, including, but not
limited to, the implied warranties of merchantability, fitness for a
particular purpose, or non-infringement, are disclaimed.  In no event
shall the copyright holders and contributors be liable for any direct,
indirect, incidental, special, exemplary, or consequential damages
(including, but not limited to, procurement of substitute goods or
services; loss of use, data, or profits; or business interruption)
however caused and on any theory of liability, whether in contract,
strict liability, or tort (including negligence or otherwise) arising in
any way out of the use of this software, even if advised of the
possibility of such damage.**
