1 /*
2 * Copyright (c) 2003, 2019, 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
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 * <h2>Thread ID</h2>
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 * <h2>Thread CPU time</h2>
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 * <h2>Thread Contention Monitoring</h2>
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 * <h2>Synchronization Information and Deadlock Detection</h2>
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.
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 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 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 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 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 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 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 UnsupportedOperationException if the Java
378 * virtual machine does not support thread contention monitoring.
379 *
380 * @throws 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 convenience 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 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 convenience 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 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 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 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 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 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 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 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 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 SecurityException if a security manager
646 * exists and the caller does not have
647 * ManagementPermission("monitor").
648 * @throws 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},
691 * with stack trace and synchronization information.
692 * This is equivalent to calling:
693 * <blockquote>
694 * {@link #getThreadInfo(long[], boolean, boolean, int)
695 * getThreadInfo(ids, lockedMonitors, lockedSynchronizers, Integer.MAX_VALUE)}
696 * </blockquote>
697 *
698 * @param ids an array of thread IDs.
699 * @param lockedMonitors if {@code true}, retrieves all locked monitors.
700 * @param lockedSynchronizers if {@code true}, retrieves all locked
701 * ownable synchronizers.
702 *
703 * @return an array of the {@link ThreadInfo} objects, each containing
704 * information about a thread whose ID is in the corresponding
705 * element of the input array of IDs.
706 *
707 * @throws SecurityException if a security manager
708 * exists and the caller does not have
709 * ManagementPermission("monitor").
710 * @throws UnsupportedOperationException
711 * <ul>
712 * <li>if {@code lockedMonitors} is {@code true} but
713 * the Java virtual machine does not support monitoring
714 * of {@linkplain #isObjectMonitorUsageSupported
715 * object monitor usage}; or</li>
716 * <li>if {@code lockedSynchronizers} is {@code true} but
717 * the Java virtual machine does not support monitoring
718 * of {@linkplain #isSynchronizerUsageSupported
719 * ownable synchronizer usage}.</li>
720 * </ul>
721 *
722 * @see #isObjectMonitorUsageSupported
723 * @see #isSynchronizerUsageSupported
724 *
725 * @since 1.6
726 */
727 public ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors,
728 boolean lockedSynchronizers);
729
730 /**
731 * Returns the thread info for each thread whose ID
732 * is in the input array {@code ids},
733 * with stack trace of the specified maximum number of elements
734 * and synchronization information.
735 * If {@code maxDepth == 0}, no stack trace of the thread
736 * will be dumped.
737 *
738 * <p>
739 * This method obtains a snapshot of the thread information
740 * for each thread including:
741 * <ul>
742 * <li>stack trace of the specified maximum number of elements,</li>
743 * <li>the object monitors currently locked by the thread
744 * if {@code lockedMonitors} is {@code true}, and</li>
745 * <li>the <a href="LockInfo.html#OwnableSynchronizer">
746 * ownable synchronizers</a> currently locked by the thread
747 * if {@code lockedSynchronizers} is {@code true}.</li>
748 * </ul>
749 * <p>
750 * This method returns an array of the {@code ThreadInfo} objects,
751 * each is the thread information about the thread with the same index
752 * as in the {@code ids} array.
753 * If a thread of the given ID is not alive or does not exist,
754 * {@code null} will be set in the corresponding element
755 * in the returned array. A thread is alive if
756 * it has been started and has not yet died.
757 * <p>
758 * If a thread does not lock any object monitor or {@code lockedMonitors}
759 * is {@code false}, the returned {@code ThreadInfo} object will have an
760 * empty {@code MonitorInfo} array. Similarly, if a thread does not
761 * lock any synchronizer or {@code lockedSynchronizers} is {@code false},
762 * the returned {@code ThreadInfo} object
763 * will have an empty {@code LockInfo} array.
764 *
765 * <p>
766 * When both {@code lockedMonitors} and {@code lockedSynchronizers}
767 * parameters are {@code false}, it is equivalent to calling:
768 * <blockquote><pre>
769 * {@link #getThreadInfo(long[], int) getThreadInfo(ids, maxDepth)}
770 * </pre></blockquote>
771 *
772 * <p>
773 * This method is designed for troubleshooting use, but not for
774 * synchronization control. It might be an expensive operation.
775 *
776 * <p>
777 * <b>MBeanServer access</b>:<br>
778 * The mapped type of {@code ThreadInfo} is
779 * {@code CompositeData} with attributes as specified in the
780 * {@link ThreadInfo#from ThreadInfo.from} method.
781 *
782 * @implSpec The default implementation throws
783 * {@code UnsupportedOperationException}.
784 *
785 * @param ids an array of thread IDs.
786 * @param lockedMonitors if {@code true}, retrieves all locked monitors.
787 * @param lockedSynchronizers if {@code true}, retrieves all locked
788 * ownable synchronizers.
789 * @param maxDepth indicates the maximum number of
790 * {@link StackTraceElement} to be retrieved from the stack trace.
791 *
792 * @return an array of the {@link ThreadInfo} objects, each containing
793 * information about a thread whose ID is in the corresponding
794 * element of the input array of IDs.
795 *
796 * @throws IllegalArgumentException if {@code maxDepth} is negative.
797 * @throws SecurityException if a security manager
798 * exists and the caller does not have
799 * ManagementPermission("monitor").
800 * @throws UnsupportedOperationException
801 * <ul>
802 * <li>if {@code lockedMonitors} is {@code true} but
803 * the Java virtual machine does not support monitoring
804 * of {@linkplain #isObjectMonitorUsageSupported
805 * object monitor usage}; or</li>
806 * <li>if {@code lockedSynchronizers} is {@code true} but
807 * the Java virtual machine does not support monitoring
808 * of {@linkplain #isSynchronizerUsageSupported
809 * ownable synchronizer usage}.</li>
810 * </ul>
811 *
812 * @see #isObjectMonitorUsageSupported
813 * @see #isSynchronizerUsageSupported
814 *
815 * @since 10
816 */
817
818 public default ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors,
819 boolean lockedSynchronizers, int maxDepth) {
820 throw new UnsupportedOperationException();
821 }
822
823 /**
824 * Returns the thread info for all live threads with stack trace
825 * and synchronization information.
826 * This is equivalent to calling:
827 * <blockquote>
828 * {@link #dumpAllThreads(boolean, boolean, int)
829 * dumpAllThreads(lockedMonitors, lockedSynchronizers, Integer.MAX_VALUE)}
830 * </blockquote>
831 *
832 * @param lockedMonitors if {@code true}, dump all locked monitors.
833 * @param lockedSynchronizers if {@code true}, dump all locked
834 * ownable synchronizers.
835 *
836 * @return an array of {@link ThreadInfo} for all live threads.
837 *
838 * @throws SecurityException if a security manager
839 * exists and the caller does not have
840 * ManagementPermission("monitor").
841 * @throws UnsupportedOperationException
842 * <ul>
843 * <li>if {@code lockedMonitors} is {@code true} but
844 * the Java virtual machine does not support monitoring
845 * of {@linkplain #isObjectMonitorUsageSupported
846 * object monitor usage}; or</li>
847 * <li>if {@code lockedSynchronizers} is {@code true} but
848 * the Java virtual machine does not support monitoring
849 * of {@linkplain #isSynchronizerUsageSupported
850 * ownable synchronizer usage}.</li>
851 * </ul>
852 *
853 * @see #isObjectMonitorUsageSupported
854 * @see #isSynchronizerUsageSupported
855 *
856 * @since 1.6
857 */
858 public ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers);
859
860
861 /**
862 * Returns the thread info for all live threads
863 * with stack trace of the specified maximum number of elements
864 * and synchronization information.
865 * if {@code maxDepth == 0}, no stack trace of the thread
866 * will be dumped.
867 * Some threads included in the returned array
868 * may have been terminated when this method returns.
869 *
870 * <p>
871 * This method returns an array of {@link ThreadInfo} objects
872 * as specified in the {@link #getThreadInfo(long[], boolean, boolean, int)}
873 * method.
874 *
875 * @implSpec The default implementation throws
876 * {@code UnsupportedOperationException}.
877 *
878 * @param lockedMonitors if {@code true}, dump all locked monitors.
879 * @param lockedSynchronizers if {@code true}, dump all locked
880 * ownable synchronizers.
881 * @param maxDepth indicates the maximum number of
882 * {@link StackTraceElement} to be retrieved from the stack trace.
883 *
884 * @return an array of {@link ThreadInfo} for all live threads.
885 *
886 * @throws IllegalArgumentException if {@code maxDepth} is negative.
887 * @throws SecurityException if a security manager
888 * exists and the caller does not have
889 * ManagementPermission("monitor").
890 * @throws UnsupportedOperationException
891 * <ul>
892 * <li>if {@code lockedMonitors} is {@code true} but
893 * the Java virtual machine does not support monitoring
894 * of {@linkplain #isObjectMonitorUsageSupported
895 * object monitor usage}; or</li>
896 * <li>if {@code lockedSynchronizers} is {@code true} but
897 * the Java virtual machine does not support monitoring
898 * of {@linkplain #isSynchronizerUsageSupported
899 * ownable synchronizer usage}.</li>
900 * </ul>
901 *
902 * @see #isObjectMonitorUsageSupported
903 * @see #isSynchronizerUsageSupported
904 *
905 * @since 10
906 */
907 public default ThreadInfo[] dumpAllThreads(boolean lockedMonitors,
908 boolean lockedSynchronizers, int maxDepth) {
909 throw new UnsupportedOperationException();
910 }
911 }