Next: , Previous: Translation, Up: Top

35 Debugging Infrastructure

— Scheme Procedure: debug-options-interface [setting]
— C Function: scm_debug_options (setting) |0 |1 |0

Option interface for the debug options. Instead of using this procedure directly, use the procedures debug-enable, debug-disable, debug-set! and debug-options.

35.1 Using Traps

— Scheme Procedure: with-traps thunk
— C Function: scm_with_traps (thunk)

Call thunk with traps enabled.

— Scheme Procedure: debug-object? obj
— C Function: scm_debug_object_p (obj)

Return #t if obj is a debug object.

35.2 Capturing the Stack or Innermost Stack Frame

When an error occurs in a running program, or the program hits a breakpoint, its state at that point can be represented by a stack of all the evaluations and procedure applications that are logically in progress at that time, each of which is known as a frame. The programmer can learn more about the program's state at the point of interruption or error by inspecting the stack and its frames.

— Scheme Procedure: make-stack obj [args ...]
— C Function: scm_make_stack (obj, args) |1 |0 |1

Create a new stack. If obj is #t, the current evaluation stack is used for creating the stack frames, otherwise the frames are taken from obj (which must be either a debug object or a continuation).

args should be a list containing any combination of integer, procedure and #t values.

These values specify various ways of cutting away uninteresting stack frames from the top and bottom of the stack that make-stack returns. They come in pairs like this: (inner-cut-1 outer-cut-1 inner-cut-2 outer-cut-2 ...).

Each inner-cut-N can be #t, an integer, or a procedure. #t means to cut away all frames up to but excluding the first user module frame. An integer means to cut away exactly that number of frames. A procedure means to cut away all frames up to but excluding the application frame whose procedure matches the specified one.

Each outer-cut-N can be an integer or a procedure. An integer means to cut away that number of frames. A procedure means to cut away frames down to but excluding the application frame whose procedure matches the specified one.

If the outer-cut-N of the last pair is missing, it is taken as 0.

— Scheme Procedure: last-stack-frame obj
— C Function: scm_last_stack_frame (obj)

Return a stack which consists of a single frame, which is the last stack frame for obj. obj must be either a debug object or a continuation.

35.3 Examining the Stack

— Scheme Procedure: stack? obj
— C Function: scm_stack_p (obj)

Return #t if obj is a calling stack.

— Scheme Procedure: stack-id stack
— C Function: scm_stack_id (stack)

Return the identifier given to stack by start-stack.

— Scheme Procedure: stack-length stack
— C Function: scm_stack_length (stack)

Return the length of stack.

— Scheme Procedure: stack-ref stack i
— C Function: scm_stack_ref (stack, i)

Return the index'th frame from stack.

— Scheme Procedure: display-backtrace stack port [first [depth]]
— C Function: scm_display_backtrace (stack, port, first, depth) |2 |2 |0

Display a backtrace to the output port port. stack is the stack to take the backtrace from, first specifies where in the stack to start and depth how much frames to display. Both first and depth can be #f, which means that default values will be used.

35.4 Examining Stack Frames

— Scheme Procedure: frame? obj
— C Function: scm_frame_p (obj)

Return #t if obj is a stack frame.

— Scheme Procedure: frame-number frame
— C Function: scm_frame_number (frame)

Return the frame number of frame.

— Scheme Procedure: frame-previous frame
— C Function: scm_frame_previous (frame)

Return the previous frame of frame, or #f if frame is the first frame in its stack.

— Scheme Procedure: frame-next frame
— C Function: scm_frame_next (frame)

Return the next frame of frame, or #f if frame is the last frame in its stack.

— Scheme Procedure: frame-source frame
— C Function: scm_frame_source (frame)

Return the source of frame.

— Scheme Procedure: frame-procedure? frame
— C Function: scm_frame_procedure_p (frame)

Return #t if a procedure is associated with frame.

— Scheme Procedure: frame-procedure frame
— C Function: scm_frame_procedure (frame)

Return the procedure for frame, or #f if no procedure is associated with frame.

— Scheme Procedure: frame-arguments frame
— C Function: scm_frame_arguments (frame)

Return the arguments of frame.

— Scheme Procedure: frame-evaluating-args? frame
— C Function: scm_frame_evaluating_args_p (frame)

Return #t if frame contains evaluated arguments.

— Scheme Procedure: frame-overflow? frame
— C Function: scm_frame_overflow_p (frame)

Return #t if frame is an overflow frame.

— Scheme Procedure: frame-real? frame
— C Function: scm_frame_real_p (frame)

Return #t if frame is a real frame.

— Scheme Procedure: display-application frame [port [indentation]]
— C Function: scm_display_application (frame, port, indentation) |1 |2 |0

Display a procedure application frame to the output port port. indentation specifies how many columns to indent the output.

35.5 Decoding Memoized Source Expressions

— Scheme Procedure: memoized? obj
— C Function: scm_memoized_p (obj)

Return #t if obj is memoized.

— Scheme Procedure: unmemoize m
— C Function: scm_unmemoize (m)

Unmemoize the memoized expression m.

— Scheme Procedure: memoized-environment m
— C Function: scm_memoized_environment (m)

Return the environment of the memoized expression m.

35.6 Starting a New Stack

— Scheme Syntax: start-stack id exp

Evaluate exp on a new calling stack with identity id. If exp is interrupted during evaluation, backtraces will not display frames farther back than exp's top-level form. This macro is a way of artificially limiting backtraces and stack procedures, largely as a convenience to the user.