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:
  61:  * </p>
  62:  * <ul>
  63:  * <li>the CPU time used by a thread</li>
  64:  * <li>thread contention</li>
  65:  * <li>object monitor usage</li>
  66:  * <li>ownable synchronizer usage</li>
  67:  * </ul>
  68:  * <p>
  69:  * The monitoring of CPU time is further subdivided into
  70:  * the monitoring of either just the current thread or all
  71:  * threads.  The methods
  72:  * {@link #isThreadCpuTimeSupported()},
  73:  * {@link #isCurrentThreadCpuTimeSupported()}
  74:  * {@link #isThreadContentionMonitoringSupported()},
  75:  * {@link #isObjectMonitorUsageSupported()} and
  76:  * {@link #isSynchronizerUsageSupported()} may be
  77:  * used to determine whether or not this functionality is
  78:  * supported.
  79:  * </p>
  80:  * <p>
  81:  * Furthermore, both time and contention monitoring may be
  82:  * disabled.  In fact, thread contention monitoring is disabled
  83:  * by default, and must be explictly turned on by calling
  84:  * the {@link #setThreadContentionMonitoringEnabled(boolean)}
  85:  * method.
  86:  * </p>
  87:  *
  88:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  89:  * @since 1.5
  90:  */
  91: public interface ThreadMXBean
  92: {
  93: 
  94:   /**
  95:    * This method returns information on all live threads at the
  96:    * time of execution (some threads may have terminated by the
  97:    * time the method completes).  This method is simply a shorthand
  98:    * for calling {@link #getThreadInfo(long[], boolean,
  99:    * boolean)} with the return value of {@link #getAllThreadIds()}.
 100:    *
 101:    * @param lockedMonitors true if the returned {@link ThreadInfo}
 102:    *                       objects should contain information on
 103:    *                       locked monitors.
 104:    * @param lockedSynchronizers true if the returned {@link ThreadInfo}
 105:    *                            objects should contain information
 106:    *                            on locked ownable synchronizers.
 107:    * @return an array of {@link ThreadInfo} objects for all live threads.
 108:    * @throws SecurityException if a security manager exists and
 109:    *                           denies ManagementPermission("monitor").
 110:    * @throws UnsupportedOperationException if <code>lockedMonitors</code>
 111:    *                                       is true, but object monitor
 112:    *                                       usage monitoring is not supported
 113:    *                                       by the VM, or
 114:    *                                       <code>lockedSynchronizers</code>
 115:    *                                       is true, but ownable synchronizer
 116:    *                                       usage monitoring is not supported
 117:    *                                       by the VM.
 118:    * @since 1.6
 119:    * @see #getThreadInfo(long[], boolean, boolean)
 120:    * @see #getAllThreadIds()
 121:    * @see #isObjectMonitorUsageSupported()
 122:    * @see #isSynchronizerUsageSupported()
 123:    */
 124:   ThreadInfo[] dumpAllThreads(boolean lockedMonitors,
 125:                   boolean lockedSynchronizers);
 126:   
 127:   /**
 128:    * <p>
 129:    * This method obtains a list of threads which are deadlocked
 130:    * waiting to obtain monitor or ownable synchronizer ownership.
 131:    * This is similar to the behaviour described for
 132:    * {@link #getMonitorDeadlockedThreads()}, except this method also
 133:    * takes in to account deadlocks involving ownable synchronizers.
 134:    * </p>
 135:    * <p>
 136:    * Note that this method is not designed for controlling
 137:    * synchronization, but for troubleshooting problems which cause such
 138:    * deadlocks; it may be prohibitively expensive to use in normal
 139:    * operation.  If only deadlocks involving monitors are of interest,
 140:    * then {@link #findMonitorDeadlockedThreads()} should be used in
 141:    * preference to this method.
 142:    * </p>
 143:    * 
 144:    * @return an array of thread identifiers, corresponding to threads
 145:    *         which are currently in a deadlocked situation, or
 146:    *         <code>null</code> if there are no deadlocks.
 147:    * @throws SecurityException if a security manager exists and
 148:    *                           denies ManagementPermission("monitor").
 149:    * @throws UnsupportedOperationException if the VM does not support
 150:    *                                       the monitoring of ownable
 151:    *                                       synchronizer usage.
 152:    * @since 1.6
 153:    * @see #findMonitorDeadlockedThreads()
 154:    * @see #isSynchronizerUsageSupported()
 155:    */
 156:   long[] findDeadlockedThreads();
 157: 
 158:   /**
 159:    * <p>
 160:    * This method obtains a list of threads which are deadlocked
 161:    * waiting to obtain monitor ownership.  On entering a synchronized
 162:    * method of an object, or re-entering it after returning from an
 163:    * {@link java.lang.Object#wait()} call, a thread obtains ownership
 164:    * of the object's monitor.  
 165:    * </p>
 166:    * <p>
 167:    * Deadlocks can occur in this situation if one or more threads end up
 168:    * waiting for a monitor, P, while also retaining ownership of a monitor,
 169:    * Q, required by the thread that currently owns P.  To give a simple
 170:    * example, imagine thread A calls a synchronized method, R, obtaining the
 171:    * monitor, P.  It then sleeps within that method, allowing thread B
 172:    * to run, but still retaining ownership of P.  B calls another
 173:    * synchronized method, S, which causes it to obtain the monitor, Q,
 174:    * of a different object.  While in that method, it then wants to
 175:    * call the original synchronized method, R,  called by A.  Doing so
 176:    * requires ownership of P, which is still held by A.  Hence, it
 177:    * becomes blocked.  
 178:    * </p>
 179:    * <p>
 180:    * A then finishes its sleep, becomes runnable, and is then allowed
 181:    * to run, being the only eligible thread in this scenario.  A tries
 182:    * to call the synchronized method, S.  It also gets blocked, because
 183:    * B still holds the monitor, Q.  Hence, the two threads, A and B,
 184:    * are deadlocked, as neither can give up its monitor without first
 185:    * obtaining the monitor held by the other thread.
 186:    * </p>
 187:    * <p>
 188:    * Calling this method in this scenario would return the thread IDs
 189:    * of A and B.  Note that this method is not designed for controlling
 190:    * synchronization, but for troubleshooting problems which cause such
 191:    * deadlocks; it may be prohibitively expensive to use in normal
 192:    * operation.  This method only returns deadlocks involving monitors;
 193:    * to include deadlocks involving ownable synchronizers,
 194:    * {@link #findDeadlockedThreads()} should be used instead.
 195:    * </p>
 196:    * 
 197:    * @return an array of thread identifiers, corresponding to threads
 198:    *         which are currently in a deadlocked situation, or
 199:    *         <code>null</code> if there are no deadlocks.
 200:    * @throws SecurityException if a security manager exists and
 201:    *                           denies ManagementPermission("monitor").
 202:    * @see #findDeadlockedThreads()
 203:    */
 204:   long[] findMonitorDeadlockedThreads();
 205: 
 206:   /**
 207:    * Returns all live thread identifiers at the time of initial
 208:    * execution.  Some thread identifiers in the returned array
 209:    * may refer to terminated threads, if this occurs during the
 210:    * lifetime of this method.
 211:    *
 212:    * @return an array of thread identifiers, corresponding to
 213:    *         current live threads.
 214:    * @throws SecurityException if a security manager exists and
 215:    *                           denies ManagementPermission("monitor").
 216:    */
 217:   long[] getAllThreadIds();
 218: 
 219:   /**
 220:    * <p>
 221:    * Returns the total number of nanoseconds of CPU time
 222:    * the current thread has used.  This is equivalent to calling
 223:    * <code>{@link #getThreadCpuTime()}(Thread.currentThread.getId())</code>.
 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:    * @return the total number of nanoseconds of CPU time the current
 235:    *         thread has used, or -1 if CPU time monitoring is disabled.
 236:    * @throws UnsupportedOperationException if CPU time monitoring is not
 237:    *                                       supported.
 238:    * @see #getCurrentThreadUserTime()
 239:    * @see #isCurrentThreadCpuTimeSupported()
 240:    * @see #isThreadCpuTimeEnabled()
 241:    * @see #setThreadCpuTimeEnabled(boolean)
 242:    */
 243:   long getCurrentThreadCpuTime();
 244: 
 245:   /**
 246:    * <p>
 247:    * Returns the total number of nanoseconds of CPU time
 248:    * the current thread has executed in user mode.  This is
 249:    * equivalent to calling
 250:    * <code>{@link #getThreadUserTime()}(Thread.currentThread.getId())</code>.
 251:    * </p> 
 252:    * <p>
 253:    * Note that the value is only nanosecond-precise, and not accurate; there
 254:    * is no guarantee that the difference between two values is really a
 255:    * nanosecond.  Also, the value is prone to overflow if the offset
 256:    * exceeds 2^63.  The use of this method depends on virtual machine
 257:    * support for measurement of the CPU time of the current thread,
 258:    * and on this functionality being enabled.
 259:    * </p>
 260:    *
 261:    * @return the total number of nanoseconds of CPU time the current
 262:    *         thread has executed in user mode, or -1 if CPU time
 263:    *         monitoring is disabled.
 264:    * @throws UnsupportedOperationException if CPU time monitoring is not
 265:    *                                       supported.
 266:    * @see #getCurrentThreadCpuTime()
 267:    * @see #isCurrentThreadCpuTimeSupported()
 268:    * @see #isThreadCpuTimeEnabled()
 269:    * @see #setThreadCpuTimeEnabled(boolean)
 270:    */
 271:   long getCurrentThreadUserTime();
 272: 
 273:   /**
 274:    * Returns the number of live daemon threads.
 275:    *
 276:    * @return the number of live daemon threads.
 277:    */
 278:   int getDaemonThreadCount();
 279: 
 280:   /**
 281:    * Returns the peak number of live threads since
 282:    * the virtual machine was started or the count
 283:    * reset using {@link #resetPeakThreadCount()}.
 284:    *
 285:    * @return the peak live thread count.
 286:    * @see #resetPeakThreadCount()
 287:    */
 288:   int getPeakThreadCount();
 289: 
 290:   /**
 291:    * Returns the number of live threads, including
 292:    * both daemon threads and non-daemon threads.
 293:    *
 294:    * @return the current number of live threads.
 295:    */
 296:   int getThreadCount();
 297: 
 298:   /**
 299:    * <p>
 300:    * Returns the total number of nanoseconds of CPU time
 301:    * the specified thread has used.  
 302:    * </p> 
 303:    * <p>
 304:    * Note that the value is only nanosecond-precise, and not accurate; there
 305:    * is no guarantee that the difference between two values is really a
 306:    * nanosecond.  Also, the value is prone to overflow if the offset
 307:    * exceeds 2^63.  The use of this method depends on virtual machine
 308:    * support for measurement of the CPU time of the current thread,
 309:    * and on this functionality being enabled.
 310:    * </p>
 311:    *
 312:    * @param id the thread identifier of the thread whose CPU time is being
 313:    *           monitored.
 314:    * @return the total number of nanoseconds of CPU time the specified
 315:    *         thread has used, or -1 if CPU time monitoring is disabled.
 316:    * @throws IllegalArgumentException if <code>id</code> <= 0.
 317:    * @throws UnsupportedOperationException if CPU time monitoring is not
 318:    *                                       supported.
 319:    * @see #getThreadUserTime(long)
 320:    * @see #isThreadCpuTimeSupported()
 321:    * @see #isThreadCpuTimeEnabled()
 322:    * @see #setThreadCpuTimeEnabled(boolean)
 323:    */
 324:   long getThreadCpuTime(long id);
 325: 
 326:   /**
 327:    * Returns information on the specified thread without any
 328:    * stack trace information.  This is equivalent to
 329:    * <code>{@link #getThreadInfo}(id, 0)</code>.  If the
 330:    * identifier specifies a thread which is either non-existant
 331:    * or not alive, then the method returns <code>null</code>.
 332:    * 
 333:    * @param id the identifier of the thread to return information
 334:    *           on.
 335:    * @return a {@link ThreadInfo} object pertaining to the specified
 336:    *         thread, or <code>null</code> if the identifier specifies
 337:    *         a thread that doesn't exist or is not alive.
 338:    * @throws IllegalArgumentException if <code>id</code> <= 0.
 339:    * @throws SecurityException if a security manager exists and
 340:    *                           denies ManagementPermission("monitor").
 341:    */
 342:   ThreadInfo getThreadInfo(long id);
 343: 
 344:   /**
 345:    * Returns information on the specified threads without any
 346:    * stack trace information.  This is equivalent to
 347:    * <code>{@link #getThreadInfo}(ids, 0)</code>.  If an
 348:    * identifier specifies a thread which is either non-existant
 349:    * or not alive, then the corresponding element in the returned
 350:    * array is <code>null</code>.
 351:    * 
 352:    * @param ids an array of thread identifiers to return information
 353:    *           on.
 354:    * @return an array of {@link ThreadInfo} objects matching the
 355:    *         specified threads.  The corresponding element is 
 356:    *         <code>null</code> if the identifier specifies
 357:    *         a thread that doesn't exist or is not alive.
 358:    * @throws IllegalArgumentException if an identifier in the array is
 359:    *                                  <= 0.
 360:    * @throws SecurityException if a security manager exists and
 361:    *                           denies ManagementPermission("monitor").
 362:    */
 363:   ThreadInfo[] getThreadInfo(long[] ids);
 364: 
 365:   /**
 366:    * Returns information on the specified threads with full
 367:    * stack trace information and optional synchronization
 368:    * information.  If <code>lockedMonitors</code> is false,
 369:    * or there are no locked monitors for a particular thread,
 370:    * then the corresponding {@link ThreadInfo} object will have
 371:    * an empty {@link MonitorInfo} array.  Likewise, if
 372:    * <code>lockedSynchronizers</code> is false, or there are
 373:    * no locked ownable synchronizers for a particular thread,
 374:    * then the corresponding {@link ThreadInfo} object will have
 375:    * an empty {@link LockInfo} array.  If both
 376:    * <code>lockedMonitors</code> and <code>lockedSynchronizers</code>
 377:    * are false, the return value is equivalent to that from
 378:    * <code>{@link #getThreadInfo}(ids, Integer.MAX_VALUE)</code>.
 379:    * If an identifier specifies a thread which is either non-existant
 380:    * or not alive, then the corresponding element in the returned
 381:    * array is <code>null</code>.
 382:    * 
 383:    * @param ids an array of thread identifiers to return information
 384:    *           on.
 385:    * @param lockedMonitors true if information on locked monitors
 386:    *                       should be included.
 387:    * @param lockedSynchronizers true if information on locked
 388:    *                            ownable synchronizers should be included. 
 389:    * @return an array of {@link ThreadInfo} objects matching the
 390:    *         specified threads.  The corresponding element is 
 391:    *         <code>null</code> if the identifier specifies
 392:    *         a thread that doesn't exist or is not alive.
 393:    * @throws IllegalArgumentException if an identifier in the array is
 394:    *                                  <= 0.
 395:    * @throws SecurityException if a security manager exists and
 396:    *                           denies ManagementPermission("monitor").
 397:    * @throws UnsupportedOperationException if <code>lockedMonitors</code>
 398:    *                                       is true, but object monitor
 399:    *                                       usage monitoring is not supported
 400:    *                                       by the VM, or
 401:    *                                       <code>lockedSynchronizers</code>
 402:    *                                       is true, but ownable synchronizer
 403:    *                                       usage monitoring is not supported
 404:    *                                       by the VM.
 405:    * @since 1.6
 406:    * @see #isObjectMonitorUsageSupported()
 407:    * @see #isSynchronizerUsageSupported()
 408:    */
 409:   ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors,
 410:                  boolean lockedSynchronizers);
 411: 
 412:   /**
 413:    * Returns information on the specified thread with
 414:    * stack trace information to the supplied depth.  If the
 415:    * identifier specifies a thread which is either non-existant
 416:    * or not alive, then the method returns <code>null</code>.
 417:    * A maximum depth of 0 corresponds to an empty stack trace
 418:    * (an empty array is returned by the appropriate
 419:    * {@link ThreadInfo} method).  A maximum depth of
 420:    * <code>Integer.MAX_VALUE</code> returns the full stack trace.
 421:    *
 422:    * @param id the identifier of the thread to return information
 423:    *           on.
 424:    * @param maxDepth the maximum depth of the stack trace.
 425:    *                 Values of 0 or <code>Integer.MAX_VALUE</code>
 426:    *                 correspond to an empty and full stack trace
 427:    *                 respectively.
 428:    * @return a {@link ThreadInfo} object pertaining to the specified
 429:    *         thread, or <code>null</code> if the identifier specifies
 430:    *         a thread that doesn't exist or is not alive.
 431:    * @throws IllegalArgumentException if <code>id</code> <= 0.
 432:    * @throws IllegalArgumentException if <code>maxDepth</code> < 0.
 433:    * @throws SecurityException if a security manager exists and
 434:    *                           denies ManagementPermission("monitor").
 435:    */
 436:   ThreadInfo getThreadInfo(long id, int maxDepth);
 437: 
 438:   /**
 439:    * Returns information on the specified threads with
 440:    * stack trace information to the supplied depth.  If an
 441:    * identifier specifies a thread which is either non-existant
 442:    * or not alive, then the corresponding element in the returned
 443:    * array is <code>null</code>.  A maximum depth of 0 corresponds
 444:    * to an empty stack trace (an empty array is returned by the
 445:    * appropriate {@link ThreadInfo} method).  A maximum depth of
 446:    * <code>Integer.MAX_VALUE</code> returns the full stack trace.
 447:    * 
 448:    * @param ids an array of thread identifiers to return information
 449:    *           on.
 450:    * @param maxDepth the maximum depth of the stack trace.
 451:    *                 Values of 0 or <code>Integer.MAX_VALUE</code>
 452:    *                 correspond to an empty and full stack trace
 453:    *                 respectively.
 454:    * @return an array of {@link ThreadInfo} objects matching the
 455:    *         specified threads.  The corresponding element is 
 456:    *         <code>null</code> if the identifier specifies
 457:    *         a thread that doesn't exist or is not alive.
 458:    * @throws IllegalArgumentException if an identifier in the array is
 459:    *                                  <= 0.
 460:    * @throws IllegalArgumentException if <code>maxDepth</code> < 0.
 461:    * @throws SecurityException if a security manager exists and
 462:    *                           denies ManagementPermission("monitor").
 463:    */
 464:   ThreadInfo[] getThreadInfo(long[] ids, int maxDepth);
 465: 
 466:   /**
 467:    * <p>
 468:    * Returns the total number of nanoseconds of CPU time
 469:    * the specified thread has executed in user mode.  
 470:    * </p> 
 471:    * <p>
 472:    * Note that the value is only nanosecond-precise, and not accurate; there
 473:    * is no guarantee that the difference between two values is really a
 474:    * nanosecond.  Also, the value is prone to overflow if the offset
 475:    * exceeds 2^63.  The use of this method depends on virtual machine
 476:    * support for measurement of the CPU time of the current thread,
 477:    * and on this functionality being enabled.
 478:    * </p>
 479:    *
 480:    * @param id the thread identifier of the thread whose CPU time is being
 481:    *           monitored.
 482:    * @return the total number of nanoseconds of CPU time the specified
 483:    *         thread has executed in user mode, or -1 if CPU time monitoring
 484:    *         is disabled.
 485:    * @throws IllegalArgumentException if <code>id</code> <= 0.
 486:    * @throws UnsupportedOperationException if CPU time monitoring is not
 487:    *                                       supported.
 488:    * @see #getThreadCpuTime(long)
 489:    * @see #isThreadCpuTimeSupported()
 490:    * @see #isThreadCpuTimeEnabled()
 491:    * @see #setThreadCpuTimeEnabled(boolean)
 492:    */
 493:   long getThreadUserTime(long id);
 494: 
 495:   /**
 496:    * Returns the total number of threads that have been
 497:    * created and started during the lifetime of the virtual
 498:    * machine.
 499:    *
 500:    * @return the total number of started threads.
 501:    */
 502:   long getTotalStartedThreadCount();
 503: 
 504:   /**
 505:    * Returns true if the virtual machine supports the monitoring
 506:    * of the CPU time used by the current thread.  This is implied
 507:    * by {@link isThreadCpuTimeSupported()} returning true.
 508:    *
 509:    * @return true if monitoring of the CPU time used by the current
 510:    *         thread is supported by the virtual machine.
 511:    * @see #isThreadCpuTimeEnabled()
 512:    * @see #isThreadCpuTimeSupported()
 513:    * @see #setThreadCpuTimeEnabled(boolean)
 514:    */
 515:   boolean isCurrentThreadCpuTimeSupported();
 516: 
 517:   /**
 518:    * Returns true if the virtual machine supports the monitoring
 519:    * of object monitor usage.
 520:    *
 521:    * @return true if the monitoring of object monitor usage
 522:    *         is supported by the virtual machine.
 523:    * @since 1.6
 524:    */
 525:   boolean isObjectMonitorUsageSupported();
 526: 
 527:   /**
 528:    * Returns true if the virtual machine supports the monitoring
 529:    * of ownable synchronizer usage.
 530:    *
 531:    * @return true if the monitoring of ownable synchronizer usage
 532:    *         is supported by the virtual machine.
 533:    * @since 1.6
 534:    */
 535:   boolean isSynchronizerUsageSupported();
 536: 
 537:   /**
 538:    * Returns true if thread contention monitoring is currently
 539:    * enabled.
 540:    *
 541:    * @return true if thread contention monitoring is enabled.
 542:    * @throws UnsupportedOperationException if the virtual
 543:    *                                       machine does not
 544:    *                                       support contention
 545:    *                                       monitoring.
 546:    * @see #isThreadContentionMonitoringSupported()
 547:    * @see #setThreadContentionMonitoringEnabled(boolean)
 548:    */
 549:   boolean isThreadContentionMonitoringEnabled();
 550: 
 551:   /**
 552:    * Returns true if thread contention monitoring is supported
 553:    * by the virtual machine.
 554:    *
 555:    * @return true if thread contention monitoring is supported
 556:    *         by the virtual machine.
 557:    * @see #isThreadContentionMonitoringEnabled()
 558:    * @see #setThreadContentionMonitoringEnabled(boolean)
 559:    */
 560:   boolean isThreadContentionMonitoringSupported();
 561: 
 562:   /**
 563:    * Returns true if monitoring of the CPU time used by a thread
 564:    * is currently enabled.
 565:    *
 566:    * @return true if thread CPU time monitoring is enabled.
 567:    * @throws UnsupportedOperationException if the virtual
 568:    *                                       machine does not
 569:    *                                       support CPU time
 570:    *                                       monitoring.
 571:    * @see #isCurrentThreadCpuTimeSupported()
 572:    * @see #isThreadCpuTimeSupported()
 573:    * @see #setThreadCpuTimeEnabled(boolean)
 574:    */
 575:   boolean isThreadCpuTimeEnabled();
 576: 
 577:   /**
 578:    * Returns true if the virtual machine supports the monitoring
 579:    * of the CPU time used by all threads.  This implies
 580:    * that {@link isCurrentThreadCpuTimeSupported()} returns true.
 581:    *
 582:    * @return true if monitoring of the CPU time used by the current
 583:    *         thread is supported by the virtual machine.
 584:    * @see #isCurrentThreadCpuTimeSupported()
 585:    * @see #isThreadCpuTimeEnabled()
 586:    * @see #setThreadCpuTimeEnabled(boolean)
 587:    */
 588:   boolean isThreadCpuTimeSupported();
 589: 
 590:   /**
 591:    * Resets the peak live thread count to the
 592:    * current number of live threads, as returned
 593:    * by {@link #getThreadCount()}.
 594:    *
 595:    * @see #getPeakThreadCount()
 596:    * @see #getThreadCount()
 597:    * @throws SecurityException if a security manager exists and
 598:    *                           denies ManagementPermission("control").
 599:    */
 600:   void resetPeakThreadCount();
 601: 
 602:   /**
 603:    * Toggles the monitoring of thread contention.  Thread
 604:    * contention monitoring is disabled by default.  Each
 605:    * time contention monitoring is re-enabled, the times
 606:    * it maintains are reset.
 607:    *
 608:    * @param enable true if monitoring should be enabled,
 609:    *               false if it should be disabled.
 610:    * @throws UnsupportedOperationException if the virtual
 611:    *                                       machine does not
 612:    *                                       support contention
 613:    *                                       monitoring.
 614:    * @throws SecurityException if a security manager exists and
 615:    *                           denies ManagementPermission("control").
 616:    * @see #isThreadContentionMonitoringEnabled()
 617:    * @see #isThreadContentionMonitoringSupported()
 618:    */
 619:   void setThreadContentionMonitoringEnabled(boolean enable);
 620: 
 621:   /**
 622:    * Toggles the monitoring of CPU time used by threads. The
 623:    * initial setting is dependent on the underlying virtual
 624:    * machine.  On enabling CPU time monitoring, the virtual
 625:    * machine may take any value up to and including the current
 626:    * time as the start time for monitoring.
 627:    *
 628:    * @param enable true if monitoring should be enabled,
 629:    *               false if it should be disabled.
 630:    * @throws UnsupportedOperationException if the virtual
 631:    *                                       machine does not
 632:    *                                       support CPU time
 633:    *                                       monitoring.
 634:    * @throws SecurityException if a security manager exists and
 635:    *                           denies ManagementPermission("control").
 636:    * @see #isCurrentThreadCpuTimeSupported()
 637:    * @see #isThreadCpuTimeEnabled()
 638:    * @see #isThreadCpuTimeSupported()
 639:    */
 640:   void setThreadCpuTimeEnabled(boolean enable);
 641: 
 642: }