5 Re-using Errortrace Stack Tracing

(require errortrace/stacktrace)

The errortrace collection also includes a errortrace/stacktrace library. It exports the stacktrace@ unit, its import signature stacktrace-imports^, and its export signature stacktrace^.

stacktrace@ : unit?

Imports stacktrace-imports^ and exports stacktrace^.

stacktrace^ : signature

(annotate stx phase-level) → syntax?   stx : syntax?   phase-level : exact-integer?

(annotate-top stx phase-level) → syntax?   stx : syntax?   phase-level : exact-integer?

Annotate expressions with errortrace information. The annotate-top function should be called with a top-level expression, and annotate should be called with a nested expression (e.g., by initialize-profile-point). The phase-level argument indicates the phase level of the expression, typically (namespace-base-phase) for a top-level expression.

(make-st-mark syntax) → st-mark?   syntax : syntax?

(st-mark-source st-mark) → syntax?   st-mark : st-mark?

(st-mark-bindings st-mark) → list?   st-mark : st-mark?

The st-mark-source and st-mark-bindings functions extract information from a particular kind of value. The value must be created by make-st-mark. The st-mark-source extracts the value originally provided to the expression-maker, and st-mark-bindings returns local binding information (if available) as a list of two element (syntax? any/c) lists. The st-mark-bindings function is currently hardwired to return null.

stacktrace-imports^ : signature

(with-mark source-stx dest-stx) → any/c

source-stx : any/c

dest-stx : any/c

Called by annotate and annotate-top to wrap expressions with with-continuation-mark. The first argument is the source expression and the second argument is the expression to be wrapped.

(test-coverage-enabled) → boolean?

(test-coverage-enabled on?) → void?

on? : any/c

Determines if the test coverage annotation is inserted into the code. This parameter controls how compilation happens – it does not affect the dynamic behavior of the already compiled code. If the parameter is set, calls to test-covered are inserted into the code (and initialize-test-coverage-point is called during compilation). If not, no calls to test-covered are inserted.

(test-covered key) → void?

key : any/c

During execution of the program, this is called for each point with the key for that program point that was passed to initialize-test-coverage-point.

(initialize-test-coverage-point key stx) → void?

key : any/c

stx : any/c

During compilation of the program, this function is called with each sub-expression of the program. The first argument is a special key used to identify this program point. The second argument is the syntax of this program point.

profile-key : any/c

Only used for profiling paths.

(profiling-enabled) → boolean?

(profiling-enabled on?) → void?

on? : any/c

Determines if profiling information is currently collected (affects the behavior of compiling the code – does not affect running code). If this always returns #f, the other profiling functions are never called.

(initialize-profile-point key name stx) → void?

key : any/c

name : (or/c syntax? false/c)

stx : any/c

Called as the program is compiled for each profiling point that might be encountered during the program’s execution. The first argument is a key identifying this code. The second argument is the inferred name at this point and the final argument is the syntax of this expression.

(register-profile-start key) → (or/c number? false/c)

key : any/c

Called when some profiled code is about to be executed. If the result is a number, it is expected to be the current number of milliseconds. key is unique to this fragment of code – it is the same key passed to initialize-profile-point for this code fragment.

(register-profile-done key start) → void?

key : any/c

start : (or/c number? false/c)

This function is called when some profiled code is finished executing.

Note that register-profile-start and register-profile-done can be called in a nested manner; in this case, the result of register-profile-start should be #f.