value stacktrace@ : unit?

value stacktrace/annotator@ : unit?

value stacktrace/filter@ : unit?

value stacktrace/annotator/filter@ : unit?

signature stacktrace^ : signature

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

procedure (annotate-top stx phase-level) → syntax?   stx : syntax?   phase-level : exact-nonnegative-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.

procedure (make-st-mark stx phase-level) → (or/c #f st-mark?)   stx : syntax?   phase-level : exact-nonnegative-integer?

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

procedure (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 shape of the value is guaranteed to be writable and not to be #f, but otherwise unspecified). The make-st-mark function returns #f when there is no source location information in the syntax object. 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.

signature stacktrace-imports^ : signature

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

source-stx : any/c

dest-stx : any/c

phase : exact-nonnegative-integer?

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

parameter (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, code generated by test-covered are inserted into the code (and initialize-test-coverage-point is called during compilation). If not, no calls to test-covered code are inserted.

procedure (test-covered stx) → (or/c syntax? (-> void?) #f)

stx : any/c

This is called during compilation of the program with an expression for each point in the program that was passed to initialize-test-coverage-point.

If the result is #f, this program point is not instrumented. If the result is syntax, it is inserted into the code, and if it is a thunk, the thunk is inserted into the code in an application (using the thunk directly, as a 3D value). In either case, the syntax or the thunk should register that the relevant point was covered.

Note: using a thunk tends to be slow. Current uses in the Racket code will create a mutable pair in initialize-test-coverage-point, and test-covered returns syntax that will set its mcar. (This makes the resulting overhead about 3 times smaller.)

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

stx : any/c

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

value profile-key : any/c

Only used for profiling paths.

parameter (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.

procedure (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.

procedure (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.

procedure (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.

signature stacktrace/annotator-imports^ : signature

Like stacktrace^, but providing more control over the annotation function for test cases. The only difference between the two signatures is test-coverage-enabled, initialize-test-coverage-point, and test-covered are replaced by test-coverage-point.

procedure (test-coverage-point body expr phase) → syntax?

body : syntax?

expr : syntax?

phase : exact-integer?

Initializes the test coverage point for expr and returns the syntax that will cover it. body is the body that should be run after the coverage for expr has been recorded as covered. body and expr may not be the same. For example expr may not have appeared in an expression position. phase is the phase level at which expr appeared.

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

source-stx : any/c

dest-stx : any/c

phase : exact-nonnegative-integer?

Same as in stacktrace-imports^.

value profile-key : any/c

Same as in stacktrace-imports^.

parameter (profiling-enabled) → boolean?

(profiling-enabled on?) → void?

on? : any/c

Same as in stacktrace-imports^.

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

key : any/c

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

stx : any/c

Same as in stacktrace-imports^.

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

key : any/c

Same as in stacktrace-imports^.

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

key : any/c

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

Same as stacktrace-imports^.

signature stacktrace-filter^ : signature

The function defined for stacktrace-filter^ provides additional control over the expressions that are instrumented for debugging an profiling.

Added in version 1.2 of package errortrace-lib.

procedure (should-annotate? stx phase) → any/c

stx : syntax?

phase : exact-nonnegative-integer?

Determines whether the annotate function from stacktrace/filter@ or stacktrace/annotator/filter@ adds debugging and/or test-coverage annotation to the immediate expression represented by stx. Annotation is added only when should-annotate? returns a true value, but subexpressions of stx will be checked and potentially annotated independent of the result for stx.

The default filter function used by stacktrace@ and stacktrace/annotator@ annotates an expression if it has a source location according to syntax-source.

When used via the errortrace meta-language or when requireing the errortrace module or when using errortrace via the "Debugging" option in DrRacket, the should-annotate? function checks to make sure that the syntax object has a source location and has the syntax property 'errortrace:annotate.