1/* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package java.lang.management; 27 28import 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 67 * if a Java virtual machine supports measuring of the CPU time for any 68 * thread. The {@link #isCurrentThreadCpuTimeSupported} method can 69 * be used to determine if a Java virtual machine supports measuring of 70 * the CPU time for the current thread. 71 * A Java virtual machine implementation that supports CPU time measurement 72 * for any thread will also support that for the current thread. 73 * 74 * <p> The CPU time provided by this interface has nanosecond precision 75 * but not necessarily nanosecond accuracy. 76 * 77 * <p> 78 * A Java virtual machine may disable CPU time measurement 79 * by default. 80 * The {@link #isThreadCpuTimeEnabled} and {@link #setThreadCpuTimeEnabled} 81 * methods can be used to test if CPU time measurement is enabled 82 * and to enable/disable this support respectively. 83 * Enabling thread CPU measurement could be expensive in some 84 * Java virtual machine implementations. 85 * 86 * <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 124public interface ThreadMXBean extends PlatformManagedObject { 125 /** 126 * Returns the current number of live threads including both 127 * daemon and non-daemon threads. 128 * 129 * @return the current number of live threads. 130 */ 131 public int getThreadCount(); 132 133 /** 134 * Returns the peak live thread count since the Java virtual machine 135 * started or peak was reset. 136 * 137 * @return the peak live thread count. 138 */ 139 public int getPeakThreadCount(); 140 141 /** 142 * Returns the total number of threads created and also started 143 * since the Java virtual machine started. 144 * 145 * @return the total number of threads started. 146 */ 147 public long getTotalStartedThreadCount(); 148 149 /** 150 * Returns the current number of live daemon threads. 151 * 152 * @return the current number of live daemon threads. 153 */ 154 public int getDaemonThreadCount(); 155 156 /** 157 * Returns all live thread IDs. 158 * Some threads included in the returned array 159 * may have been terminated when this method returns. 160 * 161 * @return an array of {@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} 807