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 --------