C.D.Lane
Revised: July 1984
GRAPHCALLS
GRAPHCALLS is an extended graphical interface to the Interlisp CALLS function.
It is to CALLS what BROWSER is to SHOW PATHS in MASTERSCOPE. It allows fast
graphing of the calling hierarchy of both interpreted and compiled code,
whether or not the source is avaliable (see the CALLS function in the Interlisp
manual), allowing examination of both user and system functions. The functions
do not have to be analyzed by MASTERSCOPE first.
Additionally, buttoning a function on the graph brings up a menu of operations
that can be done with the function, such as editing, inspecting, further
graphing etc.
(GRAPHCALLS function filter depth flags format)
Graphs the calling hierarchy of function. Terminal nodes on the graph (those
who call no other functions or are undefined) are printed in a bold version of
the graph's font indicating that they cannot be graphed further.
The filter argument is a function to apply to the functions when building the
graph to test their eligibility to appear on the graph. The filter can be any
defined function; the default is not to filter. Interesting filters are:
WHEREIS Limits the tree to only functions the user as has loaded and
prunes out Interlisp functions and SYSLOADed files. Quite
useful.
FGETD Limits the tree to only functions that are actually defined.
Thus if you are perusing the tree for BITBLT and don't have and
are not interested in the color code, FGETD will remove all of
the undefined color bitmap functions.
EXPRP Limits the tree to interpreted functions. Useful for graphing
functions in the development stage.
CCODEP Limits the tree to compiled functions.
NO\ Keeps low level functions starting with \ (i.e. \OUTDATE) off
of the graph. Useful for getting an overview of system
functions and when advising system functions (as \'ed functions
probably should not be advised).
The calling hierarchy is graphed to depth grandchildren (defaults to 1). A
depth of 2 would pick up greatgrandchildren etc.
The flags argument can be one or more of:
INVERT Sets up a dynamic graph to visually track a running program
2
(see Dynamic Graphing below).
COUNT Sets up a dynamic graph to count function calls in running
program (see Dynamic Graphing below).
EDIT Passes T to SHOWGRAPH's alloweditflg, allowing editing of the
graph from a right button menu.
TOP Passes T to SHOWGRAPH's topjustiflyflg.
The format argument is passed on to LAYOUTGRAPH in GRAPHER and can be any
format specification (eg. LATTICE, VERTICAL, FAST, REVERSE etc.) In the
forest format multiple instances of a function appear on the graph after every
calling function and a boxed node indicates the function appears elsewhere on
the graph, possibly graphed further. In the lattice format each function gets
placed on the graph only once (particularly useful for for the Dynamic Graphing
described below), and boxed nodes indicate recursive functions calls.
Graph Menus
The menu that pops up when you left button a function on the graph contains the
following items (NOTE: The subitems are implemented as menu SUBITEMS and are
also avaliable by pressing the middle button over the item.):
?= Print the arguments to the function, if avaliable.
FNTYP Print the function's FNTYP.
WHERE Do a WHEREIS on the function.
EDIT Calls the editor on the function if avaliable for editing.
TYPEIN BKSYSBUF's the name of the function into the typein buffer.
BREAK Applies BREAK to the function. Its subitems are
BREAKIN Breaks the function only in the context of a
particular calling function. In lattice
format, if the function has more than one
function calling it on the graph, the user is
prompted to indicate the caller in which to
break the function.
UNBREAKIN Undoes BREAKIN.
UNBREAK Applies UNBREAK to the function.
TRACE Applies TRACE to the function.
TRACEIN Traces the function only when called from
inside a particular function, like BREAKIN
3
above. Use UNBREAKIN to remove the trace, or
else UNBREAK on the window menu.
CCODE Calls INSPECTCODE on the function if it is compiled code.
GRAPH Calls GRAPHCALLS to make a new graph starting with function,
inherits the original graph's filter, flags and format.
FRAME Inspect the local, free and global variables of the function.
These are the last three lists of the CALLS function placed
into INSPECT windows. Its subitems are
>FRAME Like FRAME but for all of the functions on the
sub-tree starting at the selected node and only
for FREEVARS and GLOBALVARS.
<FRAME Like >FRAME but for all of the functions above
the function in the graph, i.e. the FREEVARS
and GLOBALVARS in the function's scope.
Buttoning the graph outside a node give you a menu with these options:
HardCopy Does a HARDCOPYW on the window with the graph.
UNBREAK Does an (UNBREAK), unbreaking all broken functions.
RESET Resets the counters for the COUNT option and redisplays graph.
Dynamic Graphing
When the INVERT or COUNT flags are given, GRAPHCALLS will advise all of the
functions on the graph (in the context of their parent) to invert their
corresponding node on the graph (as well as delay some to allow it to be seen)
and/or follow each function name by a count of the number of times it has been
executed. In invert mode, a node remains inverted as long as control is inside
its corresponding function and it returns to normal when the function is
exited. The lattice format is best when using the invert feature. Closing the
graph window UNADVISEs the functions on the graph.
A simple example of this is (GRAPHCALLS 'DATE NIL NIL 'INVERT) and then
evaluate (DATE).
GRAPHCALLS will not graph or advise any function in the list NOADVISEFNS when
an advise flag is used. Functions which are unsafe to advise should be added
to this list.
CAVEAT PROGRAMMER! This feature must be used with caution. As a rule, one
should not do this to system (Interlisp) functions, but only one's own, use
WHEREIS as a filter for this. Advising system code indiscriminately will
probably crash the machine unrecoverablely.
4
You can, at some risk, interactively BREAK and EDIT etc. a function on the
graph while the code is executing. Also, creating subgraphs of advised graphs
will show the generated advice functions not the original functions called, as
will creating new graphs of functions in advised graphs. You can create
advised graphs of functions already graphed normally on the screen.
Command Window
The function (GRAPHCALLSW) puts up a command window with menus that will
interactively set up calls to GRAPHCALLS. The menus let you set the Invert,
Count and Edit flags as well as select from common filters and formats as well
as set the depth of the graph. You can also change the amount of delay used in
the advised functions when doing Dynamic Graphing. If you specify an advised
graph (Invert or Count) and don't specify a WHEREIS filter, you will be asked
to confirm with the mouse for your own protection.
More than one item on the filter and flags menus can be selected at a time.
Buttoning a selected item on these menus unselects it.
The command menu contains the following:
Function Sets the current function which the command graphs by prompting
for a name in the prompt window.
Include Adds files or functions to the list of items to allow on the
graph, see the Include/Exclude algorithm below.
Exclude Adds files of functions to the list of items disallowed on the
graph, see the Include/Exclude algorithm below.
Clear Clears all of the settings on the command window to the
defaults. Also clears the Include/Exclude lists.
GRAPH Graphs the function by calling GRAPHCALLS with the selected
options.
Include and Exclude allow fine tuning of the filter function. If the function
passes the filter, then the following are tried until one determines whether or
not the function will be on the graph
1. If a set of functions has been explicitly excluded, and the function
is a member of this set, it will NOT appear on the graph.
2. If a set of functions has been explicitly included, and the function
is a member of this set, it WILL appear on the graph.
3. If a set of files has been explicitly excluded, and the function is
in one of those files, it will NOT appear on the graph.
4. If a set of files has been explicitly included, and the function is
not in one of those files, it will NOT appear on the graph.
5
5. The function WILL appear on the graph.
When the command window is open, middle buttoning a node on any GRAPHCALLS
graph will bring up a menu of commands relating to command window and graphs.
The menu contains:
EXCLUDE Adds the function to the exclude functions list of the command
window. This is the only way to exclude system functions which
get added to the SYSTEM file exclusion list.
The command window can also be obtained via the background menu.
Notes:
Function call graphs are constructed using breadth first search but GRAPHER
lays out graphs using a depth first approach so that in some cases functions
are expanded in a different place on the graph than one would expect.
GRAPHCALLS sysloads GRAPHER if it is not already loaded.
In dynamic graphs, variables caused by advising show up in the frame
inspections.
Subgraphs made from graphs created from the Command Window will inherit the
current graph filter, which may be for a completely different context.
The font for the graph (initially GACHA 8) can be changed by setting the global
CALLSFONT.
The delay in advised graphs can be changed by setting CALLSDELAY which is reset
by the command window when using the delay menu.