< prev index next >

src/java.management/share/classes/java/lang/management/ThreadMXBean.java

Print this page




  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  * <h3>Thread ID</h3>
  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  * <h3>Thread CPU time</h3>
  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


  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  * <h3>Thread Contention Monitoring</h3>
  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  * <h3>Synchronization Information and Deadlock Detection</h3>
 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.


 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 {@code id <= 0}.
 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 {@code <= 0}.
 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 {@code id <= 0}.
 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 {@code <= 0}.
 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 {@code id <= 0}.
 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 {@code id <= 0}.
 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 monitoring 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 }


  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 MBeanServer} method.
  41  *
  42  * <p>The {@code ObjectName} for uniquely identifying the MXBean for
  43  * the thread system within an MBeanServer is:
  44  * <blockquote>
  45  *    {@link ManagementFactory#THREAD_MXBEAN_NAME
  46  *           java.lang:type=Threading}
  47  * </blockquote>
  48  *
  49  * It can be obtained by calling the
  50  * {@link PlatformManagedObject#getObjectName} method.
  51  *
  52  * <h3>Thread ID</h3>
  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  * <h3>Thread CPU time</h3>
  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


  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  * <h3>Thread Contention Monitoring</h3>
  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">{@code ThreadInfo}</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  * <h3>Synchronization Information and Deadlock Detection</h3>
 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 {@code ThreadMXBean} 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.


 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 {@code long}, 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      * {@code id} 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 {@code ThreadInfo} 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 {@code ThreadInfo} 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 {@code null}.  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 {@code ThreadInfo} is
 191      * {@code CompositeData} 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      * {@code null} if the thread of the given ID is not alive or
 199      * it does not exist.
 200      *
 201      * @throws IllegalArgumentException if {@code id <= 0}.
 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 {@code ids} 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 {@code ThreadInfo} objects.
 218      * The stack trace, locked monitors, and locked synchronizers
 219      * in each {@code ThreadInfo} 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 {@code null}.  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 {@code ThreadInfo} is
 229      * {@code CompositeData} 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      *         {@code ids} is {@code <= 0}.
 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 {@code id},
 248      * with stack trace of a specified number of stack trace elements.
 249      * The {@code maxDepth} parameter indicates the maximum number of
 250      * {@link StackTraceElement} to be retrieved from the stack trace.
 251      * If {@code maxDepth == Integer.MAX_VALUE}, the entire stack trace of
 252      * the thread will be dumped.
 253      * If {@code maxDepth == 0}, 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 {@code maxDepth == 0},
 260      * the stack trace in the
 261      * {@code ThreadInfo} object will be an empty array of
 262      * {@code StackTraceElement}.
 263      *
 264      * <p>
 265      * If a thread of the given ID is not alive or does not exist,
 266      * this method will return {@code null}.  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 {@code ThreadInfo} is
 272      * {@code CompositeData} 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. {@code Integer.MAX_VALUE} 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      * {@code null} if the thread of the given ID is not alive or
 283      * it does not exist.
 284      *
 285      * @throws IllegalArgumentException if {@code id <= 0}.
 286      * @throws IllegalArgumentException if {@code maxDepth is negative}.
 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 {@code ids},
 297      * with stack trace of a specified number of stack trace elements.
 298      * The {@code maxDepth} parameter indicates the maximum number of
 299      * {@link StackTraceElement} to be retrieved from the stack trace.
 300      * If {@code maxDepth == Integer.MAX_VALUE}, the entire stack trace of
 301      * the thread will be dumped.
 302      * If {@code maxDepth == 0}, 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 {@code maxDepth == 0},
 309      * the stack trace in the
 310      * {@code ThreadInfo} object will be an empty array of
 311      * {@code StackTraceElement}.
 312      * <p>
 313      * This method returns an array of the {@code ThreadInfo} objects,
 314      * each is the thread information about the thread with the same index
 315      * as in the {@code ids} array.
 316      * If a thread of the given ID is not alive or does not exist,
 317      * {@code null} 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 {@code ThreadInfo} is
 324      * {@code CompositeData} 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. {@code Integer.MAX_VALUE} 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 {@code maxDepth is negative}.
 338      * @throws IllegalArgumentException if any element in the input array
 339      *      {@code ids} is {@code <= 0}.
 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      *   {@code true}
 352      *     if the Java virtual machine supports thread contention monitoring;
 353      *   {@code false} otherwise.
 354      */
 355     public boolean isThreadContentionMonitoringSupported();
 356 
 357     /**
 358      * Tests if thread contention monitoring is enabled.
 359      *
 360      * @return {@code true} if thread contention monitoring is enabled;
 361      *         {@code false} 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 {@code true} to enable;
 375      *               {@code false} 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; {@code -1} 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; {@code -1} 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 {@code -1}. If CPU time measurement
 455      * is disabled, this method returns {@code -1}.
 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      * {@code -1} otherwise.
 468      *
 469      * @throws IllegalArgumentException if {@code id <= 0}.
 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 {@code -1}. If CPU time measurement
 490      * is disabled, this method returns {@code -1}.
 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      * {@code -1} otherwise.
 503      *
 504      * @throws IllegalArgumentException if {@code id <= 0}.
 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      *   {@code true}
 525      *     if the Java virtual machine supports CPU time
 526      *     measurement for any thread;
 527      *   {@code false} 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 {@code true} if {@link #isThreadCpuTimeSupported}
 535      * returns {@code true}.
 536      *
 537      * @return
 538      *   {@code true}
 539      *     if the Java virtual machine supports CPU time
 540      *     measurement for current thread;
 541      *   {@code false} otherwise.
 542      */
 543     public boolean isCurrentThreadCpuTimeSupported();
 544 
 545     /**
 546      * Tests if thread CPU time measurement is enabled.
 547      *
 548      * @return {@code true} if thread CPU time measurement is enabled;
 549      *         {@code false} 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 {@code true} to enable;
 565      *               {@code false} 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; {@code null} 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      * {@code null} 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 monitoring 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      *   {@code true}
 663      *     if the Java virtual machine supports monitoring of
 664      *     object monitor usage;
 665      *   {@code false} 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      *   {@code true}
 679      *     if the Java virtual machine supports monitoring of ownable
 680      *     synchronizer usage;
 681      *   {@code false} 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 {@code ids}, 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 {@code lockedMonitors} is {@code true}, and</li>
 700      *    <li>the <a href="LockInfo.html#OwnableSynchronizer">
 701      *        ownable synchronizers</a> currently locked by the thread
 702      *        if {@code lockedSynchronizers} is {@code true}.</li>
 703      * </ul>
 704      * <p>
 705      * This method returns an array of the {@code ThreadInfo} objects,
 706      * each is the thread information about the thread with the same index
 707      * as in the {@code ids} array.
 708      * If a thread of the given ID is not alive or does not exist,
 709      * {@code null} 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 {@code lockedMonitors}
 714      * is {@code false}, the returned {@code ThreadInfo} object will have an
 715      * empty {@code MonitorInfo} array.  Similarly, if a thread does not
 716      * lock any synchronizer or {@code lockedSynchronizers} is {@code false},
 717      * the returned {@code ThreadInfo} object
 718      * will have an empty {@code LockInfo} array.
 719      *
 720      * <p>
 721      * When both {@code lockedMonitors} and {@code lockedSynchronizers}
 722      * parameters are {@code false}, 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 {@code ThreadInfo} is
 734      * {@code CompositeData} 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 {@code true}, retrieves all locked monitors.
 739      * @param  lockedSynchronizers if {@code true}, 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 {@code lockedMonitors} is {@code true} but
 752      *               the Java virtual machine does not support monitoring
 753      *               of {@linkplain #isObjectMonitorUsageSupported
 754      *               object monitor usage}; or</li>
 755      *           <li>if {@code lockedSynchronizers} is {@code true} 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 {@code true}, dump all locked monitors.
 780      * @param  lockedSynchronizers if {@code true}, 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 {@code lockedMonitors} is {@code true} but
 791      *               the Java virtual machine does not support monitoring
 792      *               of {@linkplain #isObjectMonitorUsageSupported
 793      *               object monitor usage}; or</li>
 794      *           <li>if {@code lockedSynchronizers} is {@code true} 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 }
< prev index next >