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 the Java virtual machine.
 32  *
 33  * <p> {@code ThreadMXBean} supports monitoring and management of <em>live
 34  * platform threads</em> in the Java virtual machine. Platform threads are
 35  * typically mapped to kernel threads scheduled by the operating system.
 36  * {@code ThreadMXBean} does not support monitoring or management of {@linkplain
 37  * Thread#isVirtual() virtual threads}.
 38  *
 39  * <p> A Java virtual machine has a single instance of the implementation
 40  * class of this interface.  This instance implementing this interface is
 41  * an <a href="ManagementFactory.html#MXBean">MXBean</a>
 42  * that can be obtained by calling
 43  * the {@link ManagementFactory#getThreadMXBean} method or
 44  * from the {@link ManagementFactory#getPlatformMBeanServer
 45  * platform MBeanServer} method.
 46  *
 47  * <p>The {@code ObjectName} for uniquely identifying the MXBean for
 48  * the thread system within an MBeanServer is:
 49  * <blockquote>
 50  *    {@link ManagementFactory#THREAD_MXBEAN_NAME
 51  *           java.lang:type=Threading}
 52  * </blockquote>
 53  *
 54  * It can be obtained by calling the
 55  * {@link PlatformManagedObject#getObjectName} method.
 56  *
 57  * <h2>Thread ID</h2>
 58  * Thread ID is a positive long value returned by calling the
 59  * {@link java.lang.Thread#getId} method for a thread.
 60  * The thread ID is unique during its lifetime.  When a thread
 61  * is terminated, this thread ID may be reused.
 62  *
 63  * <p> Some methods in this interface take a thread ID or an array
 64  * of thread IDs as the input parameter and return per-thread information.
 65  *
 66  * <h2>Thread CPU time</h2>
 67  * A Java virtual machine implementation may support measuring
 68  * the CPU time for the current thread, for any thread, or for no threads.
 69  *
 70  * <p>
 71  * The {@link #isThreadCpuTimeSupported} method can be used to determine
 72  * if a Java virtual machine supports measuring of the CPU time for any
 73  * thread.  The {@link #isCurrentThreadCpuTimeSupported} method can
 74  * be used to determine if a Java virtual machine supports measuring of
 75  * the CPU time for the current  thread.
 76  * A Java virtual machine implementation that supports CPU time measurement
 77  * for any thread will also support that for the current thread.
 78  *
 79  * <p> The CPU time provided by this interface has nanosecond precision
 80  * but not necessarily nanosecond accuracy.
 81  *
 82  * <p>
 83  * A Java virtual machine may disable CPU time measurement
 84  * by default.
 85  * The {@link #isThreadCpuTimeEnabled} and {@link #setThreadCpuTimeEnabled}
 86  * methods can be used to test if CPU time measurement is enabled
 87  * and to enable/disable this support respectively.
 88  * Enabling thread CPU measurement could be expensive in some
 89  * Java virtual machine implementations.
 90  *
 91  * <h2>Thread Contention Monitoring</h2>
 92  * Some Java virtual machines may support thread contention monitoring.
 93  * When thread contention monitoring is enabled, the accumulated elapsed
 94  * time that the thread has blocked for synchronization or waited for
 95  * notification will be collected and returned in the
 96  * <a href="ThreadInfo.html#SyncStats">{@code ThreadInfo}</a> object.
 97  * <p>
 98  * The {@link #isThreadContentionMonitoringSupported} method can be used to
 99  * determine if a Java virtual machine supports thread contention monitoring.
100  * The thread contention monitoring is disabled by default.  The
101  * {@link #setThreadContentionMonitoringEnabled} method can be used to enable
102  * thread contention monitoring.
103  *
104  * <h2>Synchronization Information and Deadlock Detection</h2>
105  * Some Java virtual machines may support monitoring of
106  * {@linkplain #isObjectMonitorUsageSupported object monitor usage} and
107  * {@linkplain #isSynchronizerUsageSupported ownable synchronizer usage}.
108  * The {@link #getThreadInfo(long[], boolean, boolean)} and
109  * {@link #dumpAllThreads} methods can be used to obtain the thread stack trace
110  * and synchronization information including which
111  * {@linkplain LockInfo <i>lock</i>} a thread is blocked to
112  * acquire or waiting on and which locks the thread currently owns.
113  * <p>
114  * The {@code ThreadMXBean} interface provides the
115  * {@link #findMonitorDeadlockedThreads} and
116  * {@link #findDeadlockedThreads} methods to find deadlocks in
117  * the running application.
118  *
119  * @see ManagementFactory#getPlatformMXBeans(Class)
120  * @see <a href="../../../javax/management/package-summary.html">
121  *      JMX Specification.</a>
122  * @see <a href="package-summary.html#examples">
123  *      Ways to Access MXBeans</a>
124  *
125  * @author  Mandy Chung
126  * @since   1.5
127  */
128 
129 public interface ThreadMXBean extends PlatformManagedObject {
130     /**
131      * Returns the current number of live platform threads including both
132      * daemon and non-daemon threads.
133      * The count does not include virtual threads.
134      *
135      * @return the current number of live platform threads.
136      */
137     public int getThreadCount();
138 
139     /**
140      * Returns the peak live platform thread count since the Java virtual
141      * machine started or peak was reset.
142      * The count does not include virtual threads.
143      *
144      * @return the peak live platform thread count.
145      */
146     public int getPeakThreadCount();
147 
148     /**
149      * Returns the total number of platform threads created and also started
150      * since the Java virtual machine started.
151      * The count does not include virtual threads.
152      *
153      * @return the total number of platform threads started.
154      */
155     public long getTotalStartedThreadCount();
156 
157     /**
158      * Returns the current number of live platform threads that are daemon threads.
159      * The count does not include virtual threads.
160      *
161      * @return the current number of live platform threads that are daemon threads.
162      */
163     public int getDaemonThreadCount();
164 
165     /**
166      * Returns the threadIDs of all live platform threads.
167      * The thread IDs of virtual threads are not included.
168      * Some threads included in the returned array
169      * may have been terminated when this method returns.
170      *
171      * @return an array of {@code long}, each is a thread ID.
172      *
173      * @throws SecurityException if a security manager
174      *         exists and the caller does not have
175      *         ManagementPermission("monitor").
176      */
177     public long[] getAllThreadIds();
178 
179     /**
180      * Returns the thread info for a thread of the specified
181      * {@code id} with no stack trace.
182      * This method is equivalent to calling:
183      * <blockquote>
184      *   {@link #getThreadInfo(long, int) getThreadInfo(id, 0);}
185      * </blockquote>
186      *
187      * <p>
188      * This method returns a {@code ThreadInfo} object representing
189      * the thread information for the thread of the specified ID.
190      * The stack trace, locked monitors, and locked synchronizers
191      * in the returned {@code ThreadInfo} object will
192      * be empty.
193      *
194      * If a thread of the given ID is a virtual thread, is not alive, or does
195      * not exist, then this method will return {@code null}. A thread is
196      * alive if it has been started and has not yet terminated.
197      *
198      * <p>
199      * <b>MBeanServer access</b>:<br>
200      * The mapped type of {@code ThreadInfo} is
201      * {@code CompositeData} with attributes as specified in the
202      * {@link ThreadInfo#from ThreadInfo.from} method.
203      *
204      * @param id the thread ID of the thread. Must be positive.
205      *
206      * @return a {@link ThreadInfo} object for the thread of the given ID
207      * with no stack trace, no locked monitor and no synchronizer info;
208      * {@code null} if the thread of the given ID is a virtual thread,
209      * is not alive, or it does not exist.
210      *
211      * @throws IllegalArgumentException if {@code id <= 0}.
212      * @throws SecurityException if a security manager
213      *         exists and the caller does not have
214      *         ManagementPermission("monitor").
215      */
216     public ThreadInfo getThreadInfo(long id);
217 
218     /**
219      * Returns the thread info for each thread
220      * whose ID is in the input array {@code ids} with no stack trace.
221      * This method is equivalent to calling:
222      * <blockquote><pre>
223      *   {@link #getThreadInfo(long[], int) getThreadInfo}(ids, 0);
224      * </pre></blockquote>
225      *
226      * <p>
227      * This method returns an array of the {@code ThreadInfo} objects.
228      * The stack trace, locked monitors, and locked synchronizers
229      * in each {@code ThreadInfo} object will be empty.
230      *
231      * If a thread of the given ID is a virtual thread, is not alive, or does
232      * not exist, the corresponding element in the returned array will
233      * contain {@code null}.  A thread is alive if
234      * it has been started and has not yet terminated.
235      *
236      * <p>
237      * <b>MBeanServer access</b>:<br>
238      * The mapped type of {@code ThreadInfo} is
239      * {@code CompositeData} with attributes as specified in the
240      * {@link ThreadInfo#from ThreadInfo.from} method.
241      *
242      * @param ids an array of thread IDs.
243      * @return an array of the {@link ThreadInfo} objects, each containing
244      * information about a thread whose ID is in the corresponding
245      * element of the input array of IDs
246      * with no stack trace, no locked monitor and no synchronizer info.
247      *
248      * @throws IllegalArgumentException if any element in the input array
249      *         {@code ids} is {@code <= 0}.
250      * @throws SecurityException if a security manager
251      *         exists and the caller does not have
252      *         ManagementPermission("monitor").
253      */
254     public ThreadInfo[] getThreadInfo(long[] ids);
255 
256     /**
257      * Returns a thread info for a thread of the specified {@code id},
258      * with stack trace of a specified number of stack trace elements.
259      * The {@code maxDepth} parameter indicates the maximum number of
260      * {@link StackTraceElement} to be retrieved from the stack trace.
261      * If {@code maxDepth == Integer.MAX_VALUE}, the entire stack trace of
262      * the thread will be dumped.
263      * If {@code maxDepth == 0}, no stack trace of the thread
264      * will be dumped.
265      * This method does not obtain the locked monitors and locked
266      * synchronizers of the thread.
267      * <p>
268      * When the Java virtual machine has no stack trace information
269      * about a thread or {@code maxDepth == 0},
270      * the stack trace in the
271      * {@code ThreadInfo} object will be an empty array of
272      * {@code StackTraceElement}.
273      *
274      * <p>
275      * If a thread of the given ID is a virtual thread, is not alive, or does
276      * not exist, this method will return {@code null}. A thread is alive if
277      * it has been started and has not yet terminated.
278      *
279      * <p>
280      * <b>MBeanServer access</b>:<br>
281      * The mapped type of {@code ThreadInfo} is
282      * {@code CompositeData} with attributes as specified in the
283      * {@link ThreadInfo#from ThreadInfo.from} method.
284      *
285      * @param id the thread ID of the thread. Must be positive.
286      * @param maxDepth the maximum number of entries in the stack trace
287      * to be dumped. {@code Integer.MAX_VALUE} could be used to request
288      * the entire stack to be dumped.
289      *
290      * @return a {@link ThreadInfo} of the thread of the given ID
291      * with no locked monitor and synchronizer info.
292      * {@code null} if the thread of the given ID is a virtual thread, is
293      * not alive or it does not exist.
294      *
295      * @throws IllegalArgumentException if {@code id <= 0}.
296      * @throws IllegalArgumentException if {@code maxDepth is negative}.
297      * @throws SecurityException if a security manager
298      *         exists and the caller does not have
299      *         ManagementPermission("monitor").
300      *
301      */
302     public ThreadInfo getThreadInfo(long id, int maxDepth);
303 
304     /**
305      * Returns the thread info for each thread
306      * whose ID is in the input array {@code ids},
307      * with stack trace of a specified number of stack trace elements.
308      * The {@code maxDepth} parameter indicates the maximum number of
309      * {@link StackTraceElement} to be retrieved from the stack trace.
310      * If {@code maxDepth == Integer.MAX_VALUE}, the entire stack trace of
311      * the thread will be dumped.
312      * If {@code maxDepth == 0}, no stack trace of the thread
313      * will be dumped.
314      * This method does not obtain the locked monitors and locked
315      * synchronizers of the threads.
316      * <p>
317      * When the Java virtual machine has no stack trace information
318      * about a thread or {@code maxDepth == 0},
319      * the stack trace in the
320      * {@code ThreadInfo} object will be an empty array of
321      * {@code StackTraceElement}.
322      * <p>
323      * This method returns an array of the {@code ThreadInfo} objects,
324      * each is the thread information about the thread with the same index
325      * as in the {@code ids} array.
326      * If a thread of the given ID is a virtual thread, is not alive, or does
327      * not exist, {@code null} will be set in the corresponding element
328      * in the returned array.  A thread is alive if
329      * it has been started and has not yet terminated.
330      *
331      * <p>
332      * <b>MBeanServer access</b>:<br>
333      * The mapped type of {@code ThreadInfo} is
334      * {@code CompositeData} with attributes as specified in the
335      * {@link ThreadInfo#from ThreadInfo.from} method.
336      *
337      * @param ids an array of thread IDs
338      * @param maxDepth the maximum number of entries in the stack trace
339      * to be dumped. {@code Integer.MAX_VALUE} could be used to request
340      * the entire stack to be dumped.
341      *
342      * @return an array of the {@link ThreadInfo} objects, each containing
343      * information about a thread whose ID is in the corresponding
344      * element of the input array of IDs with no locked monitor and
345      * synchronizer info.
346      *
347      * @throws IllegalArgumentException if {@code maxDepth is negative}.
348      * @throws IllegalArgumentException if any element in the input array
349      *      {@code ids} is {@code <= 0}.
350      * @throws SecurityException if a security manager
351      *         exists and the caller does not have
352      *         ManagementPermission("monitor").
353      *
354      */
355     public ThreadInfo[] getThreadInfo(long[] ids, int maxDepth);
356 
357     /**
358      * Tests if the Java virtual machine supports thread contention monitoring.
359      *
360      * @return
361      *   {@code true}
362      *     if the Java virtual machine supports thread contention monitoring;
363      *   {@code false} otherwise.
364      */
365     public boolean isThreadContentionMonitoringSupported();
366 
367     /**
368      * Tests if thread contention monitoring is enabled.
369      *
370      * @return {@code true} if thread contention monitoring is enabled;
371      *         {@code false} otherwise.
372      *
373      * @throws UnsupportedOperationException if the Java virtual
374      * machine does not support thread contention monitoring.
375      *
376      * @see #isThreadContentionMonitoringSupported
377      */
378     public boolean isThreadContentionMonitoringEnabled();
379 
380     /**
381      * Enables or disables thread contention monitoring.
382      * Thread contention monitoring is disabled by default.
383      *
384      * @param enable {@code true} to enable;
385      *               {@code false} to disable.
386      *
387      * @throws UnsupportedOperationException if the Java
388      * virtual machine does not support thread contention monitoring.
389      *
390      * @throws SecurityException if a security manager
391      *         exists and the caller does not have
392      *         ManagementPermission("control").
393      *
394      * @see #isThreadContentionMonitoringSupported
395      */
396     public void setThreadContentionMonitoringEnabled(boolean enable);
397 
398     /**
399      * Returns the total CPU time for the current thread in nanoseconds.
400      * The returned value is of nanoseconds precision but
401      * not necessarily nanoseconds accuracy.
402      * If the implementation distinguishes between user mode time and system
403      * mode time, the returned CPU time is the amount of time that
404      * the current thread has executed in user mode or system mode.
405      *
406      * <p>
407      * This is a convenience method for local management use and is
408      * equivalent to calling:
409      * <blockquote><pre>
410      *   {@link #getThreadCpuTime getThreadCpuTime}(Thread.currentThread().getId());
411      * </pre></blockquote>
412      *
413      * @return the total CPU time for the current thread if CPU time
414      * measurement is enabled; {@code -1} otherwise.
415      *
416      * @throws UnsupportedOperationException if the Java
417      * virtual machine does not support CPU time measurement for
418      * the current thread.
419      *
420      * @see #getCurrentThreadUserTime
421      * @see #isCurrentThreadCpuTimeSupported
422      * @see #isThreadCpuTimeEnabled
423      * @see #setThreadCpuTimeEnabled
424      */
425     public long getCurrentThreadCpuTime();
426 
427     /**
428      * Returns the CPU time that the current thread has executed
429      * in user mode in nanoseconds.
430      * The returned value is of nanoseconds precision but
431      * not necessarily nanoseconds accuracy.
432      *
433      * <p>
434      * This is a convenience method for local management use and is
435      * equivalent to calling:
436      * <blockquote><pre>
437      *   {@link #getThreadUserTime getThreadUserTime}(Thread.currentThread().getId());
438      * </pre></blockquote>
439      *
440      * @return the user-level CPU time for the current thread if CPU time
441      * measurement is enabled; {@code -1} otherwise.
442      *
443      * @throws UnsupportedOperationException if the Java
444      * virtual machine does not support CPU time measurement for
445      * the current thread.
446      *
447      * @see #getCurrentThreadCpuTime
448      * @see #isCurrentThreadCpuTimeSupported
449      * @see #isThreadCpuTimeEnabled
450      * @see #setThreadCpuTimeEnabled
451      */
452     public long getCurrentThreadUserTime();
453 
454     /**
455      * Returns the total CPU time for a thread of the specified ID in nanoseconds.
456      * The returned value is of nanoseconds precision but
457      * not necessarily nanoseconds accuracy.
458      * If the implementation distinguishes between user mode time and system
459      * mode time, the returned CPU time is the amount of time that
460      * the thread has executed in user mode or system mode.
461      *
462      * <p>
463      * If the thread of the specified ID is a virtual thread, is not alive or
464      * does not exist, this method returns {@code -1}. If CPU time measurement
465      * is disabled, this method returns {@code -1}.
466      * A thread is alive if it has been started and has not yet terminated.
467      * <p>
468      * If CPU time measurement is enabled after the thread has started,
469      * the Java virtual machine implementation may choose any time up to
470      * and including the time that the capability is enabled as the point
471      * where CPU time measurement starts.
472      *
473      * @param id the thread ID of a thread
474      * @return the total CPU time for a thread of the specified ID
475      * if the thread of the specified ID exists, the thread is alive,
476      * and CPU time measurement is enabled;
477      * {@code -1} otherwise.
478      *
479      * @throws IllegalArgumentException if {@code id <= 0}.
480      * @throws UnsupportedOperationException if the Java
481      * virtual machine does not support CPU time measurement for
482      * other threads.
483      *
484      * @see #getThreadUserTime
485      * @see #isThreadCpuTimeSupported
486      * @see #isThreadCpuTimeEnabled
487      * @see #setThreadCpuTimeEnabled
488      */
489     public long getThreadCpuTime(long id);
490 
491     /**
492      * Returns the CPU time that a thread of the specified ID
493      * has executed in user mode in nanoseconds.
494      * The returned value is of nanoseconds precision but
495      * not necessarily nanoseconds accuracy.
496      *
497      * <p>
498      * If the thread of the specified ID is a virtual thread, is not alive, or
499      * does not exist, this method returns {@code -1}. If CPU time measurement
500      * is disabled, this method returns {@code -1}.
501      * A thread is alive if it has been started and has not yet terminated.
502      * <p>
503      * If CPU time measurement is enabled after the thread has started,
504      * the Java virtual machine implementation may choose any time up to
505      * and including the time that the capability is enabled as the point
506      * where CPU time measurement starts.
507      *
508      * @param id the thread ID of a thread
509      * @return the user-level CPU time for a thread of the specified ID
510      * if the thread of the specified ID exists, the thread is alive,
511      * and CPU time measurement is enabled;
512      * {@code -1} otherwise.
513      *
514      * @throws IllegalArgumentException if {@code id <= 0}.
515      * @throws UnsupportedOperationException if the Java
516      * virtual machine does not support CPU time measurement for
517      * other threads.
518      *
519      * @see #getThreadCpuTime
520      * @see #isThreadCpuTimeSupported
521      * @see #isThreadCpuTimeEnabled
522      * @see #setThreadCpuTimeEnabled
523      */
524     public long getThreadUserTime(long id);
525 
526     /**
527      * Tests if the Java virtual machine implementation supports CPU time
528      * measurement for any thread.
529      * A Java virtual machine implementation that supports CPU time
530      * measurement for any thread will also support CPU time
531      * measurement for the current thread.
532      *
533      * @return
534      *   {@code true}
535      *     if the Java virtual machine supports CPU time
536      *     measurement for any thread;
537      *   {@code false} otherwise.
538      */
539     public boolean isThreadCpuTimeSupported();
540 
541     /**
542      * Tests if the Java virtual machine supports CPU time
543      * measurement for the current thread.
544      * This method returns {@code true} if {@link #isThreadCpuTimeSupported}
545      * returns {@code true}.
546      *
547      * @return
548      *   {@code true}
549      *     if the Java virtual machine supports CPU time
550      *     measurement for current thread;
551      *   {@code false} otherwise.
552      */
553     public boolean isCurrentThreadCpuTimeSupported();
554 
555     /**
556      * Tests if thread CPU time measurement is enabled.
557      *
558      * @return {@code true} if thread CPU time measurement is enabled;
559      *         {@code false} otherwise.
560      *
561      * @throws UnsupportedOperationException if the Java virtual
562      * machine does not support CPU time measurement for other threads
563      * nor for the current thread.
564      *
565      * @see #isThreadCpuTimeSupported
566      * @see #isCurrentThreadCpuTimeSupported
567      */
568     public boolean isThreadCpuTimeEnabled();
569 
570     /**
571      * Enables or disables thread CPU time measurement.  The default
572      * is platform dependent.
573      *
574      * @param enable {@code true} to enable;
575      *               {@code false} to disable.
576      *
577      * @throws UnsupportedOperationException if the Java
578      * virtual machine does not support CPU time measurement for
579      * any threads nor for the current thread.
580      *
581      * @throws SecurityException if a security manager
582      *         exists and the caller does not have
583      *         ManagementPermission("control").
584      *
585      * @see #isThreadCpuTimeSupported
586      * @see #isCurrentThreadCpuTimeSupported
587      */
588     public void setThreadCpuTimeEnabled(boolean enable);
589 
590     /**
591      * Finds cycles of threads that are in deadlock waiting to acquire
592      * object monitors. That is, threads that are blocked waiting to enter a
593      * synchronization block or waiting to reenter a synchronization block
594      * after an {@link Object#wait Object.wait} call,
595      * where each thread owns one monitor while
596      * trying to obtain another monitor already held by another thread
597      * in a cycle.
598      * <p>
599      * More formally, a thread is <em>monitor deadlocked</em> if it is
600      * part of a cycle in the relation "is waiting for an object monitor
601      * owned by".  In the simplest case, thread A is blocked waiting
602      * for a monitor owned by thread B, and thread B is blocked waiting
603      * for a monitor owned by thread A.
604      * <p>
605      * This method is designed for troubleshooting use, but not for
606      * synchronization control.  It might be an expensive operation.
607      * Its behavior with cycles involving virtual threads is not defined
608      * in this release.
609      * <p>
610      * This method finds deadlocks involving only object monitors.
611      * To find deadlocks involving both object monitors and
612      * <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>,
613      * the {@link #findDeadlockedThreads findDeadlockedThreads} method
614      * should be used.
615      *
616      * @return an array of IDs of the threads that are monitor
617      * deadlocked, if any; {@code null} otherwise.
618      *
619      * @throws SecurityException if a security manager
620      *         exists and the caller does not have
621      *         ManagementPermission("monitor").
622      *
623      * @see #findDeadlockedThreads
624      */
625     public long[] findMonitorDeadlockedThreads();
626 
627     /**
628      * Resets the peak thread count to the current number of
629      * live threads.
630      *
631      * @throws SecurityException if a security manager
632      *         exists and the caller does not have
633      *         ManagementPermission("control").
634      *
635      * @see #getPeakThreadCount
636      * @see #getThreadCount
637      */
638     public void resetPeakThreadCount();
639 
640     /**
641      * Finds cycles of threads that are in deadlock waiting to acquire
642      * object monitors or
643      * <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>.
644      *
645      * Threads are <em>deadlocked</em> in a cycle waiting for a lock of
646      * these two types if each thread owns one lock while
647      * trying to acquire another lock already held
648      * by another thread in the cycle.
649      * <p>
650      * This method is designed for troubleshooting use, but not for
651      * synchronization control.  It might be an expensive operation.
652      * Its behavior with cycles involving virtual threads is not defined
653      * in this release.
654      *
655      * @return an array of IDs of the threads that are
656      * deadlocked waiting for object monitors or ownable synchronizers, if any;
657      * {@code null} otherwise.
658      *
659      * @throws SecurityException if a security manager
660      *         exists and the caller does not have
661      *         ManagementPermission("monitor").
662      * @throws UnsupportedOperationException if the Java virtual
663      * machine does not support monitoring of ownable synchronizer usage.
664      *
665      * @see #isSynchronizerUsageSupported
666      * @see #findMonitorDeadlockedThreads
667      * @since 1.6
668      */
669     public long[] findDeadlockedThreads();
670 
671     /**
672      * Tests if the Java virtual machine supports monitoring of
673      * object monitor usage.
674      *
675      * @return
676      *   {@code true}
677      *     if the Java virtual machine supports monitoring of
678      *     object monitor usage;
679      *   {@code false} otherwise.
680      *
681      * @see #dumpAllThreads
682      * @since 1.6
683      */
684     public boolean isObjectMonitorUsageSupported();
685 
686     /**
687      * Tests if the Java virtual machine supports monitoring of
688      * <a href="LockInfo.html#OwnableSynchronizer">
689      * ownable synchronizer</a> usage.
690      *
691      * @return
692      *   {@code true}
693      *     if the Java virtual machine supports monitoring of ownable
694      *     synchronizer usage;
695      *   {@code false} otherwise.
696      *
697      * @see #dumpAllThreads
698      * @since 1.6
699      */
700     public boolean isSynchronizerUsageSupported();
701 
702     /**
703      * Returns the thread info for each thread
704      * whose ID is in the input array {@code ids},
705      * with stack trace and synchronization information.
706      * This is equivalent to calling:
707      * <blockquote>
708      * {@link #getThreadInfo(long[], boolean, boolean, int)
709      * getThreadInfo(ids, lockedMonitors, lockedSynchronizers, Integer.MAX_VALUE)}
710      * </blockquote>
711      *
712      * @param  ids an array of thread IDs.
713      * @param  lockedMonitors if {@code true}, retrieves all locked monitors.
714      * @param  lockedSynchronizers if {@code true}, retrieves all locked
715      *             ownable synchronizers.
716      *
717      * @return an array of the {@link ThreadInfo} objects, each containing
718      * information about a thread whose ID is in the corresponding
719      * element of the input array of IDs.
720      *
721      * @throws SecurityException if a security manager
722      *         exists and the caller does not have
723      *         ManagementPermission("monitor").
724      * @throws UnsupportedOperationException
725      *         <ul>
726      *           <li>if {@code lockedMonitors} is {@code true} but
727      *               the Java virtual machine does not support monitoring
728      *               of {@linkplain #isObjectMonitorUsageSupported
729      *               object monitor usage}; or</li>
730      *           <li>if {@code lockedSynchronizers} is {@code true} but
731      *               the Java virtual machine does not support monitoring
732      *               of {@linkplain #isSynchronizerUsageSupported
733      *               ownable synchronizer usage}.</li>
734      *         </ul>
735      *
736      * @see #isObjectMonitorUsageSupported
737      * @see #isSynchronizerUsageSupported
738      *
739      * @since 1.6
740      */
741     public ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors,
742                                       boolean lockedSynchronizers);
743 
744     /**
745      * Returns the thread info for each thread whose ID
746      * is in the input array {@code ids},
747      * with stack trace of the specified maximum number of elements
748      * and synchronization information.
749      * If {@code maxDepth == 0}, no stack trace of the thread
750      * will be dumped.
751      *
752      * <p>
753      * This method obtains a snapshot of the thread information
754      * for each thread including:
755      * <ul>
756      *    <li>stack trace of the specified maximum number of elements,</li>
757      *    <li>the object monitors currently locked by the thread
758      *        if {@code lockedMonitors} is {@code true}, and</li>
759      *    <li>the <a href="LockInfo.html#OwnableSynchronizer">
760      *        ownable synchronizers</a> currently locked by the thread
761      *        if {@code lockedSynchronizers} is {@code true}.</li>
762      * </ul>
763      * <p>
764      * This method returns an array of the {@code ThreadInfo} objects,
765      * each is the thread information about the thread with the same index
766      * as in the {@code ids} array.
767      * If a thread of the given ID is a virtual thread, is not alive, or does
768      * not exist, {@code null} will be set in the corresponding element
769      * in the returned array.  A thread is alive if
770      * it has been started and has not yet terminated.
771      * <p>
772      * If a thread does not lock any object monitor or {@code lockedMonitors}
773      * is {@code false}, the returned {@code ThreadInfo} object will have an
774      * empty {@code MonitorInfo} array.  Similarly, if a thread does not
775      * lock any synchronizer or {@code lockedSynchronizers} is {@code false},
776      * the returned {@code ThreadInfo} object
777      * will have an empty {@code LockInfo} array.
778      *
779      * <p>
780      * When both {@code lockedMonitors} and {@code lockedSynchronizers}
781      * parameters are {@code false}, it is equivalent to calling:
782      * <blockquote><pre>
783      *     {@link #getThreadInfo(long[], int)  getThreadInfo(ids, maxDepth)}
784      * </pre></blockquote>
785      *
786      * <p>
787      * This method is designed for troubleshooting use, but not for
788      * synchronization control.  It might be an expensive operation.
789      *
790      * <p>
791      * <b>MBeanServer access</b>:<br>
792      * The mapped type of {@code ThreadInfo} is
793      * {@code CompositeData} with attributes as specified in the
794      * {@link ThreadInfo#from ThreadInfo.from} method.
795      *
796      * @implSpec The default implementation throws
797      * {@code UnsupportedOperationException}.
798      *
799      * @param  ids an array of thread IDs.
800      * @param  lockedMonitors if {@code true}, retrieves all locked monitors.
801      * @param  lockedSynchronizers if {@code true}, retrieves all locked
802      *             ownable synchronizers.
803      * @param  maxDepth indicates the maximum number of
804      * {@link StackTraceElement} to be retrieved from the stack trace.
805      *
806      * @return an array of the {@link ThreadInfo} objects, each containing
807      * information about a thread whose ID is in the corresponding
808      * element of the input array of IDs.
809      *
810      * @throws IllegalArgumentException if {@code maxDepth} is negative.
811      * @throws SecurityException if a security manager
812      *         exists and the caller does not have
813      *         ManagementPermission("monitor").
814      * @throws UnsupportedOperationException
815      *         <ul>
816      *           <li>if {@code lockedMonitors} is {@code true} but
817      *               the Java virtual machine does not support monitoring
818      *               of {@linkplain #isObjectMonitorUsageSupported
819      *               object monitor usage}; or</li>
820      *           <li>if {@code lockedSynchronizers} is {@code true} but
821      *               the Java virtual machine does not support monitoring
822      *               of {@linkplain #isSynchronizerUsageSupported
823      *               ownable synchronizer usage}.</li>
824      *         </ul>
825      *
826      * @see #isObjectMonitorUsageSupported
827      * @see #isSynchronizerUsageSupported
828      *
829      * @since 10
830      */
831 
832     public default ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors,
833                                               boolean lockedSynchronizers, int maxDepth) {
834         throw new UnsupportedOperationException();
835     }
836 
837     /**
838      * Returns the thread info for all live threads with stack trace
839      * and synchronization information.
840      * The thread IDs of virtual threads are not included.
841      * This method is equivalent to calling:
842      * <blockquote>
843      * {@link #dumpAllThreads(boolean, boolean, int)
844      * dumpAllThreads(lockedMonitors, lockedSynchronizers, Integer.MAX_VALUE)}
845      * </blockquote>
846      *
847      * @param  lockedMonitors if {@code true}, dump all locked monitors.
848      * @param  lockedSynchronizers if {@code true}, dump all locked
849      *             ownable synchronizers.
850      *
851      * @return an array of {@link ThreadInfo} for all live threads.
852      *
853      * @throws SecurityException if a security manager
854      *         exists and the caller does not have
855      *         ManagementPermission("monitor").
856      * @throws UnsupportedOperationException
857      *         <ul>
858      *           <li>if {@code lockedMonitors} is {@code true} but
859      *               the Java virtual machine does not support monitoring
860      *               of {@linkplain #isObjectMonitorUsageSupported
861      *               object monitor usage}; or</li>
862      *           <li>if {@code lockedSynchronizers} is {@code true} but
863      *               the Java virtual machine does not support monitoring
864      *               of {@linkplain #isSynchronizerUsageSupported
865      *               ownable synchronizer usage}.</li>
866      *         </ul>
867      *
868      * @see #isObjectMonitorUsageSupported
869      * @see #isSynchronizerUsageSupported
870      *
871      * @since 1.6
872      */
873     public ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers);
874 
875 
876     /**
877      * Returns the thread info for all live threads
878      * with stack trace of the specified maximum number of elements
879      * and synchronization information.
880      * if {@code maxDepth == 0}, no stack trace of the thread
881      * will be dumped.
882      * The thread IDs of virtual threads are not included.
883      * Some threads included in the returned array
884      * may have been terminated when this method returns.
885      *
886      * <p>
887      * This method returns an array of {@link ThreadInfo} objects
888      * as specified in the {@link #getThreadInfo(long[], boolean, boolean, int)}
889      * method.
890      *
891      * @implSpec The default implementation throws
892      * {@code UnsupportedOperationException}.
893      *
894      * @param  lockedMonitors if {@code true}, dump all locked monitors.
895      * @param  lockedSynchronizers if {@code true}, dump all locked
896      *             ownable synchronizers.
897      * @param  maxDepth indicates the maximum number of
898      * {@link StackTraceElement} to be retrieved from the stack trace.
899      *
900      * @return an array of {@link ThreadInfo} for all live threads.
901      *
902      * @throws IllegalArgumentException if {@code maxDepth} is negative.
903      * @throws SecurityException if a security manager
904      *         exists and the caller does not have
905      *         ManagementPermission("monitor").
906      * @throws UnsupportedOperationException
907      *         <ul>
908      *           <li>if {@code lockedMonitors} is {@code true} but
909      *               the Java virtual machine does not support monitoring
910      *               of {@linkplain #isObjectMonitorUsageSupported
911      *               object monitor usage}; or</li>
912      *           <li>if {@code lockedSynchronizers} is {@code true} but
913      *               the Java virtual machine does not support monitoring
914      *               of {@linkplain #isSynchronizerUsageSupported
915      *               ownable synchronizer usage}.</li>
916      *         </ul>
917      *
918      * @see #isObjectMonitorUsageSupported
919      * @see #isSynchronizerUsageSupported
920      *
921      * @since 10
922      */
923     public default ThreadInfo[] dumpAllThreads(boolean lockedMonitors,
924                                                boolean lockedSynchronizers, int maxDepth) {
925         throw new UnsupportedOperationException();
926     }
927 }
--- EOF ---