The following instructions for generating debug backtraces with SML/NJ are adapted from the July 18, 2000 SML/NJ 110.29 release README:
Added a backtrace facility to aid programmers in debugging their
programs. This involves the following changes:
1. Module system/smlnj/init/core.sml (structure _Core) now has hooks
for
keeping track of the current call stack. When programs are
compiled
in a special mode, the compiler will insert calls to these hooks
into the user program.
"Hook" means that it is possible for different implementations of
back-tracing to register themselves (at different times).
2. compiler/MiscUtil/profile/btrace.sml implements the annotation
phase
as an Absyn.dec->Absyn.dec rewrite. Normally this phase is turned
off.
It can be turned on using this call:
SMLofNJ.Internals.BTrace.mode (SOME true);
Turning it off again:
SMLofNJ.Internals.BTrace.mode (SOME false);
Querying the current status:
SMLofNJ.Internals.BTrace.mode NONE;
Annotated programs are about twice as big as normal ones, and they
run a factor of 2 to 4 slower with a dummy back-trace plugin (one
where all hooks do nothing). The slowdown with a plugin that is
actually useful (such as the one supplied by default) is even
greater,
but in the case of the default plugin it is still only an constant
factor (amortized).
3. system/Basis/Implementation/NJ/internals.{sig,sml} have been
augmented
with a sub-structure BTrace for controlling back-tracing. In
particular,
the above-mentioned function "mode" controls whether the annotation
phase is invoked by the compiler. Another important function is
"trigger": when called it aborts the current execution and causes
the top-level loop to print a full back-trace.
4. compiler/MiscUtil/profile/btimp.sml is the current default plugin
for back-tracing. It keeps track of the dynamic call stack and in
addition to that it keeps a partial history at each "level" of that
stack. For example, if a tail-calls b, b tail-calls c, and c
tail-calls
d and b (at separate times, dynamically), then the report will
show:
GOTO d
/c
GOTO \b
CALL a
This shows that there was an initial non-tail call of a, then a
tail-call to b or c, looping behavior in a cluster of functions
that
consist of b and c, and then a goto from that cluster (i.e., either
from
b or from c) to d.
Note that (depending on the user program) the amount of information
that the back-trace module has to keep track of at each level is
bounded
by a constant. Thus, the whole implementation has the same
asymptotical
complexity as the original program (both in space and in time).
5. compiler/TopLevel/interact/evalloop.sml has been modified to
handle the special exception SMLofNJ.Internals.BTrace.BTrace
which is raised by the "trigger" function mentioned above.
Notes on usage:
- Annotated code works well together with unannotated code:
Unannotated calls simply do not show up at all in the backtrace.
- Back-tracing can be confused by callcc and capture.
- While it is possible to compile the compiler with back-trace
annotations turned on (I did it to get some confidence in
correctness), you must make absolutely sure that core.sml and
btimp.sml are compiled WITHOUT annotation! (core.sml cannot actually
be compiled with annotation because there is no core access yet, but
if you compile btimp.sml with annotation, then the system will go into
an infinite recursion and crash.) Since CM currently does not know
about BTrace, the only way to turn annotations on and off for
different modules of the compiler is to interrupt CMB.make, change the
settings, and re-invoke it. Of course, this is awkward and clumsy.
(Actually, you can now also use CM's new "setup" parameter for to this
end.)
Sample sessions:
Standard ML of New Jersey v110.28.1 [FLINT v1.5], June 5, 2000
- SMLofNJ.Internals.BTrace.mode (SOME true);
[autoloading]
[autoloading done]
val it = false : bool
- structure X = struct
- fun main n = let
- fun a (x, 0) = d x
- | a (x, n) = b (x, n - 1)
- and b (x, n) = c (x, n)
- and c (x, n) = a (x, n)
- and d x = e (x, 3)
- and e (x, 0) = f x
- | e (x, n) = e (x, n - 1)
- and f 0 = SMLofNJ.Internals.BTrace.trigger ()
- | f n = n * g (n - 1)
- and g n = a (n, 3)
- in
- f n
- end
- end;
structure X : sig val main : int -> int end
- X.main 3;
*** BACK-TRACE ***
GOTO stdIn:4.2-13.20: X.main[2].f
GOTO-( stdIn:4.2-13.20: X.main[2].e
GOTO stdIn:4.2-13.20: X.main[2].d
/ stdIn:4.2-13.20: X.main[2].a
| stdIn:4.2-13.20: X.main[2].b
GOTO-\ stdIn:4.2-13.20: X.main[2].c
CALL stdIn:4.2-13.20: X.main[2].g
GOTO stdIn:4.2-13.20: X.main[2].f
GOTO-( stdIn:4.2-13.20: X.main[2].e
GOTO stdIn:4.2-13.20: X.main[2].d
/ stdIn:4.2-13.20: X.main[2].a
| stdIn:4.2-13.20: X.main[2].b
GOTO-\ stdIn:4.2-13.20: X.main[2].c
CALL stdIn:4.2-13.20: X.main[2].g
GOTO stdIn:4.2-13.20: X.main[2].f
GOTO-( stdIn:4.2-13.20: X.main[2].e
GOTO stdIn:4.2-13.20: X.main[2].d
/ stdIn:4.2-13.20: X.main[2].a
| stdIn:4.2-13.20: X.main[2].b
GOTO-\ stdIn:4.2-13.20: X.main[2].c
CALL stdIn:4.2-13.20: X.main[2].g
GOTO stdIn:4.2-13.20: X.main[2].f
CALL stdIn:2.15-17.4: X.main[2]
-
Here is another example, using my modified Tiger compiler:
Standard ML of New Jersey v110.28.1 [FLINT v1.5], June 5, 2000
- SMLofNJ.Internals.BTrace.mode (SOME true);
[autoloading]
[autoloading done]
val it = false : bool
- CM.make "sources.cm";
[autoloading]
...
[autoloading done]
[scanning sources.cm]
[parsing (sources.cm):parse.sml]
[creating directory CM/SKEL ...]
[parsing (sources.cm):tiger.lex.sml]
...
[wrote CM/sparc-unix/semant.sml]
[compiling (sources.cm):main.sml]
[wrote CM/sparc-unix/main.sml]
[New bindings added.]
val it = true : bool
- Main.compile ("../testcases/merge.tig", "foo.out");
*** BACK-TRACE ***
CALL lib/semant.sml:99.2-396.21: SemantFun[2].transExp.trvar
CALL lib/semant.sml:99.2-396.21: SemantFun[2].transExp.trexp
CALL lib/semant.sml:289.3-295.22:
SemantFun[2].transExp.trexp.check[2]
GOTO lib/semant.sml:289.3-295.22:
SemantFun[2].transExp.trexp.check[2]
CALL lib/semant.sml:99.2-396.21: SemantFun[2].transExp.trexp
CALL lib/semant.sml:99.2-396.21: SemantFun[2].transExp.trexp
CALL lib/semant.sml:488.3-505.6:
SemantFun[2].transDec.trdec[2].transBody[2]
/ lib/semant.sml:411.65-543.8: SemantFun[2].transDec
CALL-\ lib/semant.sml:413.2-540.9: SemantFun[2].transDec.trdec[2]
CALL lib/semant.sml:99.2-396.21: SemantFun[2].transExp.trexp
CALL lib/semant.sml:8.52-558.4: SemantFun[2].transProg[2]
CALL main.sml:1.18-118.4: Main.compile[2]
-
--
If you are running BTrace-instrumented code and
there is an uncaught exception (regardless of whether or not it
was
raised in instrumented code), the top-level evalloop will print
the back-trace.
Features:
- Instrumented and uninstrumented code work together seemlessly.
(Of course, uninstrumented code is never mentioned in actual
back-traces.)
- Asymptotic time- and space-complexity of instrumented code is
equal to that of uninstrumented code. (This means that
tail-recursion is preserved by the instrumentation phase.)
- Modules whose code has been instrumented in different sessions
work together without problem.
- There is no penalty whatsoever on uninstrumented code.
- There is no penalty on "raise" expressions, even in
instrumented code.
A potential bug (or perhaps it is a feature, too):
A back-trace reaches no further than the outermost instrumented
non-trivial "raise". Here, a "trivial" raise is one that is the
sole RHS of a "handle" rule. Thus, back-traces reach trough
handle e => raise e
and even
handle Foo => raise Bar
and, of course, through
handle Foo => ...
if the exception was not Foo.
Back-traces always reach right through any un-instrumented code
including any of its "handle" expressions, trivial or not.
To try this out, do the following:
- Erase all existing binfiles for your program.
(You may keep binfiles for those modules where you think you
definitely don't need back-tracing.)
- Turn on back-trace instrumentation:
SMLofNJ.Internals.BTrace.mode (SOME true);
- Recompile your program. (I.e., run "CM.make" or "use".)
- You may now turn instrumentation off again (if you want):
SMLofNJ.Internals.BTrace.mode (SOME false);
- Run your program as usual. If it raises an exception that
reaches the interactive toplevel, then a back-trace will
automatically be printed. After that, the toplevel loop
will print the exception history as usual.
--
* BTrace module now also reports call sites. (However, for loop
clusters
it only shows from where the cluster was entered.) There are
associated
modifications to core.sml, internals.{sig,sml}, btrace.sml, and
btimp.sml.
--
* SMLofNJ.Internals.BTrace.trigger: when called, raises an
internal exception which explicitly carries the full back-trace
history,
so it is unaffected by any intervening handle-raise pairs
("trivial"
or not). The interactive loop will print that history once it
arrives
at top level.
Short of having all exceptions implicitly carry the full history,
the
recommended way of using this facility is:
- compile your program with instrumentation "on"
- run it, when it raises an exception, look at the history
- if the history is "cut off" because of some handler, go and
modify
your program so that it explicitly calls BTrace.trigger
- recompile (still instrumented), and rerun; look at the full
history
110.41 added:
Exported structure BTImp from $smlnj/viscomp/debugprof.cm so that
other clients can set up backtracing support.
Back to Cynbe's SML/NJ Internals Page