
 [index entries: _debug_ _debugger_ _debugging_
                 _profile_ _profiler_ _profiling_
                 _coverage_ ]

_Errortrace_ is a stack-trace-on-exceptions/profiler/coverage tool for
MzScheme.  Errortrace is not a complete debugger, and a real debugger
in DrScheme is expected eventually; meanwhile, using errortrace might
be better than MzScheme's limited stack-trace reporting.

Quick instructions
------------------

  0) Throw away .zo versions of your source

  1) Prefix your program with
       (require (lib "errortrace.ss" "errortrace"))
     or start MzScheme with the -M flag:
       mzscheme -M errortrace

  2) When an exception occurs, the exception handler prints something
     like a stack trace, most recent contexts first

The errortrace module is strange; don't import it into another module.
Instead, the errortrace module is meant to be invoked from the
top-level, so that it can install an evaluation handler, exception
handler, etc.

To reuse parts of the code of errortrace, import _errortrace-lib.ss_.
It contains all of the names here but does not set the compilation
handler or the error display handler.

Exception Information
---------------------

Invoking the _errortrace.ss_ module sets the compilation handler to
instrument Scheme source code.  It also sets the error display handler
to report source information for an exception, and it sets the
`use-compiled-file-paths' parameter to trigger the use of
errortrace-specific .zo files.

  NOTE: errortrace has no effect on code loaded as compiled byte code
  (i.e., from a .zo file) or native code (i.e., from a .dll or .so
  file).  But use the "--mode errortrace" flag to Setup PLT to create
  .zo files with errortrace information.

Explicitly requiring "errortrace.ss" within a module is generally a
bad idea, since "errortrace.ss" sets various parameters.

Errortrace's instrumentation can be explicitly disabled via the
`instrumenting-enabled' boolean parameter.  Instrumentation is on by
default.  The `instrumenting-enabled' parameter affects only the way
that source code is compiled, not the way that exception information
is reported.

> (instrumenting-enabled) - returns #t if error tracing instrumentation is
  enabled, #f otherwise
> (instrumenting-enabled on?) - enables/disables error tracing
  instrumentation

The instrumentation for storing exception information slows most
programs by a factor of 2 or 3.

The `print-error-trace' procedure takes a port and exception and
prints the errortrace-collected debugging information contained in the
exception.  It is used by the exception handler installed by
errortrace.

> (print-error-trace output-port exn) - prints the errortrace
  information in `exn' to `output-port'.

The `error-context-display-depth' parameter controls how much context
errortrace's exception handler displays.  The default value is 10000.

> (error-context-display-depth) - returns the current context display
  depth
> (error-context-display-depth d) - sets the context display depth to
  `d'

Profiling
---------

Errortrace's profiling instrumentation is off by default.  Enable
profiling instrumentation with the `profiling-enabled' boolean
parameter (but setting `instrumentation-enabled' to #f also disables
profiling):

> (profiling-enabled) - returns #t if profiling instrumentation is
  enabled, #f otherwise
> (profiling-enabled on?) - enables/disables profiling instrumentation

> (profiling-record-enabled) - returns #t if profiling info is
  recorded for instrumented code, #f otherwise; the default is #t
> (profiling-record-enabled on?) - enables/disables the recording of
  profiling info (independent of whether newly evaluated code is
  instrumented)

Profiling records:

 * the number of times a procedure was called.

 * the number of milliseconds consumed by the procedure's body across
   all calls (including the time consumed by any nested non-tail call
   within the procedure, but not including time consumed by a
   tail-call from the procedure).

 * an inferred name for the procedure.

 * the procedure's source in the form of a syntax object (which might,
   in turn, provide a source location file and position).

 * optionally, information about the procedure call path (i.e., a
   stack trace) for every call to the procedure; collecting this
   information is relatively expensive. Path information is collected
   when the `profile-paths-enabled' boolean parameter is #t; the
   default is #f, but setting the parameter to #t immediately affects
   all procedure instrumented for profiling information:

>   (profile-paths-enabled) - returns #t if profiling collects path
    information, #f otherwise
>   (profile-paths-enabled on?) - enables/disables collecting path
    information for profiling

Profiling information is accumulated in a hash table.  If a procedure
is redefined, new profiling information is accumulated for the new
version of the procedure, but the old information is also preserved.

To retrieve all profiling information accumulated so far, call
`get-profile-results':

> (get-profile-results) - returns a list of lists that contain:

  * the number of times the procedure was called;

  * the number of milliseconds of process time consumed by the
    procedure;

  * the inferred name or #f of the procedure;

  * the syntax source of the procedure; and

  * a list of unique call paths recorded while `profile-paths-enabled'
    is set to #t.  Each call path is a pair of a count (the number of
    times the path occurred) and a list containing two-element lists;
    each two-element list contains the calling procedure's name or
    source expression and the calling procedure's source file or #f.

Depending of the source program, profiling usually induces a factor of
2 to 4 slowdown (in addition to any slowdown from the exception
information instrumentation).

> (output-profile-results paths? sort-time?)

Gets the current profile results and displays them.  It optionally
shows paths information (if it is recorded) and sorts by either time
or call counts.

> (clear-profile-results)

Clears accumulated profile results.

Coverage
--------

Errortrace can track expression execution that is useful for checking
test coverage (i.e., simple expression coverage).  Enable coverage
checking with the `execute-counts-enabled' boolean parameter (but
setting `instrumentation-enabled' to #f also disables execute
counting):

> (execute-counts-enabled) - returns #t if execute-counting
  instrumentation is enabled, #f otherwise
> (execute-counts-enabled on?) - enables/disables execute-counting
  instrumentation

> (get-execute-counts) - returns a list of pairs, one for each
  instrumented expression.  The first element of the pair is a syntax
  object (usually containing source location information) for the
  original expression, and the second element of the pair is the
  number of times that the expression has been evaluated.  These
  elements are destructively modified, so to take a snapshot you will
  need to copy them.

> (annotate-executed-file filename-path) - writes the named file to
  the current output port, inserting an additional line between each
  source line to reflect execution counts (as reported by
  `get-execute-counts').  An expression underlined with "^" has been
  executed 0 times; an expression underlined with "." has been
  executed 1 time; and an expression underlined with "," has been
  executed multiple times.

_Re-using errortrace handlers_
-----------------------------------

The _errortrace-lib.ss_ module exports all of the exports of
"errortrace.ss", plus a few more.  It does not install any handlers.

The addition exports are as follows:

> (errortrace-compile-handler stx immediate-eval?) - compiles `stx'
  using the compilation handler that was active when the
  "errortrace-lib.ss" module was executed, but first instruments the
  code for errortrace information.  The code is instrumented only if
  the namespace is the same as when the module was executed.  This
  procedure is suitable for use as a compilation handler.

> (errortrace-error-display-handler string exn) - displays information
  about the exception; this procedure is suitable for use as an error
  display handler.

> (errortrace-annotate stx) - macro-expands and instruments the given
  top-level form.  If the form is a module named `errortrace-key', no
  instrumentation is applied.  This annotation function is used by
  `errortrace-compile-handler'.

> (annotate-top stx) - like `errortrace-annotate', but without the
  special case for `errortrace-key'.  Also, if `stx' is a module
  declaration, it is not enriched with imports to explicitly load
  errortrace run-time support.


_Re-using errortrace stack tracing_
-----------------------------------

The errortrace collection also includes a _stacktrace.ss_ library.  It
exports the _stacktrace@_ unit and it import signature
_stacktrace-imports^_, and its export signature _stacktrace^_.

The export signature contains these names:

> annotate : syntax boolean -> syntax
> annotate-top : syntax boolean -> syntax
> make-st-mark : syntax -> syntax
> st-mark-source : st-mark -> any
> st-mark-bindings : st-mark -> (listof (list syntax any))

The first two functions annotate expressions with errortrace
information.  The `annotate-top' function should be called with a
top-level expression, and `annotate' should be called with a nested
expression (e.g., by `profile-point').  The boolean argument indicates
whether the expression is a transformer expression (#t) or a normal
expression (#f).

The `st-mark-source' and `st-mark-bindings' functions extract
information from a particular kind of value.  The value must be
created by `make-st-mark'.  `st-mark-source' extracts the value
originally provided to the expression-maker, and `st-mark-bindings'
returns local binding information (if available).

The import signature contains these names:

> with-mark : syntax syntax -> syntax

  This procedure is called by `annotate' and `annotate-top' to wrap
  expressions with `with-continuation-mark'.  The first argument is
  the source expression and the second argument is the expression to
  be wrapped.

> test-coverage-enabled : (parameter boolean)

  This parameter determines if the test coverage annotation is
  inserted into the code.  This parameter controls how compilation
  happens -- it does not affect the dynamic behavior of the already
  compiled code.  If the parameter is set, calls to test-covered are
  inserted into the code (and initialize-test-coverage-point is called
  during compilation).  If not, no calls to test-covered are inserted.

> test-covered : symbol -> void

  During execution of the program, this is called for each point with
  the key for that program point that was passed to
  initialize-test-coverage-point.

> initialize-test-coverage-point : symbol syntax -> void

  During compilation of the program, this function is called with each
  sub-expression of the program.  The first argument is a special key
  used to identify this program point.  The second argument is the
  syntax of this program point.

> profile-key : symbol

  only used for profiling paths.

> profiling-enabled  : -> boolean

  determines if profiling information is currently collected (affects
  the behavior of compiling the code -- does not affect running code).
  If this always returns #f, the other profiling functions are never
  called.

> initialize-profile-point : symbol (union #f syntax[symbol]) syntax -> void

  called as the program is compiled for each profiling point that
  might be encountered during the program's execution.  The first
  argument is a key identifying this code.  The second argument is the
  inferred name at this point and the final argument is the syntax of
  this expression.

> register-profile-start : symbol -> (union #f number)

  Called when some profiled code is about to be executed.  If the
  result is a number, it is expected to be the current number of
  milliseconds.  The symbol is a key that is unique to this fragment
  of code -- it is the same symbol passed to initialize-profile-point
  for this code fragment.

> register-profile-done : symbol (union #f number) -> void

  This function is called when some profiled code is finished
  executing.

  Note that register-profile-start and register-profile-done can be
  called in a nested manner; in this case, the result of
  register-profile-point should be #f.
