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

5 Re-using Errortrace Stack Tracing

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

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

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.

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.