Best Tools for JAVA/Best Tools for JAVA.iso/JAVA_ALL/JAVA_UTL/HYPERPRO/README

Text File | 1996-09-14 | 8.7 KB | 251 lines

The HyperProf - hyperbolic profile browser for Java

== Version 1.2
== 14 September 1996


Author: Vladimir Bulatov ([e-mail])

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
at least in 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 <name of your program> [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 <Enter> 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.

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




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:
84 Harslock Drive, London SE2 9UU (but check via e-mail first)

Any comments and questions by e-mail are welcome too.

You can also visit may home page http://pc153.mt.ic.ac.uk/Bulatov/
to find news about HyperProf and much more.

Happy profiling!

[e-mail]