1 /* 2 * Copyright (c) 2011, 2019, 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 public interface ThreadMXBean extends java.lang.management.ThreadMXBean { 42 /** 43 * Returns the total CPU time for each thread whose ID is 44 * in the input array {@code ids} in nanoseconds. 45 * The returned values are of nanoseconds precision but 46 * not necessarily nanoseconds accuracy. 47 * <p> 48 * This method is equivalent to calling the 49 * {@link ThreadMXBean#getThreadCpuTime(long)} 50 * method for each thread ID in the input array {@code ids} and setting the 51 * returned value in the corresponding element of the returned array. 52 * 53 * @param ids an array of thread IDs. 54 * @return an array of long values, each of which is the amount of CPU 55 * time the thread whose ID is in the corresponding element of the input 56 * array of IDs has used, 57 * if the thread of a specified ID exists, the thread is alive, 58 * and CPU time measurement is enabled; 59 * {@code -1} otherwise. 60 * 61 * @throws NullPointerException if {@code ids} is {@code null} 62 * @throws IllegalArgumentException if any element in the input array 63 * {@code ids} is {@code <=} {@code 0}. 64 * @throws UnsupportedOperationException if the Java 65 * virtual machine implementation does not support CPU time 66 * measurement. 67 * 68 * @see ThreadMXBean#getThreadCpuTime(long) 69 * @see #getThreadUserTime 70 * @see ThreadMXBean#isThreadCpuTimeSupported 71 * @see ThreadMXBean#isThreadCpuTimeEnabled 72 * @see ThreadMXBean#setThreadCpuTimeEnabled 73 */ getThreadCpuTime(long[] ids)74 public long[] getThreadCpuTime(long[] ids); 75 76 /** 77 * Returns the CPU time that each thread whose ID is in the input array 78 * {@code ids} has executed in user mode in nanoseconds. 79 * The returned values are of nanoseconds precision but 80 * not necessarily nanoseconds accuracy. 81 * <p> 82 * This method is equivalent to calling the 83 * {@link ThreadMXBean#getThreadUserTime(long)} 84 * method for each thread ID in the input array {@code ids} and setting the 85 * returned value in the corresponding element of the returned array. 86 * 87 * @param ids an array of thread IDs. 88 * @return an array of long values, each of which is the amount of user 89 * mode CPU time the thread whose ID is in the corresponding element of 90 * the input array of IDs has used, 91 * if the thread of a specified ID exists, the thread is alive, 92 * and CPU time measurement is enabled; 93 * {@code -1} otherwise. 94 * 95 * @throws NullPointerException if {@code ids} is {@code null} 96 * @throws IllegalArgumentException if any element in the input array 97 * {@code ids} is {@code <=} {@code 0}. 98 * @throws UnsupportedOperationException if the Java 99 * virtual machine implementation does not support CPU time 100 * measurement. 101 * 102 * @see ThreadMXBean#getThreadUserTime(long) 103 * @see #getThreadCpuTime 104 * @see ThreadMXBean#isThreadCpuTimeSupported 105 * @see ThreadMXBean#isThreadCpuTimeEnabled 106 * @see ThreadMXBean#setThreadCpuTimeEnabled 107 */ getThreadUserTime(long[] ids)108 public long[] getThreadUserTime(long[] ids); 109 110 /** 111 * Returns an approximation of the total amount of memory, in bytes, 112 * allocated in heap memory for the current thread. 113 * The returned value is an approximation because some Java virtual machine 114 * implementations may use object allocation mechanisms that result in a 115 * delay between the time an object is allocated and the time its size is 116 * recorded. 117 * 118 * <p> 119 * This is a convenience method for local management use and is 120 * equivalent to calling: 121 * <blockquote><pre> 122 * {@link #getThreadAllocatedBytes getThreadAllocatedBytes}(Thread.currentThread().getId()); 123 * </pre></blockquote> 124 * 125 * @return an approximation of the total memory allocated, in bytes, in 126 * heap memory for the current thread 127 * if thread memory allocation measurement is enabled; 128 * {@code -1} otherwise. 129 * 130 * @throws UnsupportedOperationException if the Java virtual 131 * machine implementation does not support thread memory allocation 132 * measurement. 133 * 134 * @see #isThreadAllocatedMemorySupported 135 * @see #isThreadAllocatedMemoryEnabled 136 * @see #setThreadAllocatedMemoryEnabled 137 * 138 * @since 13.0.6 139 */ getCurrentThreadAllocatedBytes()140 public default long getCurrentThreadAllocatedBytes() { 141 return getThreadAllocatedBytes(Thread.currentThread().getId()); 142 } 143 144 /** 145 * Returns an approximation of the total amount of memory, in bytes, 146 * allocated in heap memory for the thread with the specified ID. 147 * The returned value is an approximation because some Java virtual machine 148 * implementations may use object allocation mechanisms that result in a 149 * delay between the time an object is allocated and the time its size is 150 * recorded. 151 * <p> 152 * If the thread with the specified ID is not alive or does not exist, 153 * this method returns {@code -1}. If thread memory allocation measurement 154 * is disabled, this method returns {@code -1}. 155 * A thread is alive if it has been started and has not yet died. 156 * <p> 157 * If thread memory allocation measurement is enabled after the thread has 158 * started, the Java virtual machine implementation may choose any time up 159 * to and including the time that the capability is enabled as the point 160 * where thread memory allocation measurement starts. 161 * 162 * @param id the thread ID of a thread 163 * @return an approximation of the total memory allocated, in bytes, in 164 * heap memory for the thread with the specified ID 165 * if the thread with the specified ID exists, the thread is alive, 166 * and thread memory allocation measurement is enabled; 167 * {@code -1} otherwise. 168 * 169 * @throws IllegalArgumentException if {@code id} {@code <=} {@code 0}. 170 * @throws UnsupportedOperationException if the Java virtual 171 * machine implementation does not support thread memory allocation 172 * measurement. 173 * 174 * @see #isThreadAllocatedMemorySupported 175 * @see #isThreadAllocatedMemoryEnabled 176 * @see #setThreadAllocatedMemoryEnabled 177 */ getThreadAllocatedBytes(long id)178 public long getThreadAllocatedBytes(long id); 179 180 /** 181 * Returns an approximation of the total amount of memory, in bytes, 182 * allocated in heap memory for each thread whose ID is in the input 183 * array {@code ids}. 184 * The returned values are approximations because some Java virtual machine 185 * implementations may use object allocation mechanisms that result in a 186 * delay between the time an object is allocated and the time its size is 187 * recorded. 188 * <p> 189 * This method is equivalent to calling the 190 * {@link #getThreadAllocatedBytes(long)} 191 * method for each thread ID in the input array {@code ids} and setting the 192 * returned value in the corresponding element of the returned array. 193 * 194 * @param ids an array of thread IDs. 195 * @return an array of long values, each of which is an approximation of 196 * the total memory allocated, in bytes, in heap memory for the thread 197 * whose ID is in the corresponding element of the input array of IDs. 198 * 199 * @throws NullPointerException if {@code ids} is {@code null} 200 * @throws IllegalArgumentException if any element in the input array 201 * {@code ids} is {@code <=} {@code 0}. 202 * @throws UnsupportedOperationException if the Java virtual 203 * machine implementation does not support thread memory allocation 204 * measurement. 205 * 206 * @see #getThreadAllocatedBytes(long) 207 * @see #isThreadAllocatedMemorySupported 208 * @see #isThreadAllocatedMemoryEnabled 209 * @see #setThreadAllocatedMemoryEnabled 210 */ getThreadAllocatedBytes(long[] ids)211 public long[] getThreadAllocatedBytes(long[] ids); 212 213 /** 214 * Tests if the Java virtual machine implementation supports thread memory 215 * allocation measurement. 216 * 217 * @return 218 * {@code true} 219 * if the Java virtual machine implementation supports thread memory 220 * allocation measurement; 221 * {@code false} otherwise. 222 */ isThreadAllocatedMemorySupported()223 public boolean isThreadAllocatedMemorySupported(); 224 225 /** 226 * Tests if thread memory allocation measurement is enabled. 227 * 228 * @return {@code true} if thread memory allocation measurement is enabled; 229 * {@code false} otherwise. 230 * 231 * @throws UnsupportedOperationException if the Java virtual 232 * machine does not support thread memory allocation measurement. 233 * 234 * @see #isThreadAllocatedMemorySupported 235 */ isThreadAllocatedMemoryEnabled()236 public boolean isThreadAllocatedMemoryEnabled(); 237 238 /** 239 * Enables or disables thread memory allocation measurement. The default 240 * is platform dependent. 241 * 242 * @param enable {@code true} to enable; 243 * {@code false} to disable. 244 * 245 * @throws UnsupportedOperationException if the Java virtual 246 * machine does not support thread memory allocation measurement. 247 * 248 * @throws SecurityException if a security manager 249 * exists and the caller does not have 250 * ManagementPermission("control"). 251 * 252 * @see #isThreadAllocatedMemorySupported 253 */ setThreadAllocatedMemoryEnabled(boolean enable)254 public void setThreadAllocatedMemoryEnabled(boolean enable); 255 } 256