XEROX GRAPHCALLS 2 4 1 GRAPHCALLS 1 4 By: Christopher Lane (LANE@SUMEX-AIM.ARPA) Requires: GRAPHER (WHEREIS & HELPSYS optional) 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 available (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 FLAS FORMAT STREAM SEARCHFN NAMEFN) [Function] Graphs the calling hierarchy of FUNCTION. Terminal nodes on the graph (those which 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: (( FIELDS ( SIDESFLG T) IDS 14 DATE \UNPACKDATE DAYTIME IMOD \DTSCAN \ISDST? \OUTDATE \LISPERROR NTH SUBSTRING NCHARS ALLOCSTRING \RPLRIGHT RPLSTRING FONTS 2 (GACHA 8) (GACHA 8 BRR) NODES ( (1 DATE (11 . 76) 1 NIL NIL (2 7 ) NIL) (2 \UNPACKDATE (80 . 111) 1 NIL NIL (3 4 5 6 ) (1 )) (3 DAYTIME (157 . 129) 1 NIL NIL NIL (2 )) (4 IMOD (150 . 117) 2 NIL NIL NIL (2 )) (5 \DTSCAN (157 . 105) 2 NIL NIL NIL (2 )) (6 \ISDST? (157 . 93) 1 NIL NIL NIL (2 )) (7 \OUTDATE (73 . 41) 1 NIL NIL (8 9 10 11 12 13 14 ) (1 )) (8 \LISPERROR (150 . 77) 1 NIL NIL NIL (7 )) (9 NTH (132 . 65) 2 NIL NIL NIL (7 )) (10 SUBSTRING (147 . 53) 1 NIL NIL NIL (7 )) (11 NCHARS (140 . 41) 1 NIL NIL NIL (7 )) (12 ALLOCSTRING (152 . 29) 1 NIL NIL NIL (7 )) (13 \RPLRIGHT (147 . 17) 2 NIL NIL NIL (7 )) (14 RPLSTRING (147 . 5) 1 NIL NIL NIL (7 )) )) 0 0) FILTER is an optional 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 include: 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 should probably not be advised). The calling hierarchy is graphed to depth children (the argument is optional and defaults to 2). A depth of 3 would pick up greatgrandchildren etc. The flags argument is optional and can be one or more of: INVERT Sets up a dynamic graph to visually track a running program (see Dynamic Graphing below). COUNT Sets up a dynamic graph to count function calls in running program (see Dynamic Graphing below). SHAPE Shapes the resulting graph window to fit the graph exactly. TOP Passes T to SHOWGRAPH's topjustiflyflg. EDIT Passes T to SHOWGRAPH's alloweditflg, allowing editing of the graph from a right button menu. The FORMAT argument is optional and is passed on to LAYOUTGRAPH in GRAPHER and can be any format specification (eg. LATTICE, VERTICAL, FAST, REVERSE etc.) If a format is not specified, the value of GRAPHCALLSDEFAULTFORMAT (initially HORIZONTAL COMPACT REVERSE/DAUGHTERS) is used. 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. The STREAM argument is an optional image stream to display the graph in. The graph's FILTER, FLAGS and FORMAT will be saved on the stream. The SEARCHFN argument is an optional function to use to generate the children of a given node. It should return a list whose first item is a list of the children, the other items in the list are ignored currently. Using this feature, it is possible to graph things other than functions. To graph what files load other files, supply a search function of (LAMBDA (FILE) (LIST (FILECOMSLST FILE 'FILES))) and a file name for the function argument. The NAMEFN argument is an optional function to use to generate the node labels on the graph. 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 available by pressing the middle button over the item.): ?= Print the arguments to the function, if available. HELP Calls HELPSYS on the function. FNTYP Print the function's FNTYP. WHERE Do a WHEREIS (with FILES = T) on the function. EDIT Calls the editor on the function if available 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 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. Reuses the same window for speed. 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 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: UNBREAK Does an (UNBREAK), unbreaking all broken functions. RESET Resets the counters for the COUNT option and redisplays the 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. An 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 functions, but only one's own, use WHEREIS as a filter for this. Advising system code indiscriminately will probably crash the machine unrecoverablely. 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  ?ow:ogn>tNtuomY-mon~n6jo[omݶw[;plvlVݷ0000χo0{:M':qFu?Tw8;0~,mmm[ovlm0~mml7nvovmu0zmmmovovms0χ;m+qf7Ōvاxػ0o00 @0 @0$b@@@0$b@@@0o>>$b\8q@@90l٘ٳ"bDDĉP@@D"0lٳ"B|qQ@@>0lٳ"B@ Q@@d 0l٘ٳ!BDD!@@D"03!B8q @~:f0 @0 @0 @0 @0 G 0  @D`0Ątp KDGp0$ HHLHD$H 0 ȂHHHG⏐q 0 $HHHD  0$ dHHHHD! 0ttp HFDp 0 @0 @0 @0 @0 |AC0Ȁ B AC0ȀDq! KB .@q~C0(!#" ŒMB1"@"C0Ȁ!!> H|!>@PC`0Ȁ!! H@! @P2C0Ȁ(##" H@ 1"@ "C0Dq K@@ qC0  @0  @0 @0 @0 x?@ 0! ! @ 0@#"xtq .@Ps0@$H" !1@Pd`0@'Ð"!!@$q0@$ "!!@$ 0!$H!!1Ad0#P xxtq.Ap0  @ 0  @0 @0 @00 ?HĀ`00 0 HĀ`0> ( Hĸqg 0;a $?E(ĉ 0 $ E( 0 " E(0; ! B 03 ?Bq 0 @0 @00000000000000000000000000000 0@0@00000000000000000000000000000000!0b 0 0" 0" 0" 0" 0!000000 (GRAPHCALLSW REBUILD?) [Function] 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 by prompting for a name in a prompt window attached to the command 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 their 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. The function WILL appear on the graph. The format menu contains two items that are not passed on to GRAPHER but are used to select alternate namefn arguments: ArgList Supplies a namefn to GRAPHCALLS that will print the function and its arguments (using SMARTARGLIST) as the node label. WhereIs Supplies a namefn to GRAPHCALLS that will print the function followed by the file(s) found by doing WHEREIS (with FILES = T) if any . 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 BackgroundMenu. Subsequent calls to GRAPHCALLSW (either directly or via the BackgroundMenu item) will reuse the old command window if there is one. If this window is damaged, and redisplay doesn't help, then setting the REBUILD? to T will build a new command window from scratch. 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. The font for the graph (initially GACHA 8) can be changed by setting the global GRAPHCALLSFONT (which is a FONTCLASS). The delay in advised graphs can be changed by setting CALLSDELAY which is reset by the command window when using the delay menu.(LIST ((PAGE NIL (FOLIOINFO (ARABIC) STARTINGPAGE# 1) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM) FORMATINFO (ARABIC)) (174 36 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))))) (H ($$ ( (H (H( ( ( (1 (8(8D PAGEHEADING RUNNINGHEAD TERMINAL MODERN MODERN MODERN m_(DEFAULTFONT 1 (GACHA 10) (GACHA 8) (TERMINAL 8) (IMPRESS300 GACHA NIL) (IMPRESS240 GACHA NIL))  HELVETICA MODERN MODERN MODERNLOGO     HRULE.GETFNMODERN   HRULE.GETFNMODERN   HRULE.GETFNMODERN    HRULE.GETFNMODERN   HRULE.GETFNMODERN  , /  8  GRAPHOBJ.GETFNMODERN e(<\c>+bX1+R 6!2=>3 "!_x}I  #EN"wL BMOBJ.GETFN3MODERN   *fopnF~*zy59RwD z