* 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,
 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
 
 @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
 
 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.
 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]
 @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.
 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
 
 traps          yes     Enable evaluator traps.
 @end smallexample
 


@@ -612,6 +613,20 @@ way.
 @var{retval} is the return value.
 @end deffn
 
 @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
 
 @node Debugger options
 @subsubsection Debugger options