diff options
-rw-r--r-- | doc/ref/ChangeLog | 20 | ||||
-rw-r--r-- | doc/ref/debugging.texi | 6 | ||||
-rw-r--r-- | doc/ref/scheme-control.texi | 11 | ||||
-rw-r--r-- | doc/ref/scheme-debug.texi | 255 | ||||
-rw-r--r-- | doc/ref/scheme-memory.texi | 14 | ||||
-rw-r--r-- | doc/ref/scheme-procedures.texi | 24 |
6 files changed, 180 insertions, 150 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index 1b3c63622..ced89de8c 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,5 +1,25 @@ 2002-04-20 Neil Jerram <neil@ossau.uklinux.net> + * scheme-debug.texi (Debugging): Rename chapter `Debugging + Infrastructure' and reorganize its contents. + + * scheme-debug.texi (Debugging), scheme-control.texi (Handling + Errors): Move display-error to error-focussed section. + + * scheme-debug.texi (Debugging), debugging.texi (Backtrace): Move + backtrace to user-level debugging chapter. + + * scheme-debug.texi (Debugging), scheme-procedures.texi (Procedure + Properties): Move procedure-name, procedure-source and + procedure-environment to procedures chapter. + + * scheme-debug.texi (Debugging), scheme-memory.texi (Memory + Blocks): Move malloc-stats to memory management chapter. + + * scheme-procedures.texi (Syntax Rules): Remove mention of + use-modules for loading syncase; only use-syntax really works. + Thanks to Panagiotis Vossos for spotting this. + * program.texi (Scheme vs C): New node, with existing material taken from chapter intro. (Programming Overview): New intro para to introduce example of diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi index 45fef5082..0a2471ca8 100644 --- a/doc/ref/debugging.texi +++ b/doc/ref/debugging.texi @@ -109,6 +109,12 @@ iteration. Using @code{trace} here helps us see why this is so. @node Backtrace @section Backtrace +@deffn {Scheme Procedure} backtrace +@deffnx {C Function} scm_backtrace () +Display a backtrace of the stack saved by the last error +to the current output port. +@end deffn + @node Stacks and Frames @section Stacks and Frames diff --git a/doc/ref/scheme-control.texi b/doc/ref/scheme-control.texi index e8d70e449..184ccae9d 100644 --- a/doc/ref/scheme-control.texi +++ b/doc/ref/scheme-control.texi @@ -878,6 +878,17 @@ Throw an error using the key @code{'misc-error}. The error message is created by displaying @var{msg} and writing the @var{args}. @end deffn +@deffn {Scheme Procedure} display-error stack port subr message args rest +@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest) +Display an error message to the output port @var{port}. +@var{stack} is the saved stack for the error, @var{subr} is +the name of the procedure in which the error occurred and +@var{message} is the actual error message, which may contain +formatting instructions. These will format the arguments in +the list @var{args} accordingly. @var{rest} is currently +ignored. +@end deffn + The following are the error keys defined by libguile and the situations in which they are used: diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi index f3dde5a35..ce0be8907 100644 --- a/doc/ref/scheme-debug.texi +++ b/doc/ref/scheme-debug.texi @@ -1,51 +1,6 @@ @page @node Debugging -@chapter Internal Debugging Interface - ---- The name of this chapter needs to clearly distinguish it - from the appendix describing the debugger UI. The intro - should have a pointer to the UI appendix. - -@deffn {Scheme Procedure} display-error stack port subr message args rest -@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest) -Display an error message to the output port @var{port}. -@var{stack} is the saved stack for the error, @var{subr} is -the name of the procedure in which the error occurred and -@var{message} is the actual error message, which may contain -formatting instructions. These will format the arguments in -the list @var{args} accordingly. @var{rest} is currently -ignored. -@end deffn - -@deffn {Scheme Procedure} display-application frame [port [indent]] -@deffnx {C Function} scm_display_application (frame, port, indent) -Display a procedure application @var{frame} to the output port -@var{port}. @var{indent} specifies the indentation of the -output. -@end deffn - -@deffn {Scheme Procedure} display-backtrace stack port [first [depth]] -@deffnx {C Function} scm_display_backtrace (stack, port, first, depth) -Display a backtrace to the output port @var{port}. @var{stack} -is the stack to take the backtrace from, @var{first} specifies -where in the stack to start and @var{depth} how much frames -to display. Both @var{first} and @var{depth} can be @code{#f}, -which means that default values will be used. -@end deffn - -@deffn {Scheme Procedure} backtrace -@deffnx {C Function} scm_backtrace () -Display a backtrace of the stack saved by the last error -to the current output port. -@end deffn - -@deffn {Scheme Procedure} malloc-stats -Return an alist ((@var{what} . @var{n}) ...) describing number -of malloced objects. -@var{what} is the second argument to @code{scm_gc_malloc}, -@var{n} is the number of objects of that type currently -allocated. -@end deffn +@chapter Debugging Infrastructure @deffn {Scheme Procedure} debug-options-interface [setting] @deffnx {C Function} scm_debug_options (setting) @@ -54,110 +9,21 @@ this procedure directly, use the procedures @code{debug-enable}, @code{debug-disable}, @code{debug-set!} and @code{debug-options}. @end deffn + +@section Using Traps + @deffn {Scheme Procedure} with-traps thunk @deffnx {C Function} scm_with_traps (thunk) Call @var{thunk} with traps enabled. @end deffn -@deffn {Scheme Procedure} memoized? obj -@deffnx {C Function} scm_memoized_p (obj) -Return @code{#t} if @var{obj} is memoized. -@end deffn - -@deffn {Scheme Procedure} unmemoize m -@deffnx {C Function} scm_unmemoize (m) -Unmemoize the memoized expression @var{m}, -@end deffn - -@deffn {Scheme Procedure} memoized-environment m -@deffnx {C Function} scm_memoized_environment (m) -Return the environment of the memoized expression @var{m}. -@end deffn - -@deffn {Scheme Procedure} procedure-name proc -@deffnx {C Function} scm_procedure_name (proc) -Return the name of the procedure @var{proc} -@end deffn - -@deffn {Scheme Procedure} procedure-source proc -@deffnx {C Function} scm_procedure_source (proc) -Return the source of the procedure @var{proc}. -@end deffn - -@deffn {Scheme Procedure} procedure-environment proc -@deffnx {C Function} scm_procedure_environment (proc) -Return the environment of the procedure @var{proc}. -@end deffn - @deffn {Scheme Procedure} debug-object? obj @deffnx {C Function} scm_debug_object_p (obj) Return @code{#t} if @var{obj} is a debug object. @end deffn -@deffn {Scheme Procedure} frame-arguments frame -@deffnx {C Function} scm_frame_arguments (frame) -Return the arguments of @var{frame}. -@end deffn - -@deffn {Scheme Procedure} frame-evaluating-args? frame -@deffnx {C Function} scm_frame_evaluating_args_p (frame) -Return @code{#t} if @var{frame} contains evaluated arguments. -@end deffn -@deffn {Scheme Procedure} frame-next frame -@deffnx {C Function} scm_frame_next (frame) -Return the next frame of @var{frame}, or @code{#f} if -@var{frame} is the last frame in its stack. -@end deffn - -@deffn {Scheme Procedure} frame-number frame -@deffnx {C Function} scm_frame_number (frame) -Return the frame number of @var{frame}. -@end deffn - -@deffn {Scheme Procedure} frame-overflow? frame -@deffnx {C Function} scm_frame_overflow_p (frame) -Return @code{#t} if @var{frame} is an overflow frame. -@end deffn - -@deffn {Scheme Procedure} frame-previous frame -@deffnx {C Function} scm_frame_previous (frame) -Return the previous frame of @var{frame}, or @code{#f} if -@var{frame} is the first frame in its stack. -@end deffn - -@deffn {Scheme Procedure} frame-procedure frame -@deffnx {C Function} scm_frame_procedure (frame) -Return the procedure for @var{frame}, or @code{#f} if no -procedure is associated with @var{frame}. -@end deffn - -@deffn {Scheme Procedure} frame-procedure? frame -@deffnx {C Function} scm_frame_procedure_p (frame) -Return @code{#t} if a procedure is associated with @var{frame}. -@end deffn - -@deffn {Scheme Procedure} frame-real? frame -@deffnx {C Function} scm_frame_real_p (frame) -Return @code{#t} if @var{frame} is a real frame. -@end deffn - -@deffn {Scheme Procedure} frame-source frame -@deffnx {C Function} scm_frame_source (frame) -Return the source of @var{frame}. -@end deffn - -@deffn {Scheme Procedure} frame? obj -@deffnx {C Function} scm_frame_p (obj) -Return @code{#t} if @var{obj} is a stack frame. -@end deffn - -@deffn {Scheme Procedure} last-stack-frame obj -@deffnx {C Function} scm_last_stack_frame (obj) -Return a stack which consists of a single frame, which is the -last stack frame for @var{obj}. @var{obj} must be either a -debug object or a continuation. -@end deffn +@section Capturing the Stack or Innermost Stack Frame @deffn {Scheme Procedure} make-stack obj . args @deffnx {C Function} scm_make_stack (obj, args) @@ -191,6 +57,21 @@ If the @var{outer_cut_N} of the last pair is missing, it is taken as 0. @end deffn +@deffn {Scheme Procedure} last-stack-frame obj +@deffnx {C Function} scm_last_stack_frame (obj) +Return a stack which consists of a single frame, which is the +last stack frame for @var{obj}. @var{obj} must be either a +debug object or a continuation. +@end deffn + + +@section Examining the Stack + +@deffn {Scheme Procedure} stack? obj +@deffnx {C Function} scm_stack_p (obj) +Return @code{#t} if @var{obj} is a calling stack. +@end deffn + @deffn {Scheme Procedure} stack-id stack @deffnx {C Function} scm_stack_id (stack) Return the identifier given to @var{stack} by @code{start-stack}. @@ -206,9 +87,99 @@ Return the length of @var{stack}. Return the @var{index}'th frame from @var{stack}. @end deffn -@deffn {Scheme Procedure} stack? obj -@deffnx {C Function} scm_stack_p (obj) -Return @code{#t} if @var{obj} is a calling stack. +@deffn {Scheme Procedure} display-backtrace stack port [first [depth]] +@deffnx {C Function} scm_display_backtrace (stack, port, first, depth) +Display a backtrace to the output port @var{port}. @var{stack} +is the stack to take the backtrace from, @var{first} specifies +where in the stack to start and @var{depth} how much frames +to display. Both @var{first} and @var{depth} can be @code{#f}, +which means that default values will be used. +@end deffn + + +@section Examining Stack Frames + +@deffn {Scheme Procedure} frame? obj +@deffnx {C Function} scm_frame_p (obj) +Return @code{#t} if @var{obj} is a stack frame. +@end deffn + +@deffn {Scheme Procedure} frame-number frame +@deffnx {C Function} scm_frame_number (frame) +Return the frame number of @var{frame}. +@end deffn + +@deffn {Scheme Procedure} frame-previous frame +@deffnx {C Function} scm_frame_previous (frame) +Return the previous frame of @var{frame}, or @code{#f} if +@var{frame} is the first frame in its stack. +@end deffn + +@deffn {Scheme Procedure} frame-next frame +@deffnx {C Function} scm_frame_next (frame) +Return the next frame of @var{frame}, or @code{#f} if +@var{frame} is the last frame in its stack. +@end deffn + +@deffn {Scheme Procedure} frame-source frame +@deffnx {C Function} scm_frame_source (frame) +Return the source of @var{frame}. +@end deffn + +@deffn {Scheme Procedure} frame-procedure? frame +@deffnx {C Function} scm_frame_procedure_p (frame) +Return @code{#t} if a procedure is associated with @var{frame}. +@end deffn + +@deffn {Scheme Procedure} frame-procedure frame +@deffnx {C Function} scm_frame_procedure (frame) +Return the procedure for @var{frame}, or @code{#f} if no +procedure is associated with @var{frame}. +@end deffn + +@deffn {Scheme Procedure} frame-arguments frame +@deffnx {C Function} scm_frame_arguments (frame) +Return the arguments of @var{frame}. +@end deffn + +@deffn {Scheme Procedure} frame-evaluating-args? frame +@deffnx {C Function} scm_frame_evaluating_args_p (frame) +Return @code{#t} if @var{frame} contains evaluated arguments. +@end deffn + +@deffn {Scheme Procedure} frame-overflow? frame +@deffnx {C Function} scm_frame_overflow_p (frame) +Return @code{#t} if @var{frame} is an overflow frame. +@end deffn + +@deffn {Scheme Procedure} frame-real? frame +@deffnx {C Function} scm_frame_real_p (frame) +Return @code{#t} if @var{frame} is a real frame. +@end deffn + +@deffn {Scheme Procedure} display-application frame [port [indent]] +@deffnx {C Function} scm_display_application (frame, port, indent) +Display a procedure application @var{frame} to the output port +@var{port}. @var{indent} specifies the indentation of the +output. +@end deffn + + +@section Decoding Memoized Source Expressions + +@deffn {Scheme Procedure} memoized? obj +@deffnx {C Function} scm_memoized_p (obj) +Return @code{#t} if @var{obj} is memoized. +@end deffn + +@deffn {Scheme Procedure} unmemoize m +@deffnx {C Function} scm_unmemoize (m) +Unmemoize the memoized expression @var{m}, +@end deffn + +@deffn {Scheme Procedure} memoized-environment m +@deffnx {C Function} scm_memoized_environment (m) +Return the environment of the memoized expression @var{m}. @end deffn diff --git a/doc/ref/scheme-memory.texi b/doc/ref/scheme-memory.texi index af0088692..d6f0584c6 100644 --- a/doc/ref/scheme-memory.texi +++ b/doc/ref/scheme-memory.texi @@ -26,6 +26,7 @@ Return an association list of statistics about Guile's current use of storage. @end deffn + @node Memory Blocks @section Memory Blocks @@ -80,7 +81,6 @@ When not enough memory is available, signal an error. This function runs the GC to free up some memory when it deems it appropriate. @end deftypefn - @deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what}) Informs the GC that the memory at @var{mem} of size @var{size} can potentially be freed during a GC. That is, announce that @var{mem} is @@ -108,7 +108,6 @@ this, the GC might have a wrong impression of what is going on and run much less efficiently than it could. @end deftypefn - @deftypefn {C Function} void *scm_gc_malloc (size_t @var{size}, const char *@var{what}) @deftypefnx {C Function} void *scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what}); Like @code{scm_malloc} or @code{scm_realloc}, but also call @@ -127,8 +126,16 @@ frees us from tracking this value in the GC itself, which will keep the memory management overhead very low. @end deftypefn +@deffn {Scheme Procedure} malloc-stats +Return an alist ((@var{what} . @var{n}) ...) describing number +of malloced objects. +@var{what} is the second argument to @code{scm_gc_malloc}, +@var{n} is the number of objects of that type currently +allocated. +@end deffn + -@subsection Upgrading from scm_must_malloc et al +@subsection Upgrading from scm_must_malloc et al. Version 1.6 of Guile and earlier did not have the functions from the previous section. In their place, it had the functions @@ -184,6 +191,7 @@ The important thing is to always pair @code{scm_malloc} with The same reasoning applies to @code{scm_must_realloc} and @code{scm_realloc} versus @code{scm_gc_realloc}. + @node Weak References @section Weak References diff --git a/doc/ref/scheme-procedures.texi b/doc/ref/scheme-procedures.texi index 3da356f4f..36f840ecc 100644 --- a/doc/ref/scheme-procedures.texi +++ b/doc/ref/scheme-procedures.texi @@ -368,6 +368,21 @@ Procedure properties are general properties to be attached to procedures. These can be the name of a procedure or other relevant information, such as debug hints. +@deffn {Scheme Procedure} procedure-name proc +@deffnx {C Function} scm_procedure_name (proc) +Return the name of the procedure @var{proc} +@end deffn + +@deffn {Scheme Procedure} procedure-source proc +@deffnx {C Function} scm_procedure_source (proc) +Return the source of the procedure @var{proc}. +@end deffn + +@deffn {Scheme Procedure} procedure-environment proc +@deffnx {C Function} scm_procedure_environment (proc) +Return the environment of the procedure @var{proc}. +@end deffn + @deffn {Scheme Procedure} procedure-properties proc @deffnx {C Function} scm_procedure_properties (proc) Return @var{obj}'s property list. @@ -627,11 +642,10 @@ example of the previous section looks like this: In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9 syncase)} module. To make these facilities available in your code, -include the expression @code{(use-modules (ice-9 syncase))} or -@code{(use-syntax (ice-9 syncase))} (@pxref{Using Guile Modules}) -before the first usage of @code{define-syntax} etc. If you are writing -a Scheme module, you can alternatively use one of the keywords -@code{#:use-module} and @code{#:use-syntax} in your @code{define-module} +include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using +Guile Modules}) before the first usage of @code{define-syntax} etc. If +you are writing a Scheme module, you can alternatively include the form +@code{#:use-syntax (ice-9 syncase)} in your @code{define-module} declaration (@pxref{Creating Guile Modules}). @menu |