6.26.1.1 Stack Capture ¶

A Scheme program can use the make-stack primitive anywhere in its code, with first arg #t, to construct a Scheme value that describes the Scheme stack at that point.

(make-stack #t)
⇒
#<stack 25205a0>

Use start-stack to limit the stack extent captured by future make-stack calls.

Scheme Procedure: make-stack obj arg … ¶

C Function: scm_make_stack (obj, args) ¶

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 a continuation or a frame object).

arg … can be any combination of integer, procedure, address range, and prompt tag 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_i can be an integer, a procedure, an address range, or a prompt tag. An integer means to cut away exactly that number of frames. A procedure means to cut away all frames up to but excluding the frame whose procedure matches the specified one. An address range is a pair of integers indicating the low and high addresses of a procedure’s code, and is the same as cutting away to a procedure (though with less work). Anything else is interpreted as a prompt tag which cuts away all frames that are inside a prompt with the given tag.

Each outer_cut_i can likewise be an integer, a procedure, an address range, or a prompt tag. An integer means to cut away that number of frames. A procedure means to cut away frames down to but excluding the frame whose procedure matches the specified one. An address range is the same, but with the procedure’s code specified as an address range. Anything else is taken to be a prompt tag, which cuts away all frames that are outside a prompt with the given tag.

If the outer_cut_i of the last pair is missing, it is taken as 0.

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.