For Development HEAD DRAFTSearch (procedure/syntax/module):

Previous: , Up: Core library   [Contents][Index]

6.25 Development helper API

Gauche has some basic built-in APIs to help developers to analyze the program.

6.25.1 Debugging aid

Macro: debug-print expr

This macro prints expr in a source form, then evaluates it, then prints out the result(s), and returns them.

The output goes to the current trace port (see Common port operations).

The special reader syntax #?=expr is expanded into (debug-print expr). See Debugging, for the details.

Parameter: debug-print-width

This parameter specifies the maximum width of information to be printed by debug-print. If the information takes more columns than the value of this parameter, it is truncated.

To show all the information, set #f to this parameter.

Macro: debug-funcall (proc arg …)

This macro prints the value of args right before calling proc and the result(s) of the call afterwards.

The output goes to the current trace port (see Common port operations).

The special reader syntax #?,expr is expanded into (debug-funcall expr). See Debugging, for the details.

Macro: debug-print-conditionally test expr
Macro: debug-funcall-conditionally test (proc arg …)

Works like debug-print and debug-funcall, but prints out the debug info ony when test evaluates to true.

These are functionally equivalent to the following code:

(if test
  (debug-print expr)

(if test
  (debug-funcall (proc arg …))
  (proc arg …))

The special reader syntax #??=test expr and #??,test expr are expanded into (debug-print-conditionally test expr) and (debug-funcall-conditionally test expr), respectively. See Debugging, for the details.

Function: debug-source-info obj

Retrieves source information attached to obj. The source information is returned as a list of source file name and an integer line number. If no source information is available in obj, #f is returned.

Function: source-code closure

Returns the source code of closure, if available. Otherwise, #f is returned.

Currently, only the code that’s directly read from Scheme source is available; if the Scheme code is precompiled, the source code isn’t saved. It may be changed in future.

Function: source-location procedure

Returns the location (a list of filename and line number) where procedure is defined, if available. Otherwise, #f is returned.

gosh> (use rfc.http)
gosh> (source-location http-get)
("/usr/share/gauche-0.9/0.9.5/lib/rfc/http.scm" 443)

If procedure is a subr or a precompiled closure, the filename may not be a complete pathname.

gosh> (source-location cons)
("liblist.scm" 46)
Function: disasm closure

Disassemble the compiled body of closure and print it. It may not be very useful unless you’re tracking a compiler bug, or trying to tune the program to its limit.

If you’re reading the disassembler output, keep in mind that the compiled code vector may have some dead code; they are produced by the jump optimization, but the compiler doesn’t bother to eliminate them.

Function: debug-label obj

This returns a string that is quasi-unique to an object obj. “Quasi-unique” means the label is unique to the obj— the same (eq?) objs returns the same string, and if two objs return different string they aren’t eq? to each other— until next GC occurs.

This is mostly for printing out anonymous objects that doesn’t have any other good way to distinguish each other. Note that uniqueness isn’t guaranteed across GCs, you shouldn’t use the returned value as the key to identify the objects.

6.25.2 Profiler API

These are the functions to control Gauche’s built-in profiler. See Using profiler for the explanation of the profiler.

Note that the profiler isn’t guaranteed to work correctly yet in multi-threaded program, since the interaction between setitimer and threads are platform-dependent.

Function: profiler-start

Starts the sampling profiler. If the profiler is already started, nothing is done.

Function: profiler-stop

Stop the sampling profiler, and save the sampled data into the internal structure. If there are already saved sampled data, the newly obtained data is added to it. If the profiler isn’t running, nothing is done.

Function: profiler-reset

Stop the profiler if it is running. Then discard the saved sampled data.

Function: profiler-show :key sort-by max-rows

Show the saved sampled data.

The keyword argument sort-by may be one of the symbols time, count, or time-per-call, to specify how the result should be sorted. The default is time.

The keyword argument max-rows specifies the max number of rows to be shown. If it is #f, all the data is shown.

Function: with-profiler thunk

A convenience procedure. Call thunk with the sampling profiler running, and show the result to the current output port afterwards. Returns value(s) thunk yields. The profiler is reset after the result is shown.

You can’t nest this construct; the innermost with-profiler will reset the profiler, invalidates any outer with-profiler.

Previous: , Up: Core library   [Contents][Index]

For Development HEAD DRAFTSearch (procedure/syntax/module):