Source for java.lang.management.ThreadMXBean

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