* api-options.texi (Evaluator trap options): document

memoize-symbol-handler

* api-evaluation.texi (Evaluator Behaviour): link to the Evaluator
trap options node in trap-enable/trap-set! doco.

diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 9ffa06b..880772f 100644 (file)
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,3 +1,11 @@
+2007-01-19  Han-Wen Nienhuys  <hanwen@lilypond.org>
+
+       * api-options.texi (Evaluator trap options): document
+       memoize-symbol-handler
+
+       * api-evaluation.texi (Evaluator Behaviour): link to the Evaluator
+       trap options node in trap-enable/trap-set! doco.
+
 2007-01-16  Kevin Ryde  <user42@zip.com.au>
 
        * api-data.texi (Mapping Folding and Unfolding): In string-unfold,

diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index 5f816dc..68c2022 100644 (file)
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -615,14 +615,21 @@ Invoke the Guile debugger to explore the context of the last error.
 
 @cindex Low level trap calls
 @cindex Evaluator trap calls
-Guile's evaluator can be configured to call three user-specified
-procedures at various points in its operation: an
-@dfn{apply-frame-handler} procedure, an @dfn{enter-frame-handler}
-procedure, and an @dfn{exit-frame-handler} procedure.  These procedures,
-and the circumstances under which the evaluator calls them, are
-configured by the ``evaluator trap options'' interface (@pxref{Evaluator
-trap options}), and by the @code{trace} and @code{breakpoints} fields of
-the ``debug options'' interface (@pxref{Debugger options}).
+Guile's evaluator can be configured to call the following four user-specified
+procedures at various points in its operation.
+
+@table @dfn
+@item apply-frame-handler
+@item enter-frame-handler
+@item exit-frame-handler
+@item memoize-symbol-handler
+@end table
+
+These procedures, and the circumstances under which the evaluator
+calls them, are configured by the ``evaluator trap options'' interface
+(@pxref{Evaluator trap options}), and by the @code{trace} and
+@code{breakpoints} fields of the ``debug options'' interface
+(@pxref{Debugger options}).
 
 It is not necessary to understand the fine details of these low level
 calls, and of the options which configure them, in order to use the

diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 1da13de..6fd363d 100644 (file)
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -629,6 +629,9 @@ Like @code{help}, but also print programmer options.
 Modify the evaluator options.  @code{trap-enable} should be used with boolean
 options and switches them on, @code{trap-disable} switches them off.
 @code{trap-set!} can be used to set an option to a specific value.
+
+See @ref{Evaluator trap options} for more information on the available
+trap handlers.
 @end deffn
 
 @deffn {Scheme Procedure} evaluator-traps-interface [setting]

diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi
index 6dbc370..493e238 100644 (file)
--- a/doc/ref/api-options.texi
+++ b/doc/ref/api-options.texi
@@ -554,6 +554,7 @@ Here is the list of evaluator trap options generated by typing
 exit-frame      no      Trap when exiting eval or apply.
 apply-frame     no      Trap when entering apply.
 enter-frame     no      Trap when eval enters new frame.
+memoize-symbol  no      Trap when eval memoizes a symbol's value
 traps          yes     Enable evaluator traps.
 @end smallexample
 
@@ -612,6 +613,20 @@ way.
 @var{retval} is the return value.
 @end deffn
 
+
+@deffn memoize-symbol-handler key cont expression env
+Called when the evaluator memoizes the value of a procedure symbol
+
+@var{cont} is a ``debug object'', which means that it can be passed to
+@code{make-stack} to discover the stack at the point of the trap.  The
+exit frame handler's code can capture a restartable continuation if it
+wants to by using @code{call-with-current-continuation} in the usual
+way.
+
+@var{retval} is the return value.
+@end deffn
+
+
 @node Debugger options
 @subsubsection Debugger options