ThreadMXBean


1   /*
2    * @(#)ThreadMXBean.java    1.14 04/04/29 
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.lang.management;
9   
10  /**
11   * The management interface for the thread system of
12   * the Java virtual machine.
13   *
14   * <p> A Java virtual machine has a single instance of the implementation
15   * class of this interface.  This instance implementing this interface is
16   * an <a HREF="ManagementFactory.html#MXBean">MXBean</a>
17   * that can be obtained by calling
18   * the {@link ManagementFactory#getThreadMXBean} method or
19   * from the {@link ManagementFactory#getPlatformMBeanServer
20   * platform <tt>MBeanServer</tt>} method.
21   *
22   * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for
23   * the thread system within an MBeanServer is:
24   * <blockquote>
25   *    {@link ManagementFactory#THREAD_MXBEAN_NAME 
26   *           <tt>java.lang:type=Threading</tt>}
27   * </blockquote>
28   *
29   * <h4>Thread ID</h4>
30   * Thread ID is a positive long value returned by calling the
31   * {@link java.lang.Thread#getId} method for a thread.
32   * The thread ID is unique during its lifetime.  When a thread 
33   * is terminated, this thread ID may be reused.
34   *
35   * <p> Some methods in this interface take a thread ID or an array
36   * of thread IDs as the input parameter and return per-thread information.
37   *
38   * <h4>Thread CPU time</h4>
39   * A Java virtual machine implementation may support measuring
40   * the CPU time for the current thread, for any thread, or for no threads.
41   *
42   * <p>
43   * The {@link #isThreadCpuTimeSupported} method can be used to determine
44   * if a Java virtual machine supports measuring of the CPU time for any 
45   * thread.  The {@link #isCurrentThreadCpuTimeSupported} method can 
46   * be used to determine if a Java virtual machine supports measuring of 
47   * the CPU time for the current  thread.
48   * A Java virtual machine implementation that supports CPU time measurement 
49   * for any thread will also support that for the current thread.
50   *
51   * <p> The CPU time provided by this interface has nanosecond precision
52   * but not necessarily nanosecond accuracy.
53   *
54   * <p>
55   * A Java virtual machine may disable CPU time measurement
56   * by default.
57   * The {@link #isThreadCpuTimeEnabled} and {@link #setThreadCpuTimeEnabled}
58   * methods can be used to test if CPU time measurement is enabled
59   * and to enable/disable this support respectively.
60   * Enabling thread CPU measurement could be expensive in some
61   * Java virtual machine implementations.
62   *
63   * <h4>Thread Contention Monitoring</h4>
64   * Some Java virtual machines may support thread contention monitoring.
65   * The {@link #isThreadContentionMonitoringSupported} method can be used to 
66   * determine if a Java virtual machine supports thread contention monitoring.
67   *
68   * The thread contention monitoring is disabled by default.  The 
69   * {@link #setThreadContentionMonitoringEnabled} method can be used to enable
70   * thread contention monitoring.
71   *
72   * @see <a HREF="../../../javax/management/package-summary.html">
73   *      JMX Specification.</a>
74   * @see <a HREF="package-summary.html#examples">
75   *      Ways to Access MXBeans</a>
76   *
77   * @author  Mandy Chung
78   * @version 1.14, 04/29/04
79   * @since   1.5
80   */
81  public interface ThreadMXBean {
82      /**
83       * Returns the current number of live threads including both 
84       * daemon and non-daemon threads.
85       *
86       * @return the current number of live threads.
87       */
88      public int getThreadCount();
89      
90      /**
91       * Returns the peak live thread count since the Java virtual machine 
92       * started or peak was reset.
93       *
94       * @return the peak live thread count.
95       */
96      public int getPeakThreadCount();
97      
98      /**
99       * Returns the total number of threads created and also started 
100      * since the Java virtual machine started.
101      *
102      * @return the total number of threads started.
103      */
104     public long getTotalStartedThreadCount();  
105 
106     /**
107      * Returns the current number of live daemon threads.
108      *
109      * @return the current number of live daemon threads.
110      */
111     public int getDaemonThreadCount();
112 
113     /**
114      * Returns all live thread IDs. 
115      * Some threads included in the returned array
116      * may have been terminated when this method returns.
117      *
118      * @return an array of <tt>long</tt>, each is a thread ID.
119      *
120      * @throws java.lang.SecurityException if a security manager
121      *         exists and the caller does not have
122      *         ManagementPermission("monitor").
123      */
124     public long[] getAllThreadIds();
125 
126     /**
127      * Returns the thread info for a thread of the specified
128      * <tt>id</tt> with no stack trace. This method is equivalent to calling:
129      * <blockquote>
130      *   {@link #getThreadInfo(long, int) getThreadInfo(id, 0);}
131      * </blockquote>
132      *
133      * <p>
134      * This method returns a <tt>ThreadInfo</tt> object representing
135      * the thread information for the thread of the specified ID.
136      * The stack trace in the returned <tt>ThreadInfo</tt> object will
137      * be an empty array of <tt>StackTraceElement</tt>.
138      *
139      * If a thread of the given ID is not alive or does not exist,
140      * this method will return <tt>null</tt>.  A thread is alive if 
141      * it has been started and has not yet died.
142      *
143      * <p>
144      * <b>MBeanServer access</b>:<br>
145      * The mapped type of <tt>ThreadInfo</tt> is
146      * <tt>CompositeData</tt> with attributes as specified in
147      * {@link ThreadInfo#from ThreadInfo}.
148      *
149      * @param id the thread ID of the thread. Must be positive. 
150      *
151      * @return a {@link ThreadInfo} object for the thread of the given ID 
152      * with no stack trace;
153      * <tt>null</tt> if the thread of the given ID is not alive or
154      * it does not exist.
155      *
156      * @throws IllegalArgumentException if <tt>id &lt= 0</tt>.
157      * @throws java.lang.SecurityException if a security manager
158      *         exists and the caller does not have
159      *         ManagementPermission("monitor").
160      */
161     public ThreadInfo   getThreadInfo(long id);
162 
163     /**
164      * Returns the thread info for each thread 
165      * whose ID is in the input array <tt>ids</tt> with no
166      * stack trace. This method is equivalent to calling:
167      * <blockquote><pre>
168      *   {@link #getThreadInfo(long[], int) getThreadInfo}(ids, 0);
169      * </pre></blockquote>
170      *
171      * <p>
172      * This method returns an array of the <tt>ThreadInfo</tt> objects.
173      * The stack trace in each <tt>ThreadInfo</tt> object will
174      * be an empty array of <tt>StackTraceElement</tt>.
175      *
176      * If a thread of a given ID is not alive or does not exist,
177      * the corresponding element in the returned array will
178      * contain <tt>null</tt>.  A thread is alive if 
179      * it has been started and has not yet died.
180      *
181      * <p>
182      * <b>MBeanServer access</b>:<br>
183      * The mapped type of <tt>ThreadInfo</tt> is
184      * <tt>CompositeData</tt> with attributes as specified in
185      * {@link ThreadInfo#from ThreadInfo}.
186      *
187      * @param ids an array of thread IDs 
188      * @return an array of the {@link ThreadInfo} objects, each containing
189      * information about a thread whose ID is in the corresponding
190      * element of the input array of IDs. 
191      *
192      * @throws IllegalArgumentException if any element in the input array 
193      *      <tt>ids</tt> is <tt>&lt= 0</tt>.
194      * @throws java.lang.SecurityException if a security manager
195      *         exists and the caller does not have
196      *         ManagementPermission("monitor").
197      */
198     public ThreadInfo  [] getThreadInfo(long[] ids);
199 
200     /**
201      * Returns a thread info for a thread of 
202      * the specified <tt>id</tt>.
203      * The <tt>maxDepth</tt> parameter indicates the maximum number of 
204      * <tt>StackTraceElement</tt> to be retrieved from the stack trace.
205      * If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of 
206      * the thread will be dumped. 
207      * If <tt>maxDepth == 0</tt>, no stack trace of the thread 
208      * will be dumped. 
209      * <p>
210      * When the Java virtual machine has no stack trace information 
211      * about a thread or <tt>maxDepth == 0</tt>, 
212      * the stack trace in the 
213      * <tt>ThreadInfo</tt> object will be an empty array of 
214      * <tt>StackTraceElement</tt>.
215      *
216      * <p>
217      * If a thread of the given ID is not alive or does not exist, 
218      * this method will return <tt>null</tt>.  A thread is alive if 
219      * it has been started and has not yet died.
220      *
221      * <p>
222      * <b>MBeanServer access</b>:<br>
223      * The mapped type of <tt>ThreadInfo</tt> is
224      * <tt>CompositeData</tt> with attributes as specified in
225      * {@link ThreadInfo#from ThreadInfo}.
226      *
227      * @param id the thread ID of the thread. Must be positive. 
228      * @param maxDepth the maximum number of entries in the stack trace 
229      * to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request
230      * the entire stack to be dumped.
231      * 
232      * @return a {@link ThreadInfo} of the thread of the given ID.
233      * <tt>null</tt> if the thread of the given ID is not alive or
234      * it does not exist.
235      *
236      * @throws IllegalArgumentException if <tt>id &lt= 0</tt>.
237      * @throws IllegalArgumentException if <tt>maxDepth is negative</tt>.
238      * @throws java.lang.SecurityException if a security manager
239      *         exists and the caller does not have
240      *         ManagementPermission("monitor").
241      *
242      */
243     public ThreadInfo   getThreadInfo(long id, int maxDepth);
244 
245     /**
246      * Returns the thread info for each thread 
247      * whose ID is in the input array <tt>ids</tt>.
248      * The <tt>maxDepth</tt> parameter indicates the maximum number of 
249      * <tt>StackTraceElement</tt> to be retrieved from the stack trace.
250      * If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of 
251      * the thread will be dumped. 
252      * If <tt>maxDepth == 0</tt>, no stack trace of the thread 
253      * will be dumped.
254      * <p>
255      * When the Java virtual machine has no stack trace information 
256      * about a thread or <tt>maxDepth == 0</tt>, 
257      * the stack trace in the
258      * <tt>ThreadInfo</tt> object will be an empty array of 
259      * <tt>StackTraceElement</tt>.
260      * <p>
261      * This method returns an array of the <tt>ThreadInfo</tt> objects,
262      * each is the thread information about the thread with the same index
263      * as in the <tt>ids</tt> array.
264      * If a thread of the given ID is not alive or does not exist,
265      * <tt>null</tt> will be set in the corresponding element 
266      * in the returned array.  A thread is alive if 
267      * it has been started and has not yet died.
268      *
269      * <p>
270      * <b>MBeanServer access</b>:<br>
271      * The mapped type of <tt>ThreadInfo</tt> is
272      * <tt>CompositeData</tt> with attributes as specified in
273      * {@link ThreadInfo#from ThreadInfo}.
274      *
275      * @param ids an array of thread IDs 
276      * @param maxDepth the maximum number of entries in the stack trace 
277      * to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request
278      * the entire stack to be dumped.
279      *
280      * @return an array of the {@link ThreadInfo} objects, each containing
281      * information about a thread whose ID is in the corresponding
282      * element of the input array of IDs. 
283      *
284      * @throws IllegalArgumentException if <tt>maxDepth is negative</tt>.
285      * @throws IllegalArgumentException if any element in the input array 
286      *      <tt>ids</tt> is <tt>&lt= 0</tt>.
287      * @throws java.lang.SecurityException if a security manager
288      *         exists and the caller does not have
289      *         ManagementPermission("monitor").
290      *
291      */
292     public ThreadInfo  [] getThreadInfo(long[] ids, int maxDepth);
293 
294     /**
295      * Tests if the Java virtual machine supports thread contention monitoring.
296      *
297      * @return
298      *   <tt>true</tt>
299      *     if the Java virtual machine supports thread contention monitoring;
300      *   <tt>false</tt> otherwise.
301      */
302     public boolean isThreadContentionMonitoringSupported();
303 
304     /**
305      * Tests if thread contention monitoring is enabled.
306      *
307      * @return <tt>true</tt> if thread contention monitoring is enabled;
308      *         <tt>false</tt> otherwise.
309      *
310      * @throws java.lang.UnsupportedOperationException if the Java virtual 
311      * machine does not support thread contention monitoring.
312 
313      * @see #isThreadContentionMonitoringSupported
314      */
315     public boolean isThreadContentionMonitoringEnabled();
316 
317     /**
318      * Enables or disables thread contention monitoring.
319      * Thread contention monitoring is disabled by default.
320      *
321      * @param enable <tt>true</tt> to enable;
322      *               <tt>false</tt> to disable.
323      *
324      * @throws java.lang.UnsupportedOperationException if the Java 
325      * virtual machine does not support thread contention monitoring.
326      *
327      * @throws java.lang.SecurityException if a security manager
328      *         exists and the caller does not have
329      *         ManagementPermission("control").
330      *
331      * @see #isThreadContentionMonitoringSupported
332      */
333     public void setThreadContentionMonitoringEnabled(boolean enable);
334 
335     /**
336      * Returns the total CPU time for the current thread in nanoseconds.
337      * The returned value is of nanoseconds precison but
338      * not necessarily nanoseconds accuracy.
339      * If the implementation distinguishes between user mode time and system 
340      * mode time, the returned CPU time is the amount of time that 
341      * the current thread has executed in user mode or system mode.
342      *
343      * <p>
344      * This is a convenient method for local management use and is 
345      * equivalent to calling:
346      * <blockquote><pre>
347      *   {@link #getThreadCpuTime getThreadCpuTime}(Thread.currentThread().getId());
348      * </pre></blockquote>
349      *
350      * @return the total CPU time for the current thread if CPU time
351      * measurement is enabled; <tt>-1</tt> otherwise.
352      *
353      * @throws java.lang.UnsupportedOperationException if the Java 
354      * virtual machine does not support CPU time measurement for
355      * the current thread.
356      *
357      * @see #getCurrentThreadUserTime
358      * @see #isCurrentThreadCpuTimeSupported
359      * @see #isThreadCpuTimeEnabled
360      * @see #setThreadCpuTimeEnabled
361      */
362     public long getCurrentThreadCpuTime();
363 
364     /**
365      * Returns the CPU time that the current thread has executed 
366      * in user mode in nanoseconds.
367      * The returned value is of nanoseconds precison but
368      * not necessarily nanoseconds accuracy.
369      *
370      * <p>
371      * This is a convenient method for local management use and is 
372      * equivalent to calling:
373      * <blockquote><pre>
374      *   {@link #getThreadUserTime getThreadUserTime}(Thread.currentThread().getId());
375      * </pre></blockquote>
376      *
377      * @return the user-level CPU time for the current thread if CPU time
378      * measurement is enabled; <tt>-1</tt> otherwise.
379      *
380      * @throws java.lang.UnsupportedOperationException if the Java 
381      * virtual machine does not support CPU time measurement for
382      * the current thread.
383      *
384      * @see #getCurrentThreadCpuTime
385      * @see #isCurrentThreadCpuTimeSupported
386      * @see #isThreadCpuTimeEnabled
387      * @see #setThreadCpuTimeEnabled
388      */
389     public long getCurrentThreadUserTime();
390 
391     /**
392      * Returns the total CPU time for a thread of the specified ID in nanoseconds.
393      * The returned value is of nanoseconds precision but
394      * not necessarily nanoseconds accuracy.
395      * If the implementation distinguishes between user mode time and system 
396      * mode time, the returned CPU time is the amount of time that 
397      * the thread has executed in user mode or system mode.
398      *
399      * <p>
400      * If the thread of the specified ID is not alive or does not exist,
401      * this method returns <tt>-1</tt>. If CPU time measurement
402      * is disabled, this method returns <tt>-1</tt>.
403      * A thread is alive if it has been started and has not yet died.
404      * <p>
405      * If CPU time measurement is enabled after the thread has started,
406      * the Java virtual machine implementation may choose any time up to
407      * and including the time that the capability is enabled as the point
408      * where CPU time measurement starts.
409      *
410      * @param id the thread ID of a thread
411      * @return the total CPU time for a thread of the specified ID
412      * if the thread of the specified ID exists, the thread is alive,
413      * and CPU time measurement is enabled;
414      * <tt>-1</tt> otherwise.
415      *
416      * @throws IllegalArgumentException if <tt>id &lt= 0 </tt>.
417      * @throws java.lang.UnsupportedOperationException if the Java 
418      * virtual machine does not support CPU time measurement for 
419      * other threads.
420      *
421      * @see #getThreadUserTime
422      * @see #isThreadCpuTimeSupported
423      * @see #isThreadCpuTimeEnabled
424      * @see #setThreadCpuTimeEnabled
425      */
426     public long getThreadCpuTime(long id);
427 
428     /**
429      * Returns the CPU time that a thread of the specified ID 
430      * has executed in user mode in nanoseconds.
431      * The returned value is of nanoseconds precision but
432      * not necessarily nanoseconds accuracy.
433      *
434      * <p>
435      * If the thread of the specified ID is not alive or does not exist,
436      * this method returns <tt>-1</tt>. If CPU time measurement
437      * is disabled, this method returns <tt>-1</tt>.
438      * A thread is alive if it has been started and has not yet died.
439      * <p>
440      * If CPU time measurement is enabled after the thread has started,
441      * the Java virtual machine implementation may choose any time up to
442      * and including the time that the capability is enabled as the point
443      * where CPU time measurement starts.
444      *
445      * @param id the thread ID of a thread
446      * @return the user-level CPU time for a thread of the specified ID
447      * if the thread of the specified ID exists, the thread is alive,
448      * and CPU time measurement is enabled;
449      * <tt>-1</tt> otherwise.
450      *
451      * @throws IllegalArgumentException if <tt>id &lt= 0 </tt>.
452      * @throws java.lang.UnsupportedOperationException if the Java 
453      * virtual machine does not support CPU time measurement for 
454      * other threads.
455      *
456      * @see #getThreadCpuTime
457      * @see #isThreadCpuTimeSupported
458      * @see #isThreadCpuTimeEnabled
459      * @see #setThreadCpuTimeEnabled
460      */
461     public long getThreadUserTime(long id);
462 
463     /**
464      * Tests if the Java virtual machine implementation supports CPU time
465      * measurement for any thread.
466      * A Java virtual machine implementation that supports CPU time
467      * measurement for any thread will also support CPU time
468      * measurement for the current thread.  
469      *
470      * @return
471      *   <tt>true</tt>
472      *     if the Java virtual machine supports CPU time 
473      *     measurement for any thread;
474      *   <tt>false</tt> otherwise.
475      */
476     public boolean isThreadCpuTimeSupported();
477 
478     /**
479      * Tests if the Java virtual machine supports CPU time
480      * measurement for the current thread.
481      * This method returns <tt>true</tt> if {@link #isThreadCpuTimeSupported}
482      * returns <tt>true</tt>.
483      *
484      * @return
485      *   <tt>true</tt>
486      *     if the Java virtual machine supports CPU time 
487      *     measurement for current thread;
488      *   <tt>false</tt> otherwise.
489      */
490     public boolean isCurrentThreadCpuTimeSupported();
491 
492     /**
493      * Tests if thread CPU time measurement is enabled.
494      *
495      * @return <tt>true</tt> if thread CPU time measurement is enabled;
496      *         <tt>false</tt> otherwise.
497      *
498      * @throws java.lang.UnsupportedOperationException if the Java virtual 
499      * machine does not support CPU time measurement for other threads
500      * nor for the current thread.
501      *
502      * @see #isThreadCpuTimeSupported
503      * @see #isCurrentThreadCpuTimeSupported
504      */
505     public boolean isThreadCpuTimeEnabled();
506 
507     /**
508      * Enables or disables thread CPU time measurement.  The default
509      * is platform dependent.
510      *
511      * @param enable <tt>true</tt> to enable;
512      *               <tt>false</tt> to disable.
513      *
514      * @throws java.lang.UnsupportedOperationException if the Java 
515      * virtual machine does not support CPU time measurement for
516      * any threads nor for the current thread.
517      *
518      * @throws java.lang.SecurityException if a security manager
519      *         exists and the caller does not have
520      *         ManagementPermission("control").
521      *
522      * @see #isThreadCpuTimeSupported
523      * @see #isCurrentThreadCpuTimeSupported
524      */
525     public void setThreadCpuTimeEnabled(boolean enable);
526 
527     /**
528      * Finds cycles of threads that are in deadlock waiting to acquire
529      * object monitors. That is, threads that are blocked waiting to enter a
530      * synchronization block or waiting to reenter a synchronization block
531      * after an {@link Object#wait Object.wait} call, 
532      * where each thread owns one monitor while
533      * trying to obtain another monitor already held by another thread
534      * in a cycle.
535      * <p>
536      * More formally, a thread is <em>monitor deadlocked</em> if it is
537      * part of a cycle in the relation "is waiting for an object monitor
538      * owned by".  In the simplest case, thread A is blocked waiting
539      * for a monitor owned by thread B, and thread B is blocked waiting
540      * for a monitor owned by thread A.
541      * <p>
542      * This method is designed for troubleshooting use, but not for
543      * synchronization control.  It might be an expensive operation.
544      *
545      * @return an array of IDs of the threads that are monitor
546      * deadlocked, if any; <tt>null</tt> otherwise.
547      *
548      * @throws java.lang.SecurityException if a security manager
549      *         exists and the caller does not have
550      *         ManagementPermission("monitor").
551      */
552     public long[] findMonitorDeadlockedThreads();
553 
554     /**
555      * Resets the peak thread count to the current number of
556      * live threads.
557      *
558      * @throws java.lang.SecurityException if a security manager
559      *         exists and the caller does not have
560      *         ManagementPermission("control").
561      *
562      * @see #getPeakThreadCount
563      * @see #getThreadCount
564      */
565     public void resetPeakThreadCount();
566 }
567 
568
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags