summaryrefslogtreecommitdiff
path: root/doc/ref/api-debug.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r--doc/ref/api-debug.texi82
1 files changed, 41 insertions, 41 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index 660989895..faa0c40bd 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -36,19 +36,19 @@ A Scheme stack always exists implicitly, and can be summoned into
concrete existence as a first-class Scheme value by the
@code{make-stack} call, so that an introspective Scheme program -- such
as a debugger -- can present it in some way and allow the user to query
-its details. The first thing to understand, therefore, is how Guile's
+its details. The first thing to understand, therefore, is how Guile's
function call convention creates the stack.
-Broadly speaking, Guile represents all control flow on a stack. Calling
+Broadly speaking, Guile represents all control flow on a stack. Calling
a function involves pushing an empty frame on the stack, then evaluating
the procedure and its arguments, then fixing up the new frame so that it
-points to the old one. Frames on the stack are thus linked together. A
+points to the old one. Frames on the stack are thus linked together. A
tail call is the same, except it reuses the existing frame instead of
pushing on a new one.
In this way, the only frames that are on the stack are ``active''
frames, frames which need to do some work before the computation is
-complete. On the other hand, a function that has tail-called another
+complete. On the other hand, a function that has tail-called another
function will not be on the stack, as it has no work left to do.
Therefore, when an error occurs in a running program, or the program
@@ -83,7 +83,7 @@ Use @code{start-stack} to limit the stack extent captured by future
@deffn {Scheme Procedure} make-stack obj arg @dots{}
@deffnx {C Function} scm_make_stack (obj, args)
-Create a new stack. If @var{obj} is @code{#t}, the current
+Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be
a continuation or a frame object).
@@ -239,7 +239,7 @@ output.
Additionally, the @code{(system vm frame)} module defines a number of
higher-level introspective procedures, for example to retrieve the names
of local variables, and the source location to correspond to a
-frame. See its source code for more details.
+frame. See its source code for more details.
@node Source Properties
@@ -341,7 +341,7 @@ with the new pair.
@subsection Programmatic Error Handling
For better or for worse, all programs have bugs, and dealing with bugs
-is part of programming. This section deals with that class of bugs that
+is part of programming. This section deals with that class of bugs that
causes an exception to be raised -- from your own code, from within a
library, or from Guile itself.
@@ -733,7 +733,7 @@ warn-deprecated no Warn when deprecated features are used.
@end smallexample
The boolean options may be toggled with @code{debug-enable} and
-@code{debug-disable}. The non-boolean options must be set using
+@code{debug-disable}. The non-boolean options must be set using
@code{debug-set!}.
@deffn {Scheme Procedure} debug-enable option-name
@@ -766,16 +766,16 @@ it chooses for examining the evaluation stack as program execution
proceeds, and for suspending execution to be resumed later.
VM hooks are very low-level, though, and so Guile also has a library of
-higher-level @dfn{traps} on top of the VM hooks. A trap is an execution
-condition that, when fulfilled, will fire a handler. For example, Guile
+higher-level @dfn{traps} on top of the VM hooks. A trap is an execution
+condition that, when fulfilled, will fire a handler. For example, Guile
defines a trap that fires when control reaches a certain source
location.
Finally, Guile also defines a third level of abstractions: per-thread
-@dfn{trap states}. A trap state exists to give names to traps, and to
+@dfn{trap states}. A trap state exists to give names to traps, and to
hold on to the set of traps so that they can be enabled, disabled, or
-removed. The trap state infrastructure defines the most useful
-abstractions for most cases. For example, Guile's REPL uses trap state
+removed. The trap state infrastructure defines the most useful
+abstractions for most cases. For example, Guile's REPL uses trap state
functions to set breakpoints and tracepoints.
The following subsections describe all this in detail, for both the
@@ -789,7 +789,7 @@ understanding how the interface hangs together.
* Low-Level Traps:: The various kinds of low-level traps.
* Tracing Traps:: Traps to trace procedure calls and returns.
* Trap States:: One state (per thread) to bind them.
-* High-Level Traps:: The highest-level trap interface. Use this.
+* High-Level Traps:: The highest-level trap interface. Use this.
@end menu
@@ -800,8 +800,8 @@ Everything that runs in Guile runs on its virtual machine, a C program
that defines a number of operations that Scheme programs can
perform.
-Note that there are multiple VM ``engines'' for Guile. Only some of them
-have support for hooks compiled in. Normally the deal is that you get
+Note that there are multiple VM ``engines'' for Guile. Only some of them
+have support for hooks compiled in. Normally the deal is that you get
hooks if you are running interactively, and otherwise they are disabled,
as they do have some overhead (about 10 or 20 percent).
@@ -821,7 +821,7 @@ does a terrible thing: it allocates the frames on the C stack instead of
the garbage-collected heap.
The upshot here is that the frames are only valid within the dynamic
-extent of the call to the hook. If a hook procedure keeps a reference to
+extent of the call to the hook. If a hook procedure keeps a reference to
the frame outside the extent of the hook, bad things will happen.
The interface to hooks is provided by the @code{(system vm vm)} module:
@@ -875,10 +875,10 @@ Remove @var{f} from the corresponding VM hook for the current thread.
@end deffn
@cindex VM trace level
-These hooks do impose a performance penalty, if they are on. Obviously,
-the @code{vm-next-hook} has quite an impact, performance-wise. Therefore
+These hooks do impose a performance penalty, if they are on. Obviously,
+the @code{vm-next-hook} has quite an impact, performance-wise. Therefore
Guile exposes a single, heavy-handed knob to turn hooks on or off, the
-@dfn{VM trace level}. If the trace level is positive, hooks run;
+@dfn{VM trace level}. If the trace level is positive, hooks run;
otherwise they don't.
For convenience, when the VM fires a hook, it does so with the trap
@@ -887,8 +887,8 @@ handling a hook. The trace level is restored to whatever it was once the hook
procedure finishes.
@deffn {Scheme Procedure} vm-trace-level
-Retrieve the ``trace level'' of the VM. If positive, the trace hooks
-associated with @var{vm} will be run. The initial trace level is 0.
+Retrieve the ``trace level'' of the VM. If positive, the trace hooks
+associated with @var{vm} will be run. The initial trace level is 0.
@end deffn
@deffn {Scheme Procedure} set-vm-trace-level! level
@@ -907,7 +907,7 @@ correspond to what users want to do.
For example, if a user wants to break when and if control reaches a
certain source location, how do you do it? If you install a ``next''
hook, you get unacceptable overhead for the execution of the entire
-program. It would be possible to install an ``apply'' hook, then if the
+program. It would be possible to install an ``apply'' hook, then if the
procedure encompasses those source locations, install a ``next'' hook,
but already you're talking about one concept that might be implemented
by a varying number of lower-level concepts.
@@ -916,27 +916,27 @@ It's best to be clear about things and define one abstraction for all
such conditions: the @dfn{trap}.
Considering the myriad capabilities offered by the hooks though, there
-is only a minimum of functionality shared by all traps. Guile's current
+is only a minimum of functionality shared by all traps. Guile's current
take is to reduce this to the absolute minimum, and have the only
standard interface of a trap be ``turn yourself on'' or ``turn yourself
off''.
This interface sounds a bit strange, but it is useful to procedurally
-compose higher-level traps from lower-level building blocks. For
+compose higher-level traps from lower-level building blocks. For
example, Guile defines a trap that calls one handler when control enters
-a procedure, and another when control leaves the procedure. Given that
+a procedure, and another when control leaves the procedure. Given that
trap, one can define a trap that adds to the next-hook only when within
-a given procedure. Building further, one can define a trap that fires
+a given procedure. Building further, one can define a trap that fires
when control reaches particular instructions within a procedure.
-Or of course you can stop at any of these intermediate levels. For
-example, one might only be interested in calls to a given procedure. But
+Or of course you can stop at any of these intermediate levels. For
+example, one might only be interested in calls to a given procedure. But
the point is that a simple enable/disable interface is all the
commonality that exists between the various kinds of traps, and
furthermore that such an interface serves to allow ``higher-level''
traps to be composed from more primitive ones.
-Specifically, a trap, in Guile, is a procedure. When a trap is created,
+Specifically, a trap, in Guile, is a procedure. When a trap is created,
by convention the trap is enabled; therefore, the procedure that is the
trap will, when called, disable the trap, and return a procedure that
will enable the trap, and so on.
@@ -945,10 +945,10 @@ Trap procedures take one optional argument: the current frame. (A trap
may want to add to different sets of hooks depending on the frame that
is current at enable-time.)
-If this all sounds very complicated, it's because it is. Some of it is
-essential, but probably most of it is not. The advantage of using this
+If this all sounds very complicated, it's because it is. Some of it is
+essential, but probably most of it is not. The advantage of using this
minimal interface is that composability is more lexically apparent than
-when, for example, using a stateful interface based on GOOPS. But
+when, for example, using a stateful interface based on GOOPS. But
perhaps this reflects the cognitive limitations of the programmer who
made the current interface more than anything else.
@@ -958,20 +958,20 @@ made the current interface more than anything else.
To summarize the last sections, traps are enabled or disabled, and when
they are enabled, they add to various VM hooks.
-Note, however, that @emph{traps do not increase the VM trace level}. So
+Note, however, that @emph{traps do not increase the VM trace level}. So
if you create a trap, it will be enabled, but unless something else
increases the VM's trace level (@pxref{VM Hooks}), the trap will not
fire. It turns out that getting the VM trace level right is tricky
without a global view of what traps are enabled. @xref{Trap States},
for Guile's answer to this problem.
-Traps are created by calling procedures. Most of these procedures share
+Traps are created by calling procedures. Most of these procedures share
a set of common keyword arguments, so rather than document them
separately, we discuss them all together here:
@table @code
@item #:vm
-The VM to instrument. Defaults to the current thread's VM.
+The VM to instrument. Defaults to the current thread's VM.
@item #:current-frame
For traps that enable more hooks depending on their dynamic context,
this argument gives the current frame that the trap is running in.
@@ -1028,7 +1028,7 @@ A trap that calls @var{next-handler} for every instruction executed in
handler [#:current-frame] [#:vm]
A trap that calls @var{handler} when execution enters a range of
instructions in @var{proc}. @var{range} is a simple of pairs,
-@code{((@var{start} . @var{end}) ...)}. The @var{start} addresses are
+@code{((@var{start} . @var{end}) ...)}. The @var{start} addresses are
inclusive, and @var{end} addresses are exclusive.
@end deffn
@@ -1146,13 +1146,13 @@ options:
@table @code
@item #:width
-The maximum width of trace output. Trace printouts will try not to
+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.
+unavoidable. Defaults to 80.
@item #:vm
-The VM on which to add the traps. Defaults to the current thread's VM.
+The VM on which to add the traps. Defaults to the current thread's VM.
@item #:prefix
-A string to print out before each trace line. As seen above in the
+A string to print out before each trace line. As seen above in the
examples, defaults to @code{"trace: "}.
@end table