1 /*
   2  * Copyright (c) 2003, 2005, Oracle and/or its affiliates. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  *   - Redistributions of source code must retain the above copyright
   9  *     notice, this list of conditions and the following disclaimer.
  10  *
  11  *   - Redistributions in binary form must reproduce the above copyright
  12  *     notice, this list of conditions and the following disclaimer in the
  13  *     documentation and/or other materials provided with the distribution.
  14  *
  15  *   - Neither the name of Oracle nor the names of its
  16  *     contributors may be used to endorse or promote products derived
  17  *     from this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  20  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  21  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  22  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31 
  32 README
  33 ------
  34 
  35 Design and Implementation:
  36 
  37     * The Tracker Class (Tracker.java & hprof_tracker.c)
  38         It was added to the sun.tools.hprof.Tracker in JDK 5.0 FCS, then
  39         moved to a package that didn't cause classload errors due to
  40         the security manager not liking the sun.* package name.
  41         5091195 detected that this class needs to be in com.sun.demo.jvmti.hprof.
  42         The BCI code will call these static methods, which will in turn
  43         (if engaged) call matching native methods in the hprof library,
  44         with the additional current Thread argument (Thread.currentThread()).
  45         Doing the currentThread call on the Java side was necessary due
  46         to the difficulty of getting the current thread while inside one
  47         of these Tracker native methods.  This class lives in rt.jar.
  48 
  49     * Byte Code Instrumentation (BCI)
  50         Using the ClassFileLoadHook feature and a C language
  51         implementation of a byte code injection transformer, the following
  52         bytecodes get injections:
  53             - On entry to the java.lang.Object <init> method, 
  54               a invokestatic call to
  55                 Tracker.ObjectInit(this);
  56               is injected. 
  57             - On any newarray type opcode, immediately following it, 
  58               the array object is duplicated on the stack and an
  59               invokestatic call to
  60                 Tracker.NewArray(obj);
  61               is injected. 
  62             - On entry to all methods, a invokestatic call to 
  63                 Tracker.CallSite(cnum,mnum);
  64               is injected. The hprof agent can map the two integers
  65               (cnum,mnum) to a method in a class. This is the BCI based
  66               "method entry" event.
  67             - On return from any method (any return opcode),
  68               a invokestatic call to
  69                 Tracker.ReturnSite(cnum,mnum);
  70               is injected.  
  71         All classes found via ClassFileLoadHook are injected with the
  72         exception of some system class methods "<init>" and "finalize" 
  73         whose length is 1 and system class methods with name "<clinit>",
  74         and also java.lang.Thread.currentThread() which is used in the
  75         class Tracker (preventing nasty recursion issue).
  76         System classes are currently defined as any class seen by the
  77         ClassFileLoadHook prior to VM_INIT. This does mean that
  78         objects created in the system classes inside <clinit> might not
  79         get tracked initially.
  80         See the java_crw_demo source and documentation for more info.
  81         The injections are based on what the hprof options
  82         are requesting, e.g. if heap=sites or heap=all is requested, the
  83         newarray and Object.<init> method injections happen.
  84         If cpu=times is requested, all methods get their entries and
  85         returns tracked. Options like cpu=samples or monitor=y
  86         do not require BCI.
  87 
  88     * BCI Allocation Tags (hprof_tag.c)
  89         The current jlong tag being used on allocated objects
  90         is an ObjectIndex, or an index into the object table inside
  91         the hprof code. Depending on whether heap=sites or heap=dump 
  92         was asked for, these ObjectIndex's might represent unique
  93         objects, or unique allocation sites for types of objects.
  94         The heap=dump option requires considerable more space
  95         due to the one jobject per ObjectIndex mapping.
  96 
  97     * BCI Performance
  98         The cpu=times seems to have the most negative affect on
  99         performance, this could be improved by not having the 
 100         Tracker class methods call native code directly, but accumulate
 101         the data in a file or memory somehow and letting it buffer down
 102         to the agent. The cpu=samples is probably a better way to
 103         measure cpu usage, varying the interval as needed.
 104         The heap=dump seems to use memory like crazy, but that's 
 105         partially the way it has always been. 
 106 
 107     * Sources in the JDK workspace
 108         The sources and Makefiles live in:
 109                 src/share/classes/com/sun/demo/jvmti/hprof/*
 110                 src/share/demo/jvmti/hprof/*
 111                 src/share/demo/jvmti/java_crw_demo/*
 112                 src/solaris/demo/jvmti/hprof/*
 113                 src/windows/demo/jvmti/hprof/*
 114                 make/java/java_hprof_demo/*
 115                 make/java/java_crw_demo/*
 116    
 117 --------