print-function-meta-info

Arguments: func &key (src t) (ask t) terse full sort vars mixed profile

The :lldb module must be loaded to use this function. Evaluate

(require :lldb)

to ensure the :lldb module is loaded.

Returns 0 values after printing information about func for side-effect. func can be a function or closure object or a function name.

If terse is true then 80 columns should be sufficient for the output, otherwise up to 150 columns may be required for the output. Normally, output is restricted to one line per information item. Source forms, when available, are printed using a concise-print technique whereby various values of *print-length* and *print-level* are tried until the whole form fits on one line. However, if full is true, no such testing is done, and whole forms are printed, possibly on multiple lines.

Up to four kinds of information currently presented, depending on various options. These are described more fully described in Printing function meta data are related topics in debugging.htm.

• Source debug info: these are records which serve as Lisp breakpoints, and which provide information about what is currently being executed at any particular program counter location. There may be multiple source records with same pc locations. If other information is being printed with these records, then the first column always starts with "S" for "source record". Source debug information is not available in any code compiled with cl:compile, including code compiled with a call to cl:compile that is embedded in a file that is compiled with compile-file.
• Disassembler output: generally, each one or two line record shows a single instruction at a program-counter location. No character is ever printed in the first column of disassembler output.
• Variable transition information: each record represents a transfer of a variable's value to or from a location, either a register or a memory location. Each variable record is printed on a separate line that starts with "V" (for "variable transition").
• Census information: a census point is a pc location which is likely to be seen by the precise-gc, and the census point provides information about what locations on the stack are alive at that pc location. Each Census point is printed on its own line starting with "C" (for "census point").

If src is non-nil (the default) and if source-level-debug info is available for func it is used, otherwise the output is presented without source information. If func has been compiled with comp:save-source-level-debug-info-switch on but the fasl file has not been loaded with *load-source-debug-info* on, then source info will be searched using the following steps:

1. If the fasl file was compiled with *record-source-file-info* true, and if *load-source-file-info* was true when the fasl file was loaded, then the location of the fasl file is implied and is re-loaded with only source-debug-info requested.
2. If the source-file information was not recorded or loaded, but source-debug info was recorded (and not loaded), and if ask is non-nil (the default) then a prompt is given asking for the name of the file to load. Any string representing the file can be specified, e.g. "dir/file.fasl", "dir/file", "dir/file.cl", etc. If the fasl file associated with the given name exists it is loaded for source debug info and that info becomes available.
3. If ask is nil, source-debug info is silently unused.

Information is presented in an order most appropriate for the options given. Sorting can be by requested by source-record (i.e. :rec), by program-counter (i.e. :pc), or by source-position (i.e. :pos). If no options are specified for this function, and if source is available, then only source records will be shown in record order. If src is nil or source-debug-info is unavailable, or if either of mixed or vars is non-nil, then the presentation will be made in program-counter order.

If mixed is t then assembler code is presented in a manner similar to disassemble, but intermixed with any other information (in program-counter order).

If vars is t, then variable transitions are presented, interspersed with other information (in program-counter order).

If sort is :pc for any reason, census points are presented, in pc order.

The :profile keyword argument

If the profile argument is given and is either the name of a named-profile (see prof:save-named-profile), or a profile object (see prof:find-named-profile), or an integer corresponding to a profile outline sequence number (see prof:show-outline-profile which must have been called for an integer to be a meaningful value), then profile data is looked up for the function being disassembled (when an integer, the function that appears on that line of the profile outline). If such data is found, then the instructions or source forms printed with the function are annotated with the profiler hits for the specified profile. The default value for profile is nil, which causes no profile data to be searched for and/or annotated. The current profile can be specified using a profile argument of :current, which specifies the current-profile.

If an integer is specified as the value of profile and either there was no prior call to prof:show-outline-profile or the integer does not match any sequence number, an error is signaled.

When specifying a function by an integer sequence number, hits are the complete aggregate set of hits for the function, and not just the particular instance reported on that sequence line.

If the sequence number corresponds to a C or runsys function, an error will be signaled. If profile data is desired for such a function, cl:disassemble should be used instead.

If the mixed argument is also specified as true, meaning that mixed disassembler output is desired, then the profiler hits are annotated similarly to the disassemble command (but see the details of the Allegro CL implementation of cl:disassemble, described in the section Extensions to cl:make-package, cl:disassemble, cl:truename, cl:probe-file, cl:open, cl:apropos in implementation.htm).

If the mixed argument is not specified or is nil, then hits related to particular source forms are gathered, combined, and annotated on the source records that are grouped around those hits. If multiple source forms are apropos to the same program counter, then the first one is chosen and annotated.

Regardless of the value of mixed, when the profile argument specifies a profile, the number of matched/total hits is shown, and further addresses not seen in the function are printed in the same way they are printed by disassemble: if the addresses are within a symbol-trampoline, they are printed by the disassembler as they are at the end of disassemble output. If there are any addresses that are left over (i.e. not within the function and also not within a symbol-trampoline) they are listed at the end.

Profiling code is described in the runtime-analyzer.htm document.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.