The HyperProf - hyperbolic profile browser for Java == Version 1.3 == 3 March 1997 Author: Vladimir Bulatov (V.Bulatov@dots.physics.orst.edu) This archive contains the distribution of the HyperProf. It allows you to view and analyze the execution profile of Java program, which shows exactly how much time your Java program spend and where. MAIN FEATURES HyperProf is written in Java language and should (in principle) run on all platforms supported by Java. It was tested with JDK 1.01, JDK-1.1 on Linux (where it was developed) and Windows 95. HyperProf includes hyperbolic browser of packages, classes and methods, which are called during execution of the profiled program. This browser visualizes global structure of the program and relationship between classes. INSTALLATION Unix installation. The provided Makefile will install HyperProf on your system. To use the Makefile, you MUST first edit it to match your directory structure. Change the values of $JAVA_DIR and the other two variables if necessary to point to where the actual Java binaries and classes are stored on your system. See the Makefile itself for more information. If you wish to do in-place installation, you should add 'classes' subdirectory to CLASSPATH enviroment variable. Windows 95 0) Be sure, that you have extracted files from this archive with long file names. 1) Copy contents of directory "classes" with all subdirectories to some place pointed by CLASSPATH variable (or add new path to CLASSPATH), or add path to "classes" to your CLASSPATH and do not copy anything. 2) Edit bin/HyperProf.bat to have correct full path to java executable and CLASSPATH in it pointing to correct location of HyperProf classes. 3) Copy bin/HyperProf.bat to some directory from your PATH variable. Mac installation. Here you are on your own at the moment. It shouldn't be a problem, but I am not too familiar with Mac to provide exact installation procedure. RUNNING HyperProfiler. To profile a program you should make profile information first. It can be obtained by running > java -prof [parameters] or > java -prof sun.applet.AppletViewer applet.html in case of profiling applets. After your program will finished normally (not with the help of Ctrl-C for example) there will be file java.prof in current directory. This file contatins all necessary information to investigate execution profile. There is simple program TestProfiler.java and corresponding java.prof in src directory. You can now run HyperProf typing > HyperProf java.prof MAIN WINDOW HyperProf's main window has 4 lists: Methods, Caller, Callee, Memory, which can be resized by mouse dragging boundary between them. This lists contain Methods: shows all methods of all classes which was called during execution of program. Each line contains: - time, spended in current method (in percent of total time or in milliseconds) - cumulative time - a total time spend in this method and all methods called by this method - number of calls of this method. - short name of this method. Caller: Lists all methods, which have called selected method. Each line contains: - total time spend in selected method from point of view of each caller. this time includes the time of all callee of the method. - cumulative time - sum of all times of all callers - number of calls of each caller. - name of caller Callee: Lists all method, which are called by selected method. Each line shows - time spend in the callee (including all its callee). - cumulative time - sum of all times of all callees - number of calls done by currently selected method to this callee - name of callee Memory: Lists memory used by program. Each line contains - number of bytes allocated for particular type of objects (absolute value or in percent of all allocated memory). - number of chunks by which this data was allocated. - short name of this data type. Selecting of one entry in methods list caused filling of Callee and Caller lists with correspontding callee and callers of selected method. Double click (or pressing key) in Callers or Callees list caused selection of corresponding method in Methods list. HYPERBOLIC BROWSER By selection of menu File|Show Graph, you can run Hyperbolic Browser. Simply speaking it represents all methods, classes and packages as tree. However to make possible to fit big amount of methods and classes (hundreds and thousands in relatively big program), it uses Poincare-disk model of hyperbolic plane. Hyperbolic plane has more space, than usual euclidean plane, and it is ideall place to put trees with big number of leafs. There are some not always trivial geometrical constructions behind this hyperbolic browser, however user is not expected to know anything about noneuclidean geometry and this knowledge is absolutelly not necessary to use browser. You can just drag tree by mouse in hyperplane and enjoy :) All tree is represented by 3 levels of nodes: packages (blue cyrcles), classes (green cyrcles), methods(pink cyrcles). All nodes are sorted by time and are placed clockwise starting from noon. Dragging node by mouse to center of Poincare disk caused considerable zooming in of visible size of this cyrcle with corresponding zooming out of nodes, which are going to boundary of disk. Dragging mouse with right button pressed caused rotation of all picture around the center. If your mouse dosn't have right button - use [META+mouse button] instead. Clicking by mouse over method's cyrcle caused drawing of bounds, which connect this method with its callers (yellow hyperlines) and callees (white hyperlines). The selection is reflected also in corresponding lists of main window. Clicking by mouse over class or package node causes drawing of all caller-callee bounds for methods from corresponding class or package. The status line in the bottom of the browser reflect name of and total time spend by node over which mouse is currently located. Root of the tree, which is located currently in the center of the disk represent special method with name '?.?', which I suppose represent in some sence calls done by java vitual machine. This method have no caller, no class, no package and I have decided to draw it as a root. Because of the fact, that this method has no callers, its time is negative, as far as time of several other methods. Don't worry about this. MENUS DESCRIPTION File|Load... - load new execution profile from disk, File|New Profiler - create new empty HyperProf window, (that alows comparision of different profiles without overhead of running separate java programm) File|Show Graph - creates hyperbolic browser File|Quit - ... Sort|by time - sort all entries by time spend there or by memory size. Sort|by name - sort all entries by name of it's Method or Class. Options|absolute numbers - write absolute time in milliseconds or amount of byte allocated Options|relative numbers - write percentage of time and memory relative to total memory spended by program or to total memory allocated KNOWN BUGS AND LIMITATIONS 1)In case of recursive function calls data, provided by java.prof may be incorrect or at least may be not treated correctly by the HyperProf. 2)java.prof file has several system entries, which appears as callers only, and therefore after subtracting the time of all callee from time spend in this method this methods will have negative time spend in them. It may be considered as a feature though, indicating that this method is high level system method. 3)The headers of lists are shifted to right in Windows 95 (Why?) 4) When boundary between lists is dragged by mouse, there is no visible trace of current position. This is Windows 95 JDK 1.02 limitation, which have forced me to remove this feature from Unix version too. 5) JDK 1.02 has broken profile output: all names of methods are truncated to 30 characters. Usually HyperProf will still work, however it is not guarantied. Better choice - use JDK-1.01 or JDK-1.1 6) The repainting speed of Hyperbolic browser is not great in case of relatively complex program. HISTORY 16 July 1996 Initial public release version 1.1 14 September 1996 version 1.2 - fixed some bugs: - JDK 1.02 profile format is supported - fixed parsing of names of array as arguments 3 March 1997 version 1.3 - JDK-1.1 support - JDK 1.1 profile format is supported - some minor improvements like gray background LICENSE This software is distributed for free including it's source code under terms of license included. If you like this software very much you can send me postcard or donations. My current address is: 1035 NW 26th street, Corvallis, OR, 97330, USA, (but check via e-mail first) Any comments and questions by e-mail are welcome too. You can also visit may home page http://www.physics.orst.edu/~bulatov/ to find news about HyperProf and much more. Happy profiling! V.Bulatov@dots.physics.orst.edu