▼ |  | Errortrace: Debugging and Profiling

1 | Quick Instructions
2 | Installing Errortrace
3 | Using Errortrace
4 | Errortrace Library
5 | Re-using Errortrace Stack Tracing
6 | Errortrace Key

On this page:

stacktrace@
stacktrace^
annotate
annotate-top
make-st-mark
st-mark-source
st-mark-bindings
stacktrace-imports^
with-mark
test-coverage-enabled
test-covered
initialize-test-coverage-point
profile-key
profiling-enabled
initialize-profile-point
register-profile-start
register-profile-done

top ← prev up next →

### 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) → ( or/c #f 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 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.

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, 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.

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

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

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

top ← prev up next →