5 Re-using Errortrace Stack Tracing

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

> value stacktrace@ : unit?

Imports stacktrace-imports^ and exports stacktrace^.

> 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 : nonnegative-exact-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.

top ← prev up next →