1 /* 2 * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.management; 27 28 import java.util.Map; 29 30 /** 31 * Platform-specific management interface for the thread system 32 * of the Java virtual machine. 33 * <p> 34 * This platform extension is only available to a thread 35 * implementation that supports this extension. 36 * 37 * @author Paul Hohensee 38 * @since 6u25 39 */ 40 41 @jdk.Supported 42 public interface ThreadMXBean extends java.lang.management.ThreadMXBean { 43 /** 44 * Returns the total CPU time for each thread whose ID is 45 * in the input array {@code ids} in nanoseconds. 46 * The returned values are of nanoseconds precision but 47 * not necessarily nanoseconds accuracy. 48 * <p> 49 * This method is equivalent to calling the 50 * {@link ThreadMXBean#getThreadCpuTime(long)} 51 * method for each thread ID in the input array {@code ids} and setting the 52 * returned value in the corresponding element of the returned array. 53 * 54 * @param ids an array of thread IDs. 55 * @return an array of long values, each of which is the amount of CPU 56 * time the thread whose ID is in the corresponding element of the input 57 * array of IDs has used, 58 * if the thread of a specified ID exists, the thread is alive, 59 * and CPU time measurement is enabled; 60 * {@code -1} otherwise. 61 * 62 * @throws NullPointerException if {@code ids} is {@code null} 63 * @throws IllegalArgumentException if any element in the input array 64 * {@code ids} is {@code <=} {@code 0}. 65 * @throws java.lang.UnsupportedOperationException if the Java 66 * virtual machine implementation does not support CPU time 67 * measurement. 68 * 69 * @see ThreadMXBean#getThreadCpuTime(long) 70 * @see #getThreadUserTime 71 * @see ThreadMXBean#isThreadCpuTimeSupported 72 * @see ThreadMXBean#isThreadCpuTimeEnabled 73 * @see ThreadMXBean#setThreadCpuTimeEnabled 74 */ 75 public long[] getThreadCpuTime(long[] ids); 76 77 /** 78 * Returns the CPU time that each thread whose ID is in the input array 79 * {@code ids} has executed in user mode in nanoseconds. 80 * The returned values are of nanoseconds precision but 81 * not necessarily nanoseconds accuracy. 82 * <p> 83 * This method is equivalent to calling the 84 * {@link ThreadMXBean#getThreadUserTime(long)} 85 * method for each thread ID in the input array {@code ids} and setting the 86 * returned value in the corresponding element of the returned array. 87 * 88 * @param ids an array of thread IDs. 89 * @return an array of long values, each of which is the amount of user 90 * mode CPU time the thread whose ID is in the corresponding element of 91 * the input array of IDs has used, 92 * if the thread of a specified ID exists, the thread is alive, 93 * and CPU time measurement is enabled; 94 * {@code -1} otherwise. 95 * 96 * @throws NullPointerException if {@code ids} is {@code null} 97 * @throws IllegalArgumentException if any element in the input array 98 * {@code ids} is {@code <=} {@code 0}. 99 * @throws java.lang.UnsupportedOperationException if the Java 100 * virtual machine implementation does not support CPU time 101 * measurement. 102 * 103 * @see ThreadMXBean#getThreadUserTime(long) 104 * @see #getThreadCpuTime 105 * @see ThreadMXBean#isThreadCpuTimeSupported 106 * @see ThreadMXBean#isThreadCpuTimeEnabled 107 * @see ThreadMXBean#setThreadCpuTimeEnabled 108 */ 109 public long[] getThreadUserTime(long[] ids); 110 111 /** 112 * Returns an approximation of the total amount of memory, in bytes, 113 * allocated in heap memory for the thread of the specified ID. 114 * The returned value is an approximation because some Java virtual machine 115 * implementations may use object allocation mechanisms that result in a 116 * delay between the time an object is allocated and the time its size is 117 * recorded. 118 * <p> 119 * If the thread of the specified ID is not alive or does not exist, 120 * this method returns {@code -1}. If thread memory allocation measurement 121 * is disabled, this method returns {@code -1}. 122 * A thread is alive if it has been started and has not yet died. 123 * <p> 124 * If thread memory allocation measurement is enabled after the thread has 125 * started, the Java virtual machine implementation may choose any time up 126 * to and including the time that the capability is enabled as the point 127 * where thread memory allocation measurement starts. 128 * 129 * @param id the thread ID of a thread 130 * @return an approximation of the total memory allocated, in bytes, in 131 * heap memory for a thread of the specified ID 132 * if the thread of the specified ID exists, the thread is alive, 133 * and thread memory allocation measurement is enabled; 134 * {@code -1} otherwise. 135 * 136 * @throws IllegalArgumentException if {@code id} {@code <=} {@code 0}. 137 * @throws java.lang.UnsupportedOperationException if the Java virtual 138 * machine implementation does not support thread memory allocation 139 * measurement. 140 * 141 * @see #isThreadAllocatedMemorySupported 142 * @see #isThreadAllocatedMemoryEnabled 143 * @see #setThreadAllocatedMemoryEnabled 144 */ 145 public long getThreadAllocatedBytes(long id); 146 147 /** 148 * Returns an approximation of the total amount of memory, in bytes, 149 * allocated in heap memory for each thread whose ID is in the input 150 * array {@code ids}. 151 * The returned values are approximations because some Java virtual machine 152 * implementations may use object allocation mechanisms that result in a 153 * delay between the time an object is allocated and the time its size is 154 * recorded. 155 * <p> 156 * This method is equivalent to calling the 157 * {@link #getThreadAllocatedBytes(long)} 158 * method for each thread ID in the input array {@code ids} and setting the 159 * returned value in the corresponding element of the returned array. 160 * 161 * @param ids an array of thread IDs. 162 * @return an array of long values, each of which is an approximation of 163 * the total memory allocated, in bytes, in heap memory for the thread 164 * whose ID is in the corresponding element of the input array of IDs. 165 * 166 * @throws NullPointerException if {@code ids} is {@code null} 167 * @throws IllegalArgumentException if any element in the input array 168 * {@code ids} is {@code <=} {@code 0}. 169 * @throws java.lang.UnsupportedOperationException if the Java virtual 170 * machine implementation does not support thread memory allocation 171 * measurement. 172 * 173 * @see #getThreadAllocatedBytes(long) 174 * @see #isThreadAllocatedMemorySupported 175 * @see #isThreadAllocatedMemoryEnabled 176 * @see #setThreadAllocatedMemoryEnabled 177 */ 178 public long[] getThreadAllocatedBytes(long[] ids); 179 180 /** 181 * Tests if the Java virtual machine implementation supports thread memory 182 * allocation measurement. 183 * 184 * @return 185 * {@code true} 186 * if the Java virtual machine implementation supports thread memory 187 * allocation measurement; 188 * {@code false} otherwise. 189 */ 190 public boolean isThreadAllocatedMemorySupported(); 191 192 /** 193 * Tests if thread memory allocation measurement is enabled. 194 * 195 * @return {@code true} if thread memory allocation measurement is enabled; 196 * {@code false} otherwise. 197 * 198 * @throws java.lang.UnsupportedOperationException if the Java virtual 199 * machine does not support thread memory allocation measurement. 200 * 201 * @see #isThreadAllocatedMemorySupported 202 */ 203 public boolean isThreadAllocatedMemoryEnabled(); 204 205 /** 206 * Enables or disables thread memory allocation measurement. The default 207 * is platform dependent. 208 * 209 * @param enable {@code true} to enable; 210 * {@code false} to disable. 211 * 212 * @throws java.lang.UnsupportedOperationException if the Java virtual 213 * machine does not support thread memory allocation measurement. 214 * 215 * @throws java.lang.SecurityException if a security manager 216 * exists and the caller does not have 217 * ManagementPermission("control"). 218 * 219 * @see #isThreadAllocatedMemorySupported 220 */ 221 public void setThreadAllocatedMemoryEnabled(boolean enable); 222 }