Frames | No Frames |
1: /* ThreadMXBean.java - Interface for a thread bean 2: Copyright (C) 2006 Free Software Foundation 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package java.lang.management; 39: 40: /** 41: * <p> 42: * Provides access to information about the threads 43: * of the virtual machine. An instance of this bean is 44: * obtained by calling 45: * {@link ManagementFactory#getThreadMXBean()}. 46: * </p> 47: * <p> 48: * Each thread within the virtual machine is given an 49: * identifier, which is guaranteed to be unique to a 50: * particular thread over its lifetime (after which it 51: * may be reused). The identifier for a thread may be 52: * obtained by calling {@link java.lang.Thread#getId()}. 53: * This identifier is used within implementations of this 54: * interface to obtain information about a particular thread 55: * (or series of threads, in the case of an array of identifiers). 56: * </p> 57: * <p> 58: * This bean supports some optional behaviour, which all 59: * virtual machines may not choose to implement. Specifically, 60: * this includes the monitoring of the CPU time used by a 61: * thread, and the monitoring of thread contention. The former 62: * is further subdivided into the monitoring of either just 63: * the current thread or all threads. The methods 64: * {@link #isThreadCpuTimeSupported()}, 65: * {@link #isCurrentThreadCpuTimeSupported()} and 66: * {@link #isThreadContentionMonitoringSupported()} may be 67: * used to determine whether or not this functionality is 68: * supported. 69: * </p> 70: * <p> 71: * Furthermore, both these facilities may be disabled. 72: * In fact, thread contention monitoring is disabled by 73: * default, and must be explictly turned on by calling 74: * the {@link #setThreadContentionMonitoringEnabled(boolean)} 75: * method. 76: * </p> 77: * 78: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 79: * @since 1.5 80: */ 81: public interface ThreadMXBean 82: { 83: 84: /** 85: * <p> 86: * This method obtains a list of threads which are deadlocked 87: * waiting to obtain monitor ownership. On entering a synchronized 88: * method of an object, or re-entering it after returning from an 89: * {@link java.lang.Object#wait()} call, a thread obtains ownership 90: * of the object's monitor. 91: * </p> 92: * <p> 93: * Deadlocks can occur in this situation if one or more threads end up 94: * waiting for a monitor, P, while also retaining ownership of a monitor, 95: * Q, required by the thread that currently owns P. To give a simple 96: * example, imagine thread A calls a synchronized method, R, obtaining the 97: * monitor, P. It then sleeps within that method, allowing thread B 98: * to run, but still retaining ownership of P. B calls another 99: * synchronized method, S, which causes it to obtain the monitor, Q, 100: * of a different object. While in that method, it then wants to 101: * call the original synchronized method, R, called by A. Doing so 102: * requires ownership of P, which is still held by A. Hence, it 103: * becomes blocked. 104: * </p> 105: * <p> 106: * A then finishes its sleep, becomes runnable, and is then allowed 107: * to run, being the only eligible thread in this scenario. A tries 108: * to call the synchronized method, S. It also gets blocked, because 109: * B still holds the monitor, Q. Hence, the two threads, A and B, 110: * are deadlocked, as neither can give up its monitor without first 111: * obtaining the monitor held by the other thread. 112: * </p> 113: * <p> 114: * Calling this method in this scenario would return the thread IDs 115: * of A and B. Note that this method is not designed for controlling 116: * synchronization, but for troubleshooting problems which cause such 117: * deadlocks; it may be prohibitively expensive to use in normal 118: * operation. 119: * </p> 120: * 121: * @return an array of thread identifiers, corresponding to threads 122: * which are currently in a deadlocked situation. 123: * @throws SecurityException if a security manager exists and 124: * denies ManagementPermission("monitor"). 125: */ 126: long[] findMonitorDeadlockedThreads(); 127: 128: /** 129: * Returns all live thread identifiers at the time of initial 130: * execution. Some thread identifiers in the returned array 131: * may refer to terminated threads, if this occurs during the 132: * lifetime of this method. 133: * 134: * @return an array of thread identifiers, corresponding to 135: * current live threads. 136: * @throws SecurityException if a security manager exists and 137: * denies ManagementPermission("monitor"). 138: */ 139: long[] getAllThreadIds(); 140: 141: /** 142: * <p> 143: * Returns the total number of nanoseconds of CPU time 144: * the current thread has used. This is equivalent to calling 145: * <code>{@link #getThreadCpuTime()}(Thread.currentThread.getId())</code>. 146: * </p> 147: * <p> 148: * Note that the value is only nanosecond-precise, and not accurate; there 149: * is no guarantee that the difference between two values is really a 150: * nanosecond. Also, the value is prone to overflow if the offset 151: * exceeds 2^63. The use of this method depends on virtual machine 152: * support for measurement of the CPU time of the current thread, 153: * and on this functionality being enabled. 154: * </p> 155: * 156: * @return the total number of nanoseconds of CPU time the current 157: * thread has used, or -1 if CPU time monitoring is disabled. 158: * @throws UnsupportedOperationException if CPU time monitoring is not 159: * supported. 160: * @see #getCurrentThreadUserTime() 161: * @see #isCurrentThreadCpuTimeSupported() 162: * @see #isThreadCpuTimeEnabled() 163: * @see #setThreadCpuTimeEnabled(boolean) 164: */ 165: long getCurrentThreadCpuTime(); 166: 167: /** 168: * <p> 169: * Returns the total number of nanoseconds of CPU time 170: * the current thread has executed in user mode. This is 171: * equivalent to calling 172: * <code>{@link #getThreadUserTime()}(Thread.currentThread.getId())</code>. 173: * </p> 174: * <p> 175: * Note that the value is only nanosecond-precise, and not accurate; there 176: * is no guarantee that the difference between two values is really a 177: * nanosecond. Also, the value is prone to overflow if the offset 178: * exceeds 2^63. The use of this method depends on virtual machine 179: * support for measurement of the CPU time of the current thread, 180: * and on this functionality being enabled. 181: * </p> 182: * 183: * @return the total number of nanoseconds of CPU time the current 184: * thread has executed in user mode, or -1 if CPU time 185: * monitoring is disabled. 186: * @throws UnsupportedOperationException if CPU time monitoring is not 187: * supported. 188: * @see #getCurrentThreadCpuTime() 189: * @see #isCurrentThreadCpuTimeSupported() 190: * @see #isThreadCpuTimeEnabled() 191: * @see #setThreadCpuTimeEnabled(boolean) 192: */ 193: long getCurrentThreadUserTime(); 194: 195: /** 196: * Returns the number of live daemon threads. 197: * 198: * @return the number of live daemon threads. 199: */ 200: int getDaemonThreadCount(); 201: 202: /** 203: * Returns the peak number of live threads since 204: * the virtual machine was started or the count 205: * reset using {@link #resetPeakThreadCount()}. 206: * 207: * @return the peak live thread count. 208: * @see #resetPeakThreadCount() 209: */ 210: int getPeakThreadCount(); 211: 212: /** 213: * Returns the number of live threads, including 214: * both daemon threads and non-daemon threads. 215: * 216: * @return the current number of live threads. 217: */ 218: int getThreadCount(); 219: 220: /** 221: * <p> 222: * Returns the total number of nanoseconds of CPU time 223: * the specified thread has used. 224: * </p> 225: * <p> 226: * Note that the value is only nanosecond-precise, and not accurate; there 227: * is no guarantee that the difference between two values is really a 228: * nanosecond. Also, the value is prone to overflow if the offset 229: * exceeds 2^63. The use of this method depends on virtual machine 230: * support for measurement of the CPU time of the current thread, 231: * and on this functionality being enabled. 232: * </p> 233: * 234: * @param id the thread identifier of the thread whose CPU time is being 235: * monitored. 236: * @return the total number of nanoseconds of CPU time the specified 237: * thread has used, or -1 if CPU time monitoring is disabled. 238: * @throws IllegalArgumentException if <code>id</code> <= 0. 239: * @throws UnsupportedOperationException if CPU time monitoring is not 240: * supported. 241: * @see #getThreadUserTime(long) 242: * @see #isThreadCpuTimeSupported() 243: * @see #isThreadCpuTimeEnabled() 244: * @see #setThreadCpuTimeEnabled(boolean) 245: */ 246: long getThreadCpuTime(long id); 247: 248: /** 249: * Returns information on the specified thread without any 250: * stack trace information. This is equivalent to 251: * <code>{@link #getThreadInfo}(id, 0)</code>. If the 252: * identifier specifies a thread which is either non-existant 253: * or not alive, then the method returns <code>null</code>. 254: * 255: * @param id the identifier of the thread to return information 256: * on. 257: * @return a {@link ThreadInfo} object pertaining to the specified 258: * thread, or <code>null</code> if the identifier specifies 259: * a thread that doesn't exist or is not alive. 260: * @throws IllegalArgumentException if <code>id</code> <= 0. 261: * @throws SecurityException if a security manager exists and 262: * denies ManagementPermission("monitor"). 263: */ 264: ThreadInfo getThreadInfo(long id); 265: 266: /** 267: * Returns information on the specified threads without any 268: * stack trace information. This is equivalent to 269: * <code>{@link #getThreadInfo}(ids, 0)</code>. If an 270: * identifier specifies a thread which is either non-existant 271: * or not alive, then the corresponding element in the returned 272: * array is <code>null</code>. 273: * 274: * @param ids an array of thread identifiers to return information 275: * on. 276: * @return an array of {@link ThreadInfo} objects matching the 277: * specified threads. The corresponding element is 278: * <code>null</code> if the identifier specifies 279: * a thread that doesn't exist or is not alive. 280: * @throws IllegalArgumentException if an identifier in the array is 281: * <= 0. 282: * @throws SecurityException if a security manager exists and 283: * denies ManagementPermission("monitor"). 284: */ 285: ThreadInfo[] getThreadInfo(long[] ids); 286: 287: /** 288: * Returns information on the specified thread with 289: * stack trace information to the supplied depth. If the 290: * identifier specifies a thread which is either non-existant 291: * or not alive, then the method returns <code>null</code>. 292: * A maximum depth of 0 corresponds to an empty stack trace 293: * (an empty array is returned by the appropriate 294: * {@link ThreadInfo} method). A maximum depth of 295: * <code>Integer.MAX_VALUE</code> returns the full stack trace. 296: * 297: * @param id the identifier of the thread to return information 298: * on. 299: * @param maxDepth the maximum depth of the stack trace. 300: * Values of 0 or <code>Integer.MAX_VALUE</code> 301: * correspond to an empty and full stack trace 302: * respectively. 303: * @return a {@link ThreadInfo} object pertaining to the specified 304: * thread, or <code>null</code> if the identifier specifies 305: * a thread that doesn't exist or is not alive. 306: * @throws IllegalArgumentException if <code>id</code> <= 0. 307: * @throws IllegalArgumentException if <code>maxDepth</code> < 0. 308: * @throws SecurityException if a security manager exists and 309: * denies ManagementPermission("monitor"). 310: */ 311: ThreadInfo getThreadInfo(long id, int maxDepth); 312: 313: /** 314: * Returns information on the specified threads with 315: * stack trace information to the supplied depth. If an 316: * identifier specifies a thread which is either non-existant 317: * or not alive, then the corresponding element in the returned 318: * array is <code>null</code>. A maximum depth of 0 corresponds 319: * to an empty stack trace (an empty array is returned by the 320: * appropriate {@link ThreadInfo} method). A maximum depth of 321: * <code>Integer.MAX_VALUE</code> returns the full stack trace. 322: * 323: * @param ids an array of thread identifiers to return information 324: * on. 325: * @param maxDepth the maximum depth of the stack trace. 326: * Values of 0 or <code>Integer.MAX_VALUE</code> 327: * correspond to an empty and full stack trace 328: * respectively. 329: * @return an array of {@link ThreadInfo} objects matching the 330: * specified threads. The corresponding element is 331: * <code>null</code> if the identifier specifies 332: * a thread that doesn't exist or is not alive. 333: * @throws IllegalArgumentException if an identifier in the array is 334: * <= 0. 335: * @throws IllegalArgumentException if <code>maxDepth</code> < 0. 336: * @throws SecurityException if a security manager exists and 337: * denies ManagementPermission("monitor"). 338: */ 339: ThreadInfo[] getThreadInfo(long[] ids, int maxDepth); 340: 341: /** 342: * <p> 343: * Returns the total number of nanoseconds of CPU time 344: * the specified thread has executed in user mode. 345: * </p> 346: * <p> 347: * Note that the value is only nanosecond-precise, and not accurate; there 348: * is no guarantee that the difference between two values is really a 349: * nanosecond. Also, the value is prone to overflow if the offset 350: * exceeds 2^63. The use of this method depends on virtual machine 351: * support for measurement of the CPU time of the current thread, 352: * and on this functionality being enabled. 353: * </p> 354: * 355: * @param id the thread identifier of the thread whose CPU time is being 356: * monitored. 357: * @return the total number of nanoseconds of CPU time the specified 358: * thread has executed in user mode, or -1 if CPU time monitoring 359: * is disabled. 360: * @throws IllegalArgumentException if <code>id</code> <= 0. 361: * @throws UnsupportedOperationException if CPU time monitoring is not 362: * supported. 363: * @see #getThreadCpuTime(long) 364: * @see #isThreadCpuTimeSupported() 365: * @see #isThreadCpuTimeEnabled() 366: * @see #setThreadCpuTimeEnabled(boolean) 367: */ 368: long getThreadUserTime(long id); 369: 370: /** 371: * Returns the total number of threads that have been 372: * created and started during the lifetime of the virtual 373: * machine. 374: * 375: * @return the total number of started threads. 376: */ 377: long getTotalStartedThreadCount(); 378: 379: /** 380: * Returns true if the virtual machine supports the monitoring 381: * of the CPU time used by the current thread. This is implied 382: * by {@link isThreadCpuTimeSupported()} returning true. 383: * 384: * @return true if monitoring of the CPU time used by the current 385: * thread is supported by the virtual machine. 386: * @see #isThreadCpuTimeEnabled() 387: * @see #isThreadCpuTimeSupported() 388: * @see #setThreadCpuTimeEnabled(boolean) 389: */ 390: boolean isCurrentThreadCpuTimeSupported(); 391: 392: /** 393: * Returns true if thread contention monitoring is currently 394: * enabled. 395: * 396: * @return true if thread contention monitoring is enabled. 397: * @throws UnsupportedOperationException if the virtual 398: * machine does not 399: * support contention 400: * monitoring. 401: * @see #isThreadContentionMonitoringSupported() 402: * @see #setThreadContentionMonitoringEnabled(boolean) 403: */ 404: boolean isThreadContentionMonitoringEnabled(); 405: 406: /** 407: * Returns true if thread contention monitoring is supported 408: * by the virtual machine. 409: * 410: * @return true if thread contention monitoring is supported 411: * by the virtual machine. 412: * @see #isThreadContentionMonitoringEnabled() 413: * @see #setThreadContentionMonitoringEnabled(boolean) 414: */ 415: boolean isThreadContentionMonitoringSupported(); 416: 417: /** 418: * Returns true if monitoring of the CPU time used by a thread 419: * is currently enabled. 420: * 421: * @return true if thread CPU time monitoring is enabled. 422: * @throws UnsupportedOperationException if the virtual 423: * machine does not 424: * support CPU time 425: * monitoring. 426: * @see #isCurrentThreadCpuTimeSupported() 427: * @see #isThreadCpuTimeSupported() 428: * @see #setThreadCpuTimeEnabled(boolean) 429: */ 430: boolean isThreadCpuTimeEnabled(); 431: 432: /** 433: * Returns true if the virtual machine supports the monitoring 434: * of the CPU time used by all threads. This implies 435: * that {@link isCurrentThreadCpuTimeSupported()} returns true. 436: * 437: * @return true if monitoring of the CPU time used by the current 438: * thread is supported by the virtual machine. 439: * @see #isCurrentThreadCpuTimeSupported() 440: * @see #isThreadCpuTimeEnabled() 441: * @see #setThreadCpuTimeEnabled(boolean) 442: */ 443: boolean isThreadCpuTimeSupported(); 444: 445: /** 446: * Resets the peak live thread count to the 447: * current number of live threads, as returned 448: * by {@link #getThreadCount()}. 449: * 450: * @see #getPeakThreadCount() 451: * @see #getThreadCount() 452: * @throws SecurityException if a security manager exists and 453: * denies ManagementPermission("control"). 454: */ 455: void resetPeakThreadCount(); 456: 457: /** 458: * Toggles the monitoring of thread contention. Thread 459: * contention monitoring is disabled by default. Each 460: * time contention monitoring is re-enabled, the times 461: * it maintains are reset. 462: * 463: * @param enable true if monitoring should be enabled, 464: * false if it should be disabled. 465: * @throws UnsupportedOperationException if the virtual 466: * machine does not 467: * support contention 468: * monitoring. 469: * @throws SecurityException if a security manager exists and 470: * denies ManagementPermission("control"). 471: * @see #isThreadContentionMonitoringEnabled() 472: * @see #isThreadContentionMonitoringSupported() 473: */ 474: void setThreadContentionMonitoringEnabled(boolean enable); 475: 476: /** 477: * Toggles the monitoring of CPU time used by threads. The 478: * initial setting is dependent on the underlying virtual 479: * machine. On enabling CPU time monitoring, the virtual 480: * machine may take any value up to and including the current 481: * time as the start time for monitoring. 482: * 483: * @param enable true if monitoring should be enabled, 484: * false if it should be disabled. 485: * @throws UnsupportedOperationException if the virtual 486: * machine does not 487: * support CPU time 488: * monitoring. 489: * @throws SecurityException if a security manager exists and 490: * denies ManagementPermission("control"). 491: * @see #isCurrentThreadCpuTimeSupported() 492: * @see #isThreadCpuTimeEnabled() 493: * @see #isThreadCpuTimeSupported() 494: */ 495: void setThreadCpuTimeEnabled(boolean enable); 496: 497: }