184 lines
8.4 KiB
HTML
184 lines
8.4 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<!-- This manual documents Guile version 3.0.10.
|
|
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
|
Inc.
|
|
|
|
Copyright (C) 2021 Maxime Devos
|
|
|
|
Copyright (C) 2024 Tomas Volf
|
|
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
copy of the license is included in the section entitled "GNU Free
|
|
Documentation License." -->
|
|
<title>Tracing Traps (Guile Reference Manual)</title>
|
|
|
|
<meta name="description" content="Tracing Traps (Guile Reference Manual)">
|
|
<meta name="keywords" content="Tracing Traps (Guile Reference Manual)">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content=".texi2any-real">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<link href="index.html" rel="start" title="Top">
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="Traps.html" rel="up" title="Traps">
|
|
<link href="Trap-States.html" rel="next" title="Trap States">
|
|
<link href="Low_002dLevel-Traps.html" rel="prev" title="Low-Level Traps">
|
|
<style type="text/css">
|
|
<!--
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
|
div.example {margin-left: 3.2em}
|
|
span:hover a.copiable-link {visibility: visible}
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
|
-->
|
|
</style>
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<div class="subsubsection-level-extent" id="Tracing-Traps">
|
|
<div class="nav-panel">
|
|
<p>
|
|
Next: <a href="Trap-States.html" accesskey="n" rel="next">Trap States</a>, Previous: <a href="Low_002dLevel-Traps.html" accesskey="p" rel="prev">Low-Level Traps</a>, Up: <a href="Traps.html" accesskey="u" rel="up">Traps</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<h4 class="subsubsection" id="Tracing-Traps-1"><span>6.26.4.4 Tracing Traps<a class="copiable-link" href="#Tracing-Traps-1"> ¶</a></span></h4>
|
|
|
|
<p>The <code class="code">(system vm trace)</code> module defines a number of traps for
|
|
tracing of procedure applications. When a procedure is <em class="dfn">traced</em>, it
|
|
means that every call to that procedure is reported to the user during a
|
|
program run. The idea is that you can mark a collection of procedures
|
|
for tracing, and Guile will subsequently print out a line of the form
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">| | (<var class="var">procedure</var> <var class="var">args</var> ...)
|
|
</pre></div>
|
|
|
|
<p>whenever a marked procedure is about to be applied to its arguments.
|
|
This can help a programmer determine whether a function is being called
|
|
at the wrong time or with the wrong set of arguments.
|
|
</p>
|
|
<p>In addition, the indentation of the output is useful for demonstrating
|
|
how the traced applications are or are not tail recursive with respect
|
|
to each other. Thus, a trace of a non-tail recursive factorial
|
|
implementation looks like this:
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">scheme@(guile-user)> (define (fact1 n)
|
|
(if (zero? n) 1
|
|
(* n (fact1 (1- n)))))
|
|
scheme@(guile-user)> ,trace (fact1 4)
|
|
trace: (fact1 4)
|
|
trace: | (fact1 3)
|
|
trace: | | (fact1 2)
|
|
trace: | | | (fact1 1)
|
|
trace: | | | | (fact1 0)
|
|
trace: | | | | 1
|
|
trace: | | | 1
|
|
trace: | | 2
|
|
trace: | 6
|
|
trace: 24
|
|
</pre></div>
|
|
|
|
<p>While a typical tail recursive implementation would look more like this:
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">scheme@(guile-user)> (define (facti acc n)
|
|
(if (zero? n) acc
|
|
(facti (* n acc) (1- n))))
|
|
scheme@(guile-user)> (define (fact2 n) (facti 1 n))
|
|
scheme@(guile-user)> ,trace (fact2 4)
|
|
trace: (fact2 4)
|
|
trace: (facti 1 4)
|
|
trace: (facti 4 3)
|
|
trace: (facti 12 2)
|
|
trace: (facti 24 1)
|
|
trace: (facti 24 0)
|
|
trace: 24
|
|
</pre></div>
|
|
|
|
<p>The low-level traps below (see <a class="pxref" href="Low_002dLevel-Traps.html">Low-Level Traps</a>) share some common
|
|
options:
|
|
</p>
|
|
<dl class="table">
|
|
<dt><code class="code">#:width</code></dt>
|
|
<dd><p>The maximum width of trace output. Trace printouts will try not to
|
|
exceed this column, but for highly nested procedure calls, it may be
|
|
unavoidable. Defaults to 80.
|
|
</p></dd>
|
|
<dt><code class="code">#:vm</code></dt>
|
|
<dd><p>The VM on which to add the traps. Defaults to the current thread’s VM.
|
|
</p></dd>
|
|
<dt><code class="code">#:prefix</code></dt>
|
|
<dd><p>A string to print out before each trace line. As seen above in the
|
|
examples, defaults to <code class="code">"trace: "</code>.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<p>To have access to these procedures, you’ll need to have imported the
|
|
<code class="code">(system vm trace)</code> module:
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">(use-modules (system vm trace))
|
|
</pre></div>
|
|
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-trace_002dcalls_002dto_002dprocedure"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">trace-calls-to-procedure</strong> <var class="def-var-arguments">proc [#:width] [#:vm] [#:prefix]</var><a class="copiable-link" href="#index-trace_002dcalls_002dto_002dprocedure"> ¶</a></span></dt>
|
|
<dd><p>Print a trace at applications of and returns from <var class="var">proc</var>.
|
|
</p></dd></dl>
|
|
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-trace_002dcalls_002din_002dprocedure"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">trace-calls-in-procedure</strong> <var class="def-var-arguments">proc [#:width] [#:vm] [#:prefix]</var><a class="copiable-link" href="#index-trace_002dcalls_002din_002dprocedure"> ¶</a></span></dt>
|
|
<dd><p>Print a trace at all applications and returns within the dynamic extent
|
|
of calls to <var class="var">proc</var>.
|
|
</p></dd></dl>
|
|
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-trace_002dinstructions_002din_002dprocedure"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">trace-instructions-in-procedure</strong> <var class="def-var-arguments">proc [#:width] [#:vm]</var><a class="copiable-link" href="#index-trace_002dinstructions_002din_002dprocedure"> ¶</a></span></dt>
|
|
<dd><p>Print a trace at all instructions executed in the dynamic extent of
|
|
calls to <var class="var">proc</var>.
|
|
</p></dd></dl>
|
|
|
|
<p>In addition, Guile defines a procedure to call a thunk, tracing all
|
|
procedure calls and returns within the thunk.
|
|
</p>
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-call_002dwith_002dtrace"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">call-with-trace</strong> <var class="def-var-arguments">thunk [#:calls?=#t] [#:instructions?=#f] [#:width=80]</var><a class="copiable-link" href="#index-call_002dwith_002dtrace"> ¶</a></span></dt>
|
|
<dd><p>Call <var class="var">thunk</var>, tracing all execution within its dynamic extent.
|
|
</p>
|
|
<p>If <var class="var">calls?</var> is true, Guile will print a brief report at each
|
|
procedure call and return, as given above.
|
|
</p>
|
|
<p>If <var class="var">instructions?</var> is true, Guile will also print a message each
|
|
time an instruction is executed. This is a lot of output, but it is
|
|
sometimes useful when doing low-level optimization.
|
|
</p>
|
|
<p>Note that because this procedure manipulates the VM trace level
|
|
directly, it doesn’t compose well with traps at the REPL.
|
|
</p></dd></dl>
|
|
|
|
<p>See <a class="xref" href="Profile-Commands.html">Profile Commands</a>, for more information on tracing at the REPL.
|
|
</p>
|
|
</div>
|
|
<hr>
|
|
<div class="nav-panel">
|
|
<p>
|
|
Next: <a href="Trap-States.html">Trap States</a>, Previous: <a href="Low_002dLevel-Traps.html">Low-Level Traps</a>, Up: <a href="Traps.html">Traps</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|