Showing the changes to java/pkg/java/lang/management/ThreadMXBean.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,806 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 2003, 2008, 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 java.lang.management; | ||
| 27 | |||
| 28 | import java.util.Map; | ||
| 29 | |||
| 30 | /** | ||
| 31 | * The management interface for the thread system of | ||
| 32 | * the Java virtual machine. | ||
| 33 | * | ||
| 34 | * <p> A Java virtual machine has a single instance of the implementation | ||
| 35 | * class of this interface. This instance implementing this interface is | ||
| 36 | * an <a href="ManagementFactory.html#MXBean">MXBean</a> | ||
| 37 | * that can be obtained by calling | ||
| 38 | * the {@link ManagementFactory#getThreadMXBean} method or | ||
| 39 | * from the {@link ManagementFactory#getPlatformMBeanServer | ||
| 40 | * platform <tt>MBeanServer</tt>} method. | ||
| 41 | * | ||
| 42 | * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for | ||
| 43 | * the thread system within an MBeanServer is: | ||
| 44 | * <blockquote> | ||
| 45 | * {@link ManagementFactory#THREAD_MXBEAN_NAME | ||
| 46 | * <tt>java.lang:type=Threading</tt>} | ||
| 47 | * </blockquote> | ||
| 48 | * | ||
| 49 | * It can be obtained by calling the | ||
| 50 | * {@link PlatformManagedObject#getObjectName} method. | ||
| 51 | * | ||
| 52 | * <h4>Thread ID</h4> | ||
| 53 | * Thread ID is a positive long value returned by calling the | ||
| 54 | * {@link java.lang.Thread#getId} method for a thread. | ||
| 55 | * The thread ID is unique during its lifetime. When a thread | ||
| 56 | * is terminated, this thread ID may be reused. | ||
| 57 | * | ||
| 58 | * <p> Some methods in this interface take a thread ID or an array | ||
| 59 | * of thread IDs as the input parameter and return per-thread information. | ||
| 60 | * | ||
| 61 | * <h4>Thread CPU time</h4> | ||
| 62 | * A Java virtual machine implementation may support measuring | ||
| 63 | * the CPU time for the current thread, for any thread, or for no threads. | ||
| 64 | * | ||
| 65 | * <p> | ||
| 66 | * The {@link #isThreadCpuTimeSupported} method can be used to determine | ||
| 67 | * if a Java virtual machine supports measuring of the CPU time for any | ||
| 68 | * thread. The {@link #isCurrentThreadCpuTimeSupported} method can | ||
| 69 | * be used to determine if a Java virtual machine supports measuring of | ||
| 70 | * the CPU time for the current thread. | ||
| 71 | * A Java virtual machine implementation that supports CPU time measurement | ||
| 72 | * for any thread will also support that for the current thread. | ||
| 73 | * | ||
| 74 | * <p> The CPU time provided by this interface has nanosecond precision | ||
| 75 | * but not necessarily nanosecond accuracy. | ||
| 76 | * | ||
| 77 | * <p> | ||
| 78 | * A Java virtual machine may disable CPU time measurement | ||
| 79 | * by default. | ||
| 80 | * The {@link #isThreadCpuTimeEnabled} and {@link #setThreadCpuTimeEnabled} | ||
| 81 | * methods can be used to test if CPU time measurement is enabled | ||
| 82 | * and to enable/disable this support respectively. | ||
| 83 | * Enabling thread CPU measurement could be expensive in some | ||
| 84 | * Java virtual machine implementations. | ||
| 85 | * | ||
| 86 | * <h4>Thread Contention Monitoring</h4> | ||
| 87 | * Some Java virtual machines may support thread contention monitoring. | ||
| 88 | * When thread contention monitoring is enabled, the accumulated elapsed | ||
| 89 | * time that the thread has blocked for synchronization or waited for | ||
| 90 | * notification will be collected and returned in the | ||
| 91 | * <a href="ThreadInfo.html#SyncStats"><tt>ThreadInfo</tt></a> object. | ||
| 92 | * <p> | ||
| 93 | * The {@link #isThreadContentionMonitoringSupported} method can be used to | ||
| 94 | * determine if a Java virtual machine supports thread contention monitoring. | ||
| 95 | * The thread contention monitoring is disabled by default. The | ||
| 96 | * {@link #setThreadContentionMonitoringEnabled} method can be used to enable | ||
| 97 | * thread contention monitoring. | ||
| 98 | * | ||
| 99 | * <h4>Synchronization Information and Deadlock Detection</h4> | ||
| 100 | * Some Java virtual machines may support monitoring of | ||
| 101 | * {@linkplain #isObjectMonitorUsageSupported object monitor usage} and | ||
| 102 | * {@linkplain #isSynchronizerUsageSupported ownable synchronizer usage}. | ||
| 103 | * The {@link #getThreadInfo(long[], boolean, boolean)} and | ||
| 104 | * {@link #dumpAllThreads} methods can be used to obtain the thread stack trace | ||
| 105 | * and synchronization information including which | ||
| 106 | * {@linkplain LockInfo <i>lock</i>} a thread is blocked to | ||
| 107 | * acquire or waiting on and which locks the thread currently owns. | ||
| 108 | * <p> | ||
| 109 | * The <tt>ThreadMXBean</tt> interface provides the | ||
| 110 | * {@link #findMonitorDeadlockedThreads} and | ||
| 111 | * {@link #findDeadlockedThreads} methods to find deadlocks in | ||
| 112 | * the running application. | ||
| 113 | * | ||
| 114 | * @see ManagementFactory#getPlatformMXBeans(Class) | ||
| 115 | * @see <a href="../../../javax/management/package-summary.html"> | ||
| 116 | * JMX Specification.</a> | ||
| 117 | * @see <a href="package-summary.html#examples"> | ||
| 118 | * Ways to Access MXBeans</a> | ||
| 119 | * | ||
| 120 | * @author Mandy Chung | ||
| 121 | * @since 1.5 | ||
| 122 | */ | ||
| 123 | |||
| 124 | public interface ThreadMXBean extends PlatformManagedObject { | ||
| 125 | /** | ||
| 126 | * Returns the current number of live threads including both | ||
| 127 | * daemon and non-daemon threads. | ||
| 128 | * | ||
| 129 | * @return the current number of live threads. | ||
| 130 | */ | ||
| 131 | public int getThreadCount(); | ||
| 132 | |||
| 133 | /** | ||
| 134 | * Returns the peak live thread count since the Java virtual machine | ||
| 135 | * started or peak was reset. | ||
| 136 | * | ||
| 137 | * @return the peak live thread count. | ||
| 138 | */ | ||
| 139 | public int getPeakThreadCount(); | ||
| 140 | |||
| 141 | /** | ||
| 142 | * Returns the total number of threads created and also started | ||
| 143 | * since the Java virtual machine started. | ||
| 144 | * | ||
| 145 | * @return the total number of threads started. | ||
| 146 | */ | ||
| 147 | public long getTotalStartedThreadCount(); | ||
| 148 | |||
| 149 | /** | ||
| 150 | * Returns the current number of live daemon threads. | ||
| 151 | * | ||
| 152 | * @return the current number of live daemon threads. | ||
| 153 | */ | ||
| 154 | public int getDaemonThreadCount(); | ||
| 155 | |||
| 156 | /** | ||
| 157 | * Returns all live thread IDs. | ||
| 158 | * Some threads included in the returned array | ||
| 159 | * may have been terminated when this method returns. | ||
| 160 | * | ||
| 161 | * @return an array of <tt>long</tt>, each is a thread ID. | ||
| 162 | * | ||
| 163 | * @throws java.lang.SecurityException if a security manager | ||
| 164 | * exists and the caller does not have | ||
| 165 | * ManagementPermission("monitor"). | ||
| 166 | */ | ||
| 167 | public long[] getAllThreadIds(); | ||
| 168 | |||
| 169 | /** | ||
| 170 | * Returns the thread info for a thread of the specified | ||
| 171 | * <tt>id</tt> with no stack trace. | ||
| 172 | * This method is equivalent to calling: | ||
| 173 | * <blockquote> | ||
| 174 | * {@link #getThreadInfo(long, int) getThreadInfo(id, 0);} | ||
| 175 | * </blockquote> | ||
| 176 | * | ||
| 177 | * <p> | ||
| 178 | * This method returns a <tt>ThreadInfo</tt> object representing | ||
| 179 | * the thread information for the thread of the specified ID. | ||
| 180 | * The stack trace, locked monitors, and locked synchronizers | ||
| 181 | * in the returned <tt>ThreadInfo</tt> object will | ||
| 182 | * be empty. | ||
| 183 | * | ||
| 184 | * If a thread of the given ID is not alive or does not exist, | ||
| 185 | * this method will return <tt>null</tt>. A thread is alive if | ||
| 186 | * it has been started and has not yet died. | ||
| 187 | * | ||
| 188 | * <p> | ||
| 189 | * <b>MBeanServer access</b>:<br> | ||
| 190 | * The mapped type of <tt>ThreadInfo</tt> is | ||
| 191 | * <tt>CompositeData</tt> with attributes as specified in the | ||
| 192 | * {@link ThreadInfo#from ThreadInfo.from} method. | ||
| 193 | * | ||
| 194 | * @param id the thread ID of the thread. Must be positive. | ||
| 195 | * | ||
| 196 | * @return a {@link ThreadInfo} object for the thread of the given ID | ||
| 197 | * with no stack trace, no locked monitor and no synchronizer info; | ||
| 198 | * <tt>null</tt> if the thread of the given ID is not alive or | ||
| 199 | * it does not exist. | ||
| 200 | * | ||
| 201 | * @throws IllegalArgumentException if <tt>id <= 0</tt>. | ||
| 202 | * @throws java.lang.SecurityException if a security manager | ||
| 203 | * exists and the caller does not have | ||
| 204 | * ManagementPermission("monitor"). | ||
| 205 | */ | ||
| 206 | public ThreadInfo getThreadInfo(long id); | ||
| 207 | |||
| 208 | /** | ||
| 209 | * Returns the thread info for each thread | ||
| 210 | * whose ID is in the input array <tt>ids</tt> with no stack trace. | ||
| 211 | * This method is equivalent to calling: | ||
| 212 | * <blockquote><pre> | ||
| 213 | * {@link #getThreadInfo(long[], int) getThreadInfo}(ids, 0); | ||
| 214 | * </pre></blockquote> | ||
| 215 | * | ||
| 216 | * <p> | ||
| 217 | * This method returns an array of the <tt>ThreadInfo</tt> objects. | ||
| 218 | * The stack trace, locked monitors, and locked synchronizers | ||
| 219 | * in each <tt>ThreadInfo</tt> object will be empty. | ||
| 220 | * | ||
| 221 | * If a thread of a given ID is not alive or does not exist, | ||
| 222 | * the corresponding element in the returned array will | ||
| 223 | * contain <tt>null</tt>. A thread is alive if | ||
| 224 | * it has been started and has not yet died. | ||
| 225 | * | ||
| 226 | * <p> | ||
| 227 | * <b>MBeanServer access</b>:<br> | ||
| 228 | * The mapped type of <tt>ThreadInfo</tt> is | ||
| 229 | * <tt>CompositeData</tt> with attributes as specified in the | ||
| 230 | * {@link ThreadInfo#from ThreadInfo.from} method. | ||
| 231 | * | ||
| 232 | * @param ids an array of thread IDs. | ||
| 233 | * @return an array of the {@link ThreadInfo} objects, each containing | ||
| 234 | * information about a thread whose ID is in the corresponding | ||
| 235 | * element of the input array of IDs | ||
| 236 | * with no stack trace, no locked monitor and no synchronizer info. | ||
| 237 | * | ||
| 238 | * @throws IllegalArgumentException if any element in the input array | ||
| 239 | * <tt>ids</tt> is <tt><= 0</tt>. | ||
| 240 | * @throws java.lang.SecurityException if a security manager | ||
| 241 | * exists and the caller does not have | ||
| 242 | * ManagementPermission("monitor"). | ||
| 243 | */ | ||
| 244 | public ThreadInfo[] getThreadInfo(long[] ids); | ||
| 245 | |||
| 246 | /** | ||
| 247 | * Returns a thread info for a thread of the specified <tt>id</tt>, | ||
| 248 | * with stack trace of a specified number of stack trace elements. | ||
| 249 | * The <tt>maxDepth</tt> parameter indicates the maximum number of | ||
| 250 | * {@link StackTraceElement} to be retrieved from the stack trace. | ||
| 251 | * If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of | ||
| 252 | * the thread will be dumped. | ||
| 253 | * If <tt>maxDepth == 0</tt>, no stack trace of the thread | ||
| 254 | * will be dumped. | ||
| 255 | * This method does not obtain the locked monitors and locked | ||
| 256 | * synchronizers of the thread. | ||
| 257 | * <p> | ||
| 258 | * When the Java virtual machine has no stack trace information | ||
| 259 | * about a thread or <tt>maxDepth == 0</tt>, | ||
| 260 | * the stack trace in the | ||
| 261 | * <tt>ThreadInfo</tt> object will be an empty array of | ||
| 262 | * <tt>StackTraceElement</tt>. | ||
| 263 | * | ||
| 264 | * <p> | ||
| 265 | * If a thread of the given ID is not alive or does not exist, | ||
| 266 | * this method will return <tt>null</tt>. A thread is alive if | ||
| 267 | * it has been started and has not yet died. | ||
| 268 | * | ||
| 269 | * <p> | ||
| 270 | * <b>MBeanServer access</b>:<br> | ||
| 271 | * The mapped type of <tt>ThreadInfo</tt> is | ||
| 272 | * <tt>CompositeData</tt> with attributes as specified in the | ||
| 273 | * {@link ThreadInfo#from ThreadInfo.from} method. | ||
| 274 | * | ||
| 275 | * @param id the thread ID of the thread. Must be positive. | ||
| 276 | * @param maxDepth the maximum number of entries in the stack trace | ||
| 277 | * to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request | ||
| 278 | * the entire stack to be dumped. | ||
| 279 | * | ||
| 280 | * @return a {@link ThreadInfo} of the thread of the given ID | ||
| 281 | * with no locked monitor and synchronizer info. | ||
| 282 | * <tt>null</tt> if the thread of the given ID is not alive or | ||
| 283 | * it does not exist. | ||
| 284 | * | ||
| 285 | * @throws IllegalArgumentException if <tt>id <= 0</tt>. | ||
| 286 | * @throws IllegalArgumentException if <tt>maxDepth is negative</tt>. | ||
| 287 | * @throws java.lang.SecurityException if a security manager | ||
| 288 | * exists and the caller does not have | ||
| 289 | * ManagementPermission("monitor"). | ||
| 290 | * | ||
| 291 | */ | ||
| 292 | public ThreadInfo getThreadInfo(long id, int maxDepth); | ||
| 293 | |||
| 294 | /** | ||
| 295 | * Returns the thread info for each thread | ||
| 296 | * whose ID is in the input array <tt>ids</tt>, | ||
| 297 | * with stack trace of a specified number of stack trace elements. | ||
| 298 | * The <tt>maxDepth</tt> parameter indicates the maximum number of | ||
| 299 | * {@link StackTraceElement} to be retrieved from the stack trace. | ||
| 300 | * If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of | ||
| 301 | * the thread will be dumped. | ||
| 302 | * If <tt>maxDepth == 0</tt>, no stack trace of the thread | ||
| 303 | * will be dumped. | ||
| 304 | * This method does not obtain the locked monitors and locked | ||
| 305 | * synchronizers of the threads. | ||
| 306 | * <p> | ||
| 307 | * When the Java virtual machine has no stack trace information | ||
| 308 | * about a thread or <tt>maxDepth == 0</tt>, | ||
| 309 | * the stack trace in the | ||
| 310 | * <tt>ThreadInfo</tt> object will be an empty array of | ||
| 311 | * <tt>StackTraceElement</tt>. | ||
| 312 | * <p> | ||
| 313 | * This method returns an array of the <tt>ThreadInfo</tt> objects, | ||
| 314 | * each is the thread information about the thread with the same index | ||
| 315 | * as in the <tt>ids</tt> array. | ||
| 316 | * If a thread of the given ID is not alive or does not exist, | ||
| 317 | * <tt>null</tt> will be set in the corresponding element | ||
| 318 | * in the returned array. A thread is alive if | ||
| 319 | * it has been started and has not yet died. | ||
| 320 | * | ||
| 321 | * <p> | ||
| 322 | * <b>MBeanServer access</b>:<br> | ||
| 323 | * The mapped type of <tt>ThreadInfo</tt> is | ||
| 324 | * <tt>CompositeData</tt> with attributes as specified in the | ||
| 325 | * {@link ThreadInfo#from ThreadInfo.from} method. | ||
| 326 | * | ||
| 327 | * @param ids an array of thread IDs | ||
| 328 | * @param maxDepth the maximum number of entries in the stack trace | ||
| 329 | * to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request | ||
| 330 | * the entire stack to be dumped. | ||
| 331 | * | ||
| 332 | * @return an array of the {@link ThreadInfo} objects, each containing | ||
| 333 | * information about a thread whose ID is in the corresponding | ||
| 334 | * element of the input array of IDs with no locked monitor and | ||
| 335 | * synchronizer info. | ||
| 336 | * | ||
| 337 | * @throws IllegalArgumentException if <tt>maxDepth is negative</tt>. | ||
| 338 | * @throws IllegalArgumentException if any element in the input array | ||
| 339 | * <tt>ids</tt> is <tt><= 0</tt>. | ||
| 340 | * @throws java.lang.SecurityException if a security manager | ||
| 341 | * exists and the caller does not have | ||
| 342 | * ManagementPermission("monitor"). | ||
| 343 | * | ||
| 344 | */ | ||
| 345 | public ThreadInfo[] getThreadInfo(long[] ids, int maxDepth); | ||
| 346 | |||
| 347 | /** | ||
| 348 | * Tests if the Java virtual machine supports thread contention monitoring. | ||
| 349 | * | ||
| 350 | * @return | ||
| 351 | * <tt>true</tt> | ||
| 352 | * if the Java virtual machine supports thread contention monitoring; | ||
| 353 | * <tt>false</tt> otherwise. | ||
| 354 | */ | ||
| 355 | public boolean isThreadContentionMonitoringSupported(); | ||
| 356 | |||
| 357 | /** | ||
| 358 | * Tests if thread contention monitoring is enabled. | ||
| 359 | * | ||
| 360 | * @return <tt>true</tt> if thread contention monitoring is enabled; | ||
| 361 | * <tt>false</tt> otherwise. | ||
| 362 | * | ||
| 363 | * @throws java.lang.UnsupportedOperationException if the Java virtual | ||
| 364 | * machine does not support thread contention monitoring. | ||
| 365 | * | ||
| 366 | * @see #isThreadContentionMonitoringSupported | ||
| 367 | */ | ||
| 368 | public boolean isThreadContentionMonitoringEnabled(); | ||
| 369 | |||
| 370 | /** | ||
| 371 | * Enables or disables thread contention monitoring. | ||
| 372 | * Thread contention monitoring is disabled by default. | ||
| 373 | * | ||
| 374 | * @param enable <tt>true</tt> to enable; | ||
| 375 | * <tt>false</tt> to disable. | ||
| 376 | * | ||
| 377 | * @throws java.lang.UnsupportedOperationException if the Java | ||
| 378 | * virtual machine does not support thread contention monitoring. | ||
| 379 | * | ||
| 380 | * @throws java.lang.SecurityException if a security manager | ||
| 381 | * exists and the caller does not have | ||
| 382 | * ManagementPermission("control"). | ||
| 383 | * | ||
| 384 | * @see #isThreadContentionMonitoringSupported | ||
| 385 | */ | ||
| 386 | public void setThreadContentionMonitoringEnabled(boolean enable); | ||
| 387 | |||
| 388 | /** | ||
| 389 | * Returns the total CPU time for the current thread in nanoseconds. | ||
| 390 | * The returned value is of nanoseconds precision but | ||
| 391 | * not necessarily nanoseconds accuracy. | ||
| 392 | * If the implementation distinguishes between user mode time and system | ||
| 393 | * mode time, the returned CPU time is the amount of time that | ||
| 394 | * the current thread has executed in user mode or system mode. | ||
| 395 | * | ||
| 396 | * <p> | ||
| 397 | * This is a convenient method for local management use and is | ||
| 398 | * equivalent to calling: | ||
| 399 | * <blockquote><pre> | ||
| 400 | * {@link #getThreadCpuTime getThreadCpuTime}(Thread.currentThread().getId()); | ||
| 401 | * </pre></blockquote> | ||
| 402 | * | ||
| 403 | * @return the total CPU time for the current thread if CPU time | ||
| 404 | * measurement is enabled; <tt>-1</tt> otherwise. | ||
| 405 | * | ||
| 406 | * @throws java.lang.UnsupportedOperationException if the Java | ||
| 407 | * virtual machine does not support CPU time measurement for | ||
| 408 | * the current thread. | ||
| 409 | * | ||
| 410 | * @see #getCurrentThreadUserTime | ||
| 411 | * @see #isCurrentThreadCpuTimeSupported | ||
| 412 | * @see #isThreadCpuTimeEnabled | ||
| 413 | * @see #setThreadCpuTimeEnabled | ||
| 414 | */ | ||
| 415 | public long getCurrentThreadCpuTime(); | ||
| 416 | |||
| 417 | /** | ||
| 418 | * Returns the CPU time that the current thread has executed | ||
| 419 | * in user mode in nanoseconds. | ||
| 420 | * The returned value is of nanoseconds precision but | ||
| 421 | * not necessarily nanoseconds accuracy. | ||
| 422 | * | ||
| 423 | * <p> | ||
| 424 | * This is a convenient method for local management use and is | ||
| 425 | * equivalent to calling: | ||
| 426 | * <blockquote><pre> | ||
| 427 | * {@link #getThreadUserTime getThreadUserTime}(Thread.currentThread().getId()); | ||
| 428 | * </pre></blockquote> | ||
| 429 | * | ||
| 430 | * @return the user-level CPU time for the current thread if CPU time | ||
| 431 | * measurement is enabled; <tt>-1</tt> otherwise. | ||
| 432 | * | ||
| 433 | * @throws java.lang.UnsupportedOperationException if the Java | ||
| 434 | * virtual machine does not support CPU time measurement for | ||
| 435 | * the current thread. | ||
| 436 | * | ||
| 437 | * @see #getCurrentThreadCpuTime | ||
| 438 | * @see #isCurrentThreadCpuTimeSupported | ||
| 439 | * @see #isThreadCpuTimeEnabled | ||
| 440 | * @see #setThreadCpuTimeEnabled | ||
| 441 | */ | ||
| 442 | public long getCurrentThreadUserTime(); | ||
| 443 | |||
| 444 | /** | ||
| 445 | * Returns the total CPU time for a thread of the specified ID in nanoseconds. | ||
| 446 | * The returned value is of nanoseconds precision but | ||
| 447 | * not necessarily nanoseconds accuracy. | ||
| 448 | * If the implementation distinguishes between user mode time and system | ||
| 449 | * mode time, the returned CPU time is the amount of time that | ||
| 450 | * the thread has executed in user mode or system mode. | ||
| 451 | * | ||
| 452 | * <p> | ||
| 453 | * If the thread of the specified ID is not alive or does not exist, | ||
| 454 | * this method returns <tt>-1</tt>. If CPU time measurement | ||
| 455 | * is disabled, this method returns <tt>-1</tt>. | ||
| 456 | * A thread is alive if it has been started and has not yet died. | ||
| 457 | * <p> | ||
| 458 | * If CPU time measurement is enabled after the thread has started, | ||
| 459 | * the Java virtual machine implementation may choose any time up to | ||
| 460 | * and including the time that the capability is enabled as the point | ||
| 461 | * where CPU time measurement starts. | ||
| 462 | * | ||
| 463 | * @param id the thread ID of a thread | ||
| 464 | * @return the total CPU time for a thread of the specified ID | ||
| 465 | * if the thread of the specified ID exists, the thread is alive, | ||
| 466 | * and CPU time measurement is enabled; | ||
| 467 | * <tt>-1</tt> otherwise. | ||
| 468 | * | ||
| 469 | * @throws IllegalArgumentException if <tt>id <= 0 </tt>. | ||
| 470 | * @throws java.lang.UnsupportedOperationException if the Java | ||
| 471 | * virtual machine does not support CPU time measurement for | ||
| 472 | * other threads. | ||
| 473 | * | ||
| 474 | * @see #getThreadUserTime | ||
| 475 | * @see #isThreadCpuTimeSupported | ||
| 476 | * @see #isThreadCpuTimeEnabled | ||
| 477 | * @see #setThreadCpuTimeEnabled | ||
| 478 | */ | ||
| 479 | public long getThreadCpuTime(long id); | ||
| 480 | |||
| 481 | /** | ||
| 482 | * Returns the CPU time that a thread of the specified ID | ||
| 483 | * has executed in user mode in nanoseconds. | ||
| 484 | * The returned value is of nanoseconds precision but | ||
| 485 | * not necessarily nanoseconds accuracy. | ||
| 486 | * | ||
| 487 | * <p> | ||
| 488 | * If the thread of the specified ID is not alive or does not exist, | ||
| 489 | * this method returns <tt>-1</tt>. If CPU time measurement | ||
| 490 | * is disabled, this method returns <tt>-1</tt>. | ||
| 491 | * A thread is alive if it has been started and has not yet died. | ||
| 492 | * <p> | ||
| 493 | * If CPU time measurement is enabled after the thread has started, | ||
| 494 | * the Java virtual machine implementation may choose any time up to | ||
| 495 | * and including the time that the capability is enabled as the point | ||
| 496 | * where CPU time measurement starts. | ||
| 497 | * | ||
| 498 | * @param id the thread ID of a thread | ||
| 499 | * @return the user-level CPU time for a thread of the specified ID | ||
| 500 | * if the thread of the specified ID exists, the thread is alive, | ||
| 501 | * and CPU time measurement is enabled; | ||
| 502 | * <tt>-1</tt> otherwise. | ||
| 503 | * | ||
| 504 | * @throws IllegalArgumentException if <tt>id <= 0 </tt>. | ||
| 505 | * @throws java.lang.UnsupportedOperationException if the Java | ||
| 506 | * virtual machine does not support CPU time measurement for | ||
| 507 | * other threads. | ||
| 508 | * | ||
| 509 | * @see #getThreadCpuTime | ||
| 510 | * @see #isThreadCpuTimeSupported | ||
| 511 | * @see #isThreadCpuTimeEnabled | ||
| 512 | * @see #setThreadCpuTimeEnabled | ||
| 513 | */ | ||
| 514 | public long getThreadUserTime(long id); | ||
| 515 | |||
| 516 | /** | ||
| 517 | * Tests if the Java virtual machine implementation supports CPU time | ||
| 518 | * measurement for any thread. | ||
| 519 | * A Java virtual machine implementation that supports CPU time | ||
| 520 | * measurement for any thread will also support CPU time | ||
| 521 | * measurement for the current thread. | ||
| 522 | * | ||
| 523 | * @return | ||
| 524 | * <tt>true</tt> | ||
| 525 | * if the Java virtual machine supports CPU time | ||
| 526 | * measurement for any thread; | ||
| 527 | * <tt>false</tt> otherwise. | ||
| 528 | */ | ||
| 529 | public boolean isThreadCpuTimeSupported(); | ||
| 530 | |||
| 531 | /** | ||
| 532 | * Tests if the Java virtual machine supports CPU time | ||
| 533 | * measurement for the current thread. | ||
| 534 | * This method returns <tt>true</tt> if {@link #isThreadCpuTimeSupported} | ||
| 535 | * returns <tt>true</tt>. | ||
| 536 | * | ||
| 537 | * @return | ||
| 538 | * <tt>true</tt> | ||
| 539 | * if the Java virtual machine supports CPU time | ||
| 540 | * measurement for current thread; | ||
| 541 | * <tt>false</tt> otherwise. | ||
| 542 | */ | ||
| 543 | public boolean isCurrentThreadCpuTimeSupported(); | ||
| 544 | |||
| 545 | /** | ||
| 546 | * Tests if thread CPU time measurement is enabled. | ||
| 547 | * | ||
| 548 | * @return <tt>true</tt> if thread CPU time measurement is enabled; | ||
| 549 | * <tt>false</tt> otherwise. | ||
| 550 | * | ||
| 551 | * @throws java.lang.UnsupportedOperationException if the Java virtual | ||
| 552 | * machine does not support CPU time measurement for other threads | ||
| 553 | * nor for the current thread. | ||
| 554 | * | ||
| 555 | * @see #isThreadCpuTimeSupported | ||
| 556 | * @see #isCurrentThreadCpuTimeSupported | ||
| 557 | */ | ||
| 558 | public boolean isThreadCpuTimeEnabled(); | ||
| 559 | |||
| 560 | /** | ||
| 561 | * Enables or disables thread CPU time measurement. The default | ||
| 562 | * is platform dependent. | ||
| 563 | * | ||
| 564 | * @param enable <tt>true</tt> to enable; | ||
| 565 | * <tt>false</tt> to disable. | ||
| 566 | * | ||
| 567 | * @throws java.lang.UnsupportedOperationException if the Java | ||
| 568 | * virtual machine does not support CPU time measurement for | ||
| 569 | * any threads nor for the current thread. | ||
| 570 | * | ||
| 571 | * @throws java.lang.SecurityException if a security manager | ||
| 572 | * exists and the caller does not have | ||
| 573 | * ManagementPermission("control"). | ||
| 574 | * | ||
| 575 | * @see #isThreadCpuTimeSupported | ||
| 576 | * @see #isCurrentThreadCpuTimeSupported | ||
| 577 | */ | ||
| 578 | public void setThreadCpuTimeEnabled(boolean enable); | ||
| 579 | |||
| 580 | /** | ||
| 581 | * Finds cycles of threads that are in deadlock waiting to acquire | ||
| 582 | * object monitors. That is, threads that are blocked waiting to enter a | ||
| 583 | * synchronization block or waiting to reenter a synchronization block | ||
| 584 | * after an {@link Object#wait Object.wait} call, | ||
| 585 | * where each thread owns one monitor while | ||
| 586 | * trying to obtain another monitor already held by another thread | ||
| 587 | * in a cycle. | ||
| 588 | * <p> | ||
| 589 | * More formally, a thread is <em>monitor deadlocked</em> if it is | ||
| 590 | * part of a cycle in the relation "is waiting for an object monitor | ||
| 591 | * owned by". In the simplest case, thread A is blocked waiting | ||
| 592 | * for a monitor owned by thread B, and thread B is blocked waiting | ||
| 593 | * for a monitor owned by thread A. | ||
| 594 | * <p> | ||
| 595 | * This method is designed for troubleshooting use, but not for | ||
| 596 | * synchronization control. It might be an expensive operation. | ||
| 597 | * <p> | ||
| 598 | * This method finds deadlocks involving only object monitors. | ||
| 599 | * To find deadlocks involving both object monitors and | ||
| 600 | * <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>, | ||
| 601 | * the {@link #findDeadlockedThreads findDeadlockedThreads} method | ||
| 602 | * should be used. | ||
| 603 | * | ||
| 604 | * @return an array of IDs of the threads that are monitor | ||
| 605 | * deadlocked, if any; <tt>null</tt> otherwise. | ||
| 606 | * | ||
| 607 | * @throws java.lang.SecurityException if a security manager | ||
| 608 | * exists and the caller does not have | ||
| 609 | * ManagementPermission("monitor"). | ||
| 610 | * | ||
| 611 | * @see #findDeadlockedThreads | ||
| 612 | */ | ||
| 613 | public long[] findMonitorDeadlockedThreads(); | ||
| 614 | |||
| 615 | /** | ||
| 616 | * Resets the peak thread count to the current number of | ||
| 617 | * live threads. | ||
| 618 | * | ||
| 619 | * @throws java.lang.SecurityException if a security manager | ||
| 620 | * exists and the caller does not have | ||
| 621 | * ManagementPermission("control"). | ||
| 622 | * | ||
| 623 | * @see #getPeakThreadCount | ||
| 624 | * @see #getThreadCount | ||
| 625 | */ | ||
| 626 | public void resetPeakThreadCount(); | ||
| 627 | |||
| 628 | /** | ||
| 629 | * Finds cycles of threads that are in deadlock waiting to acquire | ||
| 630 | * object monitors or | ||
| 631 | * <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>. | ||
| 632 | * | ||
| 633 | * Threads are <em>deadlocked</em> in a cycle waiting for a lock of | ||
| 634 | * these two types if each thread owns one lock while | ||
| 635 | * trying to acquire another lock already held | ||
| 636 | * by another thread in the cycle. | ||
| 637 | * <p> | ||
| 638 | * This method is designed for troubleshooting use, but not for | ||
| 639 | * synchronization control. It might be an expensive operation. | ||
| 640 | * | ||
| 641 | * @return an array of IDs of the threads that are | ||
| 642 | * deadlocked waiting for object monitors or ownable synchronizers, if any; | ||
| 643 | * <tt>null</tt> otherwise. | ||
| 644 | * | ||
| 645 | * @throws java.lang.SecurityException if a security manager | ||
| 646 | * exists and the caller does not have | ||
| 647 | * ManagementPermission("monitor"). | ||
| 648 | * @throws java.lang.UnsupportedOperationException if the Java virtual | ||
| 649 | * machine does not support monitoriing of ownable synchronizer usage. | ||
| 650 | * | ||
| 651 | * @see #isSynchronizerUsageSupported | ||
| 652 | * @see #findMonitorDeadlockedThreads | ||
| 653 | * @since 1.6 | ||
| 654 | */ | ||
| 655 | public long[] findDeadlockedThreads(); | ||
| 656 | |||
| 657 | /** | ||
| 658 | * Tests if the Java virtual machine supports monitoring of | ||
| 659 | * object monitor usage. | ||
| 660 | * | ||
| 661 | * @return | ||
| 662 | * <tt>true</tt> | ||
| 663 | * if the Java virtual machine supports monitoring of | ||
| 664 | * object monitor usage; | ||
| 665 | * <tt>false</tt> otherwise. | ||
| 666 | * | ||
| 667 | * @see #dumpAllThreads | ||
| 668 | * @since 1.6 | ||
| 669 | */ | ||
| 670 | public boolean isObjectMonitorUsageSupported(); | ||
| 671 | |||
| 672 | /** | ||
| 673 | * Tests if the Java virtual machine supports monitoring of | ||
| 674 | * <a href="LockInfo.html#OwnableSynchronizer"> | ||
| 675 | * ownable synchronizer</a> usage. | ||
| 676 | * | ||
| 677 | * @return | ||
| 678 | * <tt>true</tt> | ||
| 679 | * if the Java virtual machine supports monitoring of ownable | ||
| 680 | * synchronizer usage; | ||
| 681 | * <tt>false</tt> otherwise. | ||
| 682 | * | ||
| 683 | * @see #dumpAllThreads | ||
| 684 | * @since 1.6 | ||
| 685 | */ | ||
| 686 | public boolean isSynchronizerUsageSupported(); | ||
| 687 | |||
| 688 | /** | ||
| 689 | * Returns the thread info for each thread | ||
| 690 | * whose ID is in the input array <tt>ids</tt>, with stack trace | ||
| 691 | * and synchronization information. | ||
| 692 | * | ||
| 693 | * <p> | ||
| 694 | * This method obtains a snapshot of the thread information | ||
| 695 | * for each thread including: | ||
| 696 | * <ul> | ||
| 697 | * <li>the entire stack trace,</li> | ||
| 698 | * <li>the object monitors currently locked by the thread | ||
| 699 | * if <tt>lockedMonitors</tt> is <tt>true</tt>, and</li> | ||
| 700 | * <li>the <a href="LockInfo.html#OwnableSynchronizer"> | ||
| 701 | * ownable synchronizers</a> currently locked by the thread | ||
| 702 | * if <tt>lockedSynchronizers</tt> is <tt>true</tt>.</li> | ||
| 703 | * </ul> | ||
| 704 | * <p> | ||
| 705 | * This method returns an array of the <tt>ThreadInfo</tt> objects, | ||
| 706 | * each is the thread information about the thread with the same index | ||
| 707 | * as in the <tt>ids</tt> array. | ||
| 708 | * If a thread of the given ID is not alive or does not exist, | ||
| 709 | * <tt>null</tt> will be set in the corresponding element | ||
| 710 | * in the returned array. A thread is alive if | ||
| 711 | * it has been started and has not yet died. | ||
| 712 | * <p> | ||
| 713 | * If a thread does not lock any object monitor or <tt>lockedMonitors</tt> | ||
| 714 | * is <tt>false</tt>, the returned <tt>ThreadInfo</tt> object will have an | ||
| 715 | * empty <tt>MonitorInfo</tt> array. Similarly, if a thread does not | ||
| 716 | * lock any synchronizer or <tt>lockedSynchronizers</tt> is <tt>false</tt>, | ||
| 717 | * the returned <tt>ThreadInfo</tt> object | ||
| 718 | * will have an empty <tt>LockInfo</tt> array. | ||
| 719 | * | ||
| 720 | * <p> | ||
| 721 | * When both <tt>lockedMonitors</tt> and <tt>lockedSynchronizers</tt> | ||
| 722 | * parameters are <tt>false</tt>, it is equivalent to calling: | ||
| 723 | * <blockquote><pre> | ||
| 724 | * {@link #getThreadInfo(long[], int) getThreadInfo(ids, Integer.MAX_VALUE)} | ||
| 725 | * </pre></blockquote> | ||
| 726 | * | ||
| 727 | * <p> | ||
| 728 | * This method is designed for troubleshooting use, but not for | ||
| 729 | * synchronization control. It might be an expensive operation. | ||
| 730 | * | ||
| 731 | * <p> | ||
| 732 | * <b>MBeanServer access</b>:<br> | ||
| 733 | * The mapped type of <tt>ThreadInfo</tt> is | ||
| 734 | * <tt>CompositeData</tt> with attributes as specified in the | ||
| 735 | * {@link ThreadInfo#from ThreadInfo.from} method. | ||
| 736 | * | ||
| 737 | * @param ids an array of thread IDs. | ||
| 738 | * @param lockedMonitors if <tt>true</tt>, retrieves all locked monitors. | ||
| 739 | * @param lockedSynchronizers if <tt>true</tt>, retrieves all locked | ||
| 740 | * ownable synchronizers. | ||
| 741 | * | ||
| 742 | * @return an array of the {@link ThreadInfo} objects, each containing | ||
| 743 | * information about a thread whose ID is in the corresponding | ||
| 744 | * element of the input array of IDs. | ||
| 745 | * | ||
| 746 | * @throws java.lang.SecurityException if a security manager | ||
| 747 | * exists and the caller does not have | ||
| 748 | * ManagementPermission("monitor"). | ||
| 749 | * @throws java.lang.UnsupportedOperationException | ||
| 750 | * <ul> | ||
| 751 | * <li>if <tt>lockedMonitors</tt> is <tt>true</tt> but | ||
| 752 | * the Java virtual machine does not support monitoring | ||
| 753 | * of {@linkplain #isObjectMonitorUsageSupported | ||
| 754 | * object monitor usage}; or</li> | ||
| 755 | * <li>if <tt>lockedSynchronizers</tt> is <tt>true</tt> but | ||
| 756 | * the Java virtual machine does not support monitoring | ||
| 757 | * of {@linkplain #isSynchronizerUsageSupported | ||
| 758 | * ownable synchronizer usage}.</li> | ||
| 759 | * </ul> | ||
| 760 | * | ||
| 761 | * @see #isObjectMonitorUsageSupported | ||
| 762 | * @see #isSynchronizerUsageSupported | ||
| 763 | * | ||
| 764 | * @since 1.6 | ||
| 765 | */ | ||
| 766 | public ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers); | ||
| 767 | |||
| 768 | /** | ||
| 769 | * Returns the thread info for all live threads with stack trace | ||
| 770 | * and synchronization information. | ||
| 771 | * Some threads included in the returned array | ||
| 772 | * may have been terminated when this method returns. | ||
| 773 | * | ||
| 774 | * <p> | ||
| 775 | * This method returns an array of {@link ThreadInfo} objects | ||
| 776 | * as specified in the {@link #getThreadInfo(long[], boolean, boolean)} | ||
| 777 | * method. | ||
| 778 | * | ||
| 779 | * @param lockedMonitors if <tt>true</tt>, dump all locked monitors. | ||
| 780 | * @param lockedSynchronizers if <tt>true</tt>, dump all locked | ||
| 781 | * ownable synchronizers. | ||
| 782 | * | ||
| 783 | * @return an array of {@link ThreadInfo} for all live threads. | ||
| 784 | * | ||
| 785 | * @throws java.lang.SecurityException if a security manager | ||
| 786 | * exists and the caller does not have | ||
| 787 | * ManagementPermission("monitor"). | ||
| 788 | * @throws java.lang.UnsupportedOperationException | ||
| 789 | * <ul> | ||
| 790 | * <li>if <tt>lockedMonitors</tt> is <tt>true</tt> but | ||
| 791 | * the Java virtual machine does not support monitoring | ||
| 792 | * of {@linkplain #isObjectMonitorUsageSupported | ||
| 793 | * object monitor usage}; or</li> | ||
| 794 | * <li>if <tt>lockedSynchronizers</tt> is <tt>true</tt> but | ||
| 795 | * the Java virtual machine does not support monitoring | ||
| 796 | * of {@linkplain #isSynchronizerUsageSupported | ||
| 797 | * ownable synchronizer usage}.</li> | ||
| 798 | * </ul> | ||
| 799 | * | ||
| 800 | * @see #isObjectMonitorUsageSupported | ||
| 801 | * @see #isSynchronizerUsageSupported | ||
| 802 | * | ||
| 803 | * @since 1.6 | ||
| 804 | */ | ||
| 805 | public ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers); | ||
| 806 | } | ||