author | jfranck |
Wed, 11 Sep 2013 09:45:52 +0200 | |
changeset 19834 | c43d94c72c41 |
parent 18799 | 31062cb3cc8e |
child 21278 | ef8a3a2a72f2 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
18799
31062cb3cc8e
8020308: Fix doclint issues in java.lang.management
sspitsyn
parents:
18156
diff
changeset
|
2 |
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. |
2 | 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 |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 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 |
* |
|
5506 | 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. |
|
2 | 24 |
*/ |
25 |
||
26 |
package java.lang.management; |
|
27 |
||
28 |
import java.util.Map; |
|
29 |
||
30 |
/** |
|
31 |
* The management interface for the thread system of |
|
32 |
* the Java virtual machine. |
|
33 |
* |
|
34 |
* <p> A Java virtual machine has a single instance of the implementation |
|
35 |
* class of this interface. This instance implementing this interface is |
|
36 |
* an <a href="ManagementFactory.html#MXBean">MXBean</a> |
|
37 |
* that can be obtained by calling |
|
38 |
* the {@link ManagementFactory#getThreadMXBean} method or |
|
39 |
* from the {@link ManagementFactory#getPlatformMBeanServer |
|
40 |
* platform <tt>MBeanServer</tt>} method. |
|
41 |
* |
|
42 |
* <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for |
|
43 |
* the thread system within an MBeanServer is: |
|
44 |
* <blockquote> |
|
45 |
* {@link ManagementFactory#THREAD_MXBEAN_NAME |
|
46 |
* <tt>java.lang:type=Threading</tt>} |
|
47 |
* </blockquote> |
|
48 |
* |
|
401
ef01e0dccd63
6610094: Add generic support for platform MXBeans of any type (also fixed 6681031)
mchung
parents:
2
diff
changeset
|
49 |
* It can be obtained by calling the |
ef01e0dccd63
6610094: Add generic support for platform MXBeans of any type (also fixed 6681031)
mchung
parents:
2
diff
changeset
|
50 |
* {@link PlatformManagedObject#getObjectName} method. |
ef01e0dccd63
6610094: Add generic support for platform MXBeans of any type (also fixed 6681031)
mchung
parents:
2
diff
changeset
|
51 |
* |
18799
31062cb3cc8e
8020308: Fix doclint issues in java.lang.management
sspitsyn
parents:
18156
diff
changeset
|
52 |
* <h3>Thread ID</h3> |
2 | 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 |
* |
|
18799
31062cb3cc8e
8020308: Fix doclint issues in java.lang.management
sspitsyn
parents:
18156
diff
changeset
|
61 |
* <h3>Thread CPU time</h3> |
2 | 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 |
* |
|
18799
31062cb3cc8e
8020308: Fix doclint issues in java.lang.management
sspitsyn
parents:
18156
diff
changeset
|
86 |
* <h3>Thread Contention Monitoring</h3> |
2 | 87 |
* Some Java virtual machines may support thread contention monitoring. |
88 |
* When thread contention monitoring is enabled, the accumulated elapsed |
|
89 |
* time that the thread has blocked for synchronization or waited for |
|
90 |
* notification will be collected and returned in the |
|
91 |
* <a href="ThreadInfo.html#SyncStats"><tt>ThreadInfo</tt></a> object. |
|
92 |
* <p> |
|
93 |
* The {@link #isThreadContentionMonitoringSupported} method can be used to |
|
94 |
* determine if a Java virtual machine supports thread contention monitoring. |
|
95 |
* The thread contention monitoring is disabled by default. The |
|
96 |
* {@link #setThreadContentionMonitoringEnabled} method can be used to enable |
|
97 |
* thread contention monitoring. |
|
98 |
* |
|
18799
31062cb3cc8e
8020308: Fix doclint issues in java.lang.management
sspitsyn
parents:
18156
diff
changeset
|
99 |
* <h3>Synchronization Information and Deadlock Detection</h3> |
2 | 100 |
* Some Java virtual machines may support monitoring of |
101 |
* {@linkplain #isObjectMonitorUsageSupported object monitor usage} and |
|
102 |
* {@linkplain #isSynchronizerUsageSupported ownable synchronizer usage}. |
|
103 |
* The {@link #getThreadInfo(long[], boolean, boolean)} and |
|
104 |
* {@link #dumpAllThreads} methods can be used to obtain the thread stack trace |
|
105 |
* and synchronization information including which |
|
106 |
* {@linkplain LockInfo <i>lock</i>} a thread is blocked to |
|
107 |
* acquire or waiting on and which locks the thread currently owns. |
|
108 |
* <p> |
|
109 |
* The <tt>ThreadMXBean</tt> interface provides the |
|
110 |
* {@link #findMonitorDeadlockedThreads} and |
|
111 |
* {@link #findDeadlockedThreads} methods to find deadlocks in |
|
112 |
* the running application. |
|
113 |
* |
|
401
ef01e0dccd63
6610094: Add generic support for platform MXBeans of any type (also fixed 6681031)
mchung
parents:
2
diff
changeset
|
114 |
* @see ManagementFactory#getPlatformMXBeans(Class) |
2 | 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 |
||
401
ef01e0dccd63
6610094: Add generic support for platform MXBeans of any type (also fixed 6681031)
mchung
parents:
2
diff
changeset
|
124 |
public interface ThreadMXBean extends PlatformManagedObject { |
2 | 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 <tt>long</tt>, each is a thread ID. |
|
162 |
* |
|
163 |
* @throws java.lang.SecurityException if a security manager |
|
164 |
* exists and the caller does not have |
|
165 |
* ManagementPermission("monitor"). |
|
166 |
*/ |
|
167 |
public long[] getAllThreadIds(); |
|
168 |
||
169 |
/** |
|
170 |
* Returns the thread info for a thread of the specified |
|
171 |
* <tt>id</tt> with no stack trace. |
|
172 |
* This method is equivalent to calling: |
|
173 |
* <blockquote> |
|
174 |
* {@link #getThreadInfo(long, int) getThreadInfo(id, 0);} |
|
175 |
* </blockquote> |
|
176 |
* |
|
177 |
* <p> |
|
178 |
* This method returns a <tt>ThreadInfo</tt> object representing |
|
179 |
* the thread information for the thread of the specified ID. |
|
180 |
* The stack trace, locked monitors, and locked synchronizers |
|
181 |
* in the returned <tt>ThreadInfo</tt> object will |
|
182 |
* be empty. |
|
183 |
* |
|
184 |
* If a thread of the given ID is not alive or does not exist, |
|
185 |
* this method will return <tt>null</tt>. A thread is alive if |
|
186 |
* it has been started and has not yet died. |
|
187 |
* |
|
188 |
* <p> |
|
189 |
* <b>MBeanServer access</b>:<br> |
|
190 |
* The mapped type of <tt>ThreadInfo</tt> is |
|
191 |
* <tt>CompositeData</tt> with attributes as specified in the |
|
192 |
* {@link ThreadInfo#from ThreadInfo.from} method. |
|
193 |
* |
|
194 |
* @param id the thread ID of the thread. Must be positive. |
|
195 |
* |
|
196 |
* @return a {@link ThreadInfo} object for the thread of the given ID |
|
197 |
* with no stack trace, no locked monitor and no synchronizer info; |
|
198 |
* <tt>null</tt> if the thread of the given ID is not alive or |
|
199 |
* it does not exist. |
|
200 |
* |
|
18156 | 201 |
* @throws IllegalArgumentException if {@code id <= 0}. |
2 | 202 |
* @throws java.lang.SecurityException if a security manager |
203 |
* exists and the caller does not have |
|
204 |
* ManagementPermission("monitor"). |
|
205 |
*/ |
|
206 |
public ThreadInfo getThreadInfo(long id); |
|
207 |
||
208 |
/** |
|
209 |
* Returns the thread info for each thread |
|
210 |
* whose ID is in the input array <tt>ids</tt> with no stack trace. |
|
211 |
* This method is equivalent to calling: |
|
212 |
* <blockquote><pre> |
|
213 |
* {@link #getThreadInfo(long[], int) getThreadInfo}(ids, 0); |
|
214 |
* </pre></blockquote> |
|
215 |
* |
|
216 |
* <p> |
|
217 |
* This method returns an array of the <tt>ThreadInfo</tt> objects. |
|
218 |
* The stack trace, locked monitors, and locked synchronizers |
|
219 |
* in each <tt>ThreadInfo</tt> object will be empty. |
|
220 |
* |
|
221 |
* If a thread of a given ID is not alive or does not exist, |
|
222 |
* the corresponding element in the returned array will |
|
223 |
* contain <tt>null</tt>. A thread is alive if |
|
224 |
* it has been started and has not yet died. |
|
225 |
* |
|
226 |
* <p> |
|
227 |
* <b>MBeanServer access</b>:<br> |
|
228 |
* The mapped type of <tt>ThreadInfo</tt> is |
|
229 |
* <tt>CompositeData</tt> with attributes as specified in the |
|
230 |
* {@link ThreadInfo#from ThreadInfo.from} method. |
|
231 |
* |
|
232 |
* @param ids an array of thread IDs. |
|
233 |
* @return an array of the {@link ThreadInfo} objects, each containing |
|
234 |
* information about a thread whose ID is in the corresponding |
|
235 |
* element of the input array of IDs |
|
236 |
* with no stack trace, no locked monitor and no synchronizer info. |
|
237 |
* |
|
238 |
* @throws IllegalArgumentException if any element in the input array |
|
18156 | 239 |
* <tt>ids</tt> is {@code <= 0}. |
2 | 240 |
* @throws java.lang.SecurityException if a security manager |
241 |
* exists and the caller does not have |
|
242 |
* ManagementPermission("monitor"). |
|
243 |
*/ |
|
244 |
public ThreadInfo[] getThreadInfo(long[] ids); |
|
245 |
||
246 |
/** |
|
247 |
* Returns a thread info for a thread of the specified <tt>id</tt>, |
|
248 |
* with stack trace of a specified number of stack trace elements. |
|
249 |
* The <tt>maxDepth</tt> parameter indicates the maximum number of |
|
250 |
* {@link StackTraceElement} to be retrieved from the stack trace. |
|
251 |
* If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of |
|
252 |
* the thread will be dumped. |
|
253 |
* If <tt>maxDepth == 0</tt>, no stack trace of the thread |
|
254 |
* will be dumped. |
|
255 |
* This method does not obtain the locked monitors and locked |
|
256 |
* synchronizers of the thread. |
|
257 |
* <p> |
|
258 |
* When the Java virtual machine has no stack trace information |
|
259 |
* about a thread or <tt>maxDepth == 0</tt>, |
|
260 |
* the stack trace in the |
|
261 |
* <tt>ThreadInfo</tt> object will be an empty array of |
|
262 |
* <tt>StackTraceElement</tt>. |
|
263 |
* |
|
264 |
* <p> |
|
265 |
* If a thread of the given ID is not alive or does not exist, |
|
266 |
* this method will return <tt>null</tt>. A thread is alive if |
|
267 |
* it has been started and has not yet died. |
|
268 |
* |
|
269 |
* <p> |
|
270 |
* <b>MBeanServer access</b>:<br> |
|
271 |
* The mapped type of <tt>ThreadInfo</tt> is |
|
272 |
* <tt>CompositeData</tt> with attributes as specified in the |
|
273 |
* {@link ThreadInfo#from ThreadInfo.from} method. |
|
274 |
* |
|
275 |
* @param id the thread ID of the thread. Must be positive. |
|
276 |
* @param maxDepth the maximum number of entries in the stack trace |
|
277 |
* to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request |
|
278 |
* the entire stack to be dumped. |
|
279 |
* |
|
280 |
* @return a {@link ThreadInfo} of the thread of the given ID |
|
281 |
* with no locked monitor and synchronizer info. |
|
282 |
* <tt>null</tt> if the thread of the given ID is not alive or |
|
283 |
* it does not exist. |
|
284 |
* |
|
18156 | 285 |
* @throws IllegalArgumentException if {@code id <= 0}. |
2 | 286 |
* @throws IllegalArgumentException if <tt>maxDepth is negative</tt>. |
287 |
* @throws java.lang.SecurityException if a security manager |
|
288 |
* exists and the caller does not have |
|
289 |
* ManagementPermission("monitor"). |
|
290 |
* |
|
291 |
*/ |
|
292 |
public ThreadInfo getThreadInfo(long id, int maxDepth); |
|
293 |
||
294 |
/** |
|
295 |
* Returns the thread info for each thread |
|
296 |
* whose ID is in the input array <tt>ids</tt>, |
|
297 |
* with stack trace of a specified number of stack trace elements. |
|
298 |
* The <tt>maxDepth</tt> parameter indicates the maximum number of |
|
299 |
* {@link StackTraceElement} to be retrieved from the stack trace. |
|
300 |
* If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of |
|
301 |
* the thread will be dumped. |
|
302 |
* If <tt>maxDepth == 0</tt>, no stack trace of the thread |
|
303 |
* will be dumped. |
|
304 |
* This method does not obtain the locked monitors and locked |
|
305 |
* synchronizers of the threads. |
|
306 |
* <p> |
|
307 |
* When the Java virtual machine has no stack trace information |
|
308 |
* about a thread or <tt>maxDepth == 0</tt>, |
|
309 |
* the stack trace in the |
|
310 |
* <tt>ThreadInfo</tt> object will be an empty array of |
|
311 |
* <tt>StackTraceElement</tt>. |
|
312 |
* <p> |
|
313 |
* This method returns an array of the <tt>ThreadInfo</tt> objects, |
|
314 |
* each is the thread information about the thread with the same index |
|
315 |
* as in the <tt>ids</tt> array. |
|
316 |
* If a thread of the given ID is not alive or does not exist, |
|
317 |
* <tt>null</tt> will be set in the corresponding element |
|
318 |
* in the returned array. A thread is alive if |
|
319 |
* it has been started and has not yet died. |
|
320 |
* |
|
321 |
* <p> |
|
322 |
* <b>MBeanServer access</b>:<br> |
|
323 |
* The mapped type of <tt>ThreadInfo</tt> is |
|
324 |
* <tt>CompositeData</tt> with attributes as specified in the |
|
325 |
* {@link ThreadInfo#from ThreadInfo.from} method. |
|
326 |
* |
|
327 |
* @param ids an array of thread IDs |
|
328 |
* @param maxDepth the maximum number of entries in the stack trace |
|
329 |
* to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request |
|
330 |
* the entire stack to be dumped. |
|
331 |
* |
|
332 |
* @return an array of the {@link ThreadInfo} objects, each containing |
|
333 |
* information about a thread whose ID is in the corresponding |
|
334 |
* element of the input array of IDs with no locked monitor and |
|
335 |
* synchronizer info. |
|
336 |
* |
|
337 |
* @throws IllegalArgumentException if <tt>maxDepth is negative</tt>. |
|
338 |
* @throws IllegalArgumentException if any element in the input array |
|
18156 | 339 |
* <tt>ids</tt> is {@code <= 0}. |
2 | 340 |
* @throws java.lang.SecurityException if a security manager |
341 |
* exists and the caller does not have |
|
342 |
* ManagementPermission("monitor"). |
|
343 |
* |
|
344 |
*/ |
|
345 |
public ThreadInfo[] getThreadInfo(long[] ids, int maxDepth); |
|
346 |
||
347 |
/** |
|
348 |
* Tests if the Java virtual machine supports thread contention monitoring. |
|
349 |
* |
|
350 |
* @return |
|
351 |
* <tt>true</tt> |
|
352 |
* if the Java virtual machine supports thread contention monitoring; |
|
353 |
* <tt>false</tt> otherwise. |
|
354 |
*/ |
|
355 |
public boolean isThreadContentionMonitoringSupported(); |
|
356 |
||
357 |
/** |
|
358 |
* Tests if thread contention monitoring is enabled. |
|
359 |
* |
|
360 |
* @return <tt>true</tt> if thread contention monitoring is enabled; |
|
361 |
* <tt>false</tt> otherwise. |
|
362 |
* |
|
363 |
* @throws java.lang.UnsupportedOperationException if the Java virtual |
|
364 |
* machine does not support thread contention monitoring. |
|
365 |
* |
|
366 |
* @see #isThreadContentionMonitoringSupported |
|
367 |
*/ |
|
368 |
public boolean isThreadContentionMonitoringEnabled(); |
|
369 |
||
370 |
/** |
|
371 |
* Enables or disables thread contention monitoring. |
|
372 |
* Thread contention monitoring is disabled by default. |
|
373 |
* |
|
374 |
* @param enable <tt>true</tt> to enable; |
|
375 |
* <tt>false</tt> to disable. |
|
376 |
* |
|
377 |
* @throws java.lang.UnsupportedOperationException if the Java |
|
378 |
* virtual machine does not support thread contention monitoring. |
|
379 |
* |
|
380 |
* @throws java.lang.SecurityException if a security manager |
|
381 |
* exists and the caller does not have |
|
382 |
* ManagementPermission("control"). |
|
383 |
* |
|
384 |
* @see #isThreadContentionMonitoringSupported |
|
385 |
*/ |
|
386 |
public void setThreadContentionMonitoringEnabled(boolean enable); |
|
387 |
||
388 |
/** |
|
389 |
* Returns the total CPU time for the current thread in nanoseconds. |
|
390 |
* The returned value is of nanoseconds precision but |
|
391 |
* not necessarily nanoseconds accuracy. |
|
392 |
* If the implementation distinguishes between user mode time and system |
|
393 |
* mode time, the returned CPU time is the amount of time that |
|
394 |
* the current thread has executed in user mode or system mode. |
|
395 |
* |
|
396 |
* <p> |
|
397 |
* This is a convenient method for local management use and is |
|
398 |
* equivalent to calling: |
|
399 |
* <blockquote><pre> |
|
400 |
* {@link #getThreadCpuTime getThreadCpuTime}(Thread.currentThread().getId()); |
|
401 |
* </pre></blockquote> |
|
402 |
* |
|
403 |
* @return the total CPU time for the current thread if CPU time |
|
404 |
* measurement is enabled; <tt>-1</tt> otherwise. |
|
405 |
* |
|
406 |
* @throws java.lang.UnsupportedOperationException if the Java |
|
407 |
* virtual machine does not support CPU time measurement for |
|
408 |
* the current thread. |
|
409 |
* |
|
410 |
* @see #getCurrentThreadUserTime |
|
411 |
* @see #isCurrentThreadCpuTimeSupported |
|
412 |
* @see #isThreadCpuTimeEnabled |
|
413 |
* @see #setThreadCpuTimeEnabled |
|
414 |
*/ |
|
415 |
public long getCurrentThreadCpuTime(); |
|
416 |
||
417 |
/** |
|
418 |
* Returns the CPU time that the current thread has executed |
|
419 |
* in user mode in nanoseconds. |
|
420 |
* The returned value is of nanoseconds precision but |
|
421 |
* not necessarily nanoseconds accuracy. |
|
422 |
* |
|
423 |
* <p> |
|
424 |
* This is a convenient method for local management use and is |
|
425 |
* equivalent to calling: |
|
426 |
* <blockquote><pre> |
|
427 |
* {@link #getThreadUserTime getThreadUserTime}(Thread.currentThread().getId()); |
|
428 |
* </pre></blockquote> |
|
429 |
* |
|
430 |
* @return the user-level CPU time for the current thread if CPU time |
|
431 |
* measurement is enabled; <tt>-1</tt> otherwise. |
|
432 |
* |
|
433 |
* @throws java.lang.UnsupportedOperationException if the Java |
|
434 |
* virtual machine does not support CPU time measurement for |
|
435 |
* the current thread. |
|
436 |
* |
|
437 |
* @see #getCurrentThreadCpuTime |
|
438 |
* @see #isCurrentThreadCpuTimeSupported |
|
439 |
* @see #isThreadCpuTimeEnabled |
|
440 |
* @see #setThreadCpuTimeEnabled |
|
441 |
*/ |
|
442 |
public long getCurrentThreadUserTime(); |
|
443 |
||
444 |
/** |
|
445 |
* Returns the total CPU time for a thread of the specified ID in nanoseconds. |
|
446 |
* The returned value is of nanoseconds precision but |
|
447 |
* not necessarily nanoseconds accuracy. |
|
448 |
* If the implementation distinguishes between user mode time and system |
|
449 |
* mode time, the returned CPU time is the amount of time that |
|
450 |
* the thread has executed in user mode or system mode. |
|
451 |
* |
|
452 |
* <p> |
|
453 |
* If the thread of the specified ID is not alive or does not exist, |
|
454 |
* this method returns <tt>-1</tt>. If CPU time measurement |
|
455 |
* is disabled, this method returns <tt>-1</tt>. |
|
456 |
* A thread is alive if it has been started and has not yet died. |
|
457 |
* <p> |
|
458 |
* If CPU time measurement is enabled after the thread has started, |
|
459 |
* the Java virtual machine implementation may choose any time up to |
|
460 |
* and including the time that the capability is enabled as the point |
|
461 |
* where CPU time measurement starts. |
|
462 |
* |
|
463 |
* @param id the thread ID of a thread |
|
464 |
* @return the total CPU time for a thread of the specified ID |
|
465 |
* if the thread of the specified ID exists, the thread is alive, |
|
466 |
* and CPU time measurement is enabled; |
|
467 |
* <tt>-1</tt> otherwise. |
|
468 |
* |
|
18156 | 469 |
* @throws IllegalArgumentException if {@code id <= 0}. |
2 | 470 |
* @throws java.lang.UnsupportedOperationException if the Java |
471 |
* virtual machine does not support CPU time measurement for |
|
472 |
* other threads. |
|
473 |
* |
|
474 |
* @see #getThreadUserTime |
|
475 |
* @see #isThreadCpuTimeSupported |
|
476 |
* @see #isThreadCpuTimeEnabled |
|
477 |
* @see #setThreadCpuTimeEnabled |
|
478 |
*/ |
|
479 |
public long getThreadCpuTime(long id); |
|
480 |
||
481 |
/** |
|
482 |
* Returns the CPU time that a thread of the specified ID |
|
483 |
* has executed in user mode in nanoseconds. |
|
484 |
* The returned value is of nanoseconds precision but |
|
485 |
* not necessarily nanoseconds accuracy. |
|
486 |
* |
|
487 |
* <p> |
|
488 |
* If the thread of the specified ID is not alive or does not exist, |
|
489 |
* this method returns <tt>-1</tt>. If CPU time measurement |
|
490 |
* is disabled, this method returns <tt>-1</tt>. |
|
491 |
* A thread is alive if it has been started and has not yet died. |
|
492 |
* <p> |
|
493 |
* If CPU time measurement is enabled after the thread has started, |
|
494 |
* the Java virtual machine implementation may choose any time up to |
|
495 |
* and including the time that the capability is enabled as the point |
|
496 |
* where CPU time measurement starts. |
|
497 |
* |
|
498 |
* @param id the thread ID of a thread |
|
499 |
* @return the user-level CPU time for a thread of the specified ID |
|
500 |
* if the thread of the specified ID exists, the thread is alive, |
|
501 |
* and CPU time measurement is enabled; |
|
502 |
* <tt>-1</tt> otherwise. |
|
503 |
* |
|
18156 | 504 |
* @throws IllegalArgumentException if {@code id <= 0}. |
2 | 505 |
* @throws java.lang.UnsupportedOperationException if the Java |
506 |
* virtual machine does not support CPU time measurement for |
|
507 |
* other threads. |
|
508 |
* |
|
509 |
* @see #getThreadCpuTime |
|
510 |
* @see #isThreadCpuTimeSupported |
|
511 |
* @see #isThreadCpuTimeEnabled |
|
512 |
* @see #setThreadCpuTimeEnabled |
|
513 |
*/ |
|
514 |
public long getThreadUserTime(long id); |
|
515 |
||
516 |
/** |
|
517 |
* Tests if the Java virtual machine implementation supports CPU time |
|
518 |
* measurement for any thread. |
|
519 |
* A Java virtual machine implementation that supports CPU time |
|
520 |
* measurement for any thread will also support CPU time |
|
521 |
* measurement for the current thread. |
|
522 |
* |
|
523 |
* @return |
|
524 |
* <tt>true</tt> |
|
525 |
* if the Java virtual machine supports CPU time |
|
526 |
* measurement for any thread; |
|
527 |
* <tt>false</tt> otherwise. |
|
528 |
*/ |
|
529 |
public boolean isThreadCpuTimeSupported(); |
|
530 |
||
531 |
/** |
|
532 |
* Tests if the Java virtual machine supports CPU time |
|
533 |
* measurement for the current thread. |
|
534 |
* This method returns <tt>true</tt> if {@link #isThreadCpuTimeSupported} |
|
535 |
* returns <tt>true</tt>. |
|
536 |
* |
|
537 |
* @return |
|
538 |
* <tt>true</tt> |
|
539 |
* if the Java virtual machine supports CPU time |
|
540 |
* measurement for current thread; |
|
541 |
* <tt>false</tt> otherwise. |
|
542 |
*/ |
|
543 |
public boolean isCurrentThreadCpuTimeSupported(); |
|
544 |
||
545 |
/** |
|
546 |
* Tests if thread CPU time measurement is enabled. |
|
547 |
* |
|
548 |
* @return <tt>true</tt> if thread CPU time measurement is enabled; |
|
549 |
* <tt>false</tt> otherwise. |
|
550 |
* |
|
551 |
* @throws java.lang.UnsupportedOperationException if the Java virtual |
|
552 |
* machine does not support CPU time measurement for other threads |
|
553 |
* nor for the current thread. |
|
554 |
* |
|
555 |
* @see #isThreadCpuTimeSupported |
|
556 |
* @see #isCurrentThreadCpuTimeSupported |
|
557 |
*/ |
|
558 |
public boolean isThreadCpuTimeEnabled(); |
|
559 |
||
560 |
/** |
|
561 |
* Enables or disables thread CPU time measurement. The default |
|
562 |
* is platform dependent. |
|
563 |
* |
|
564 |
* @param enable <tt>true</tt> to enable; |
|
565 |
* <tt>false</tt> to disable. |
|
566 |
* |
|
567 |
* @throws java.lang.UnsupportedOperationException if the Java |
|
568 |
* virtual machine does not support CPU time measurement for |
|
569 |
* any threads nor for the current thread. |
|
570 |
* |
|
571 |
* @throws java.lang.SecurityException if a security manager |
|
572 |
* exists and the caller does not have |
|
573 |
* ManagementPermission("control"). |
|
574 |
* |
|
575 |
* @see #isThreadCpuTimeSupported |
|
576 |
* @see #isCurrentThreadCpuTimeSupported |
|
577 |
*/ |
|
578 |
public void setThreadCpuTimeEnabled(boolean enable); |
|
579 |
||
580 |
/** |
|
581 |
* Finds cycles of threads that are in deadlock waiting to acquire |
|
582 |
* object monitors. That is, threads that are blocked waiting to enter a |
|
583 |
* synchronization block or waiting to reenter a synchronization block |
|
584 |
* after an {@link Object#wait Object.wait} call, |
|
585 |
* where each thread owns one monitor while |
|
586 |
* trying to obtain another monitor already held by another thread |
|
587 |
* in a cycle. |
|
588 |
* <p> |
|
589 |
* More formally, a thread is <em>monitor deadlocked</em> if it is |
|
590 |
* part of a cycle in the relation "is waiting for an object monitor |
|
591 |
* owned by". In the simplest case, thread A is blocked waiting |
|
592 |
* for a monitor owned by thread B, and thread B is blocked waiting |
|
593 |
* for a monitor owned by thread A. |
|
594 |
* <p> |
|
595 |
* This method is designed for troubleshooting use, but not for |
|
596 |
* synchronization control. It might be an expensive operation. |
|
597 |
* <p> |
|
598 |
* This method finds deadlocks involving only object monitors. |
|
599 |
* To find deadlocks involving both object monitors and |
|
600 |
* <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>, |
|
601 |
* the {@link #findDeadlockedThreads findDeadlockedThreads} method |
|
602 |
* should be used. |
|
603 |
* |
|
604 |
* @return an array of IDs of the threads that are monitor |
|
605 |
* deadlocked, if any; <tt>null</tt> otherwise. |
|
606 |
* |
|
607 |
* @throws java.lang.SecurityException if a security manager |
|
608 |
* exists and the caller does not have |
|
609 |
* ManagementPermission("monitor"). |
|
610 |
* |
|
611 |
* @see #findDeadlockedThreads |
|
612 |
*/ |
|
613 |
public long[] findMonitorDeadlockedThreads(); |
|
614 |
||
615 |
/** |
|
616 |
* Resets the peak thread count to the current number of |
|
617 |
* live threads. |
|
618 |
* |
|
619 |
* @throws java.lang.SecurityException if a security manager |
|
620 |
* exists and the caller does not have |
|
621 |
* ManagementPermission("control"). |
|
622 |
* |
|
623 |
* @see #getPeakThreadCount |
|
624 |
* @see #getThreadCount |
|
625 |
*/ |
|
626 |
public void resetPeakThreadCount(); |
|
627 |
||
628 |
/** |
|
629 |
* Finds cycles of threads that are in deadlock waiting to acquire |
|
630 |
* object monitors or |
|
631 |
* <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>. |
|
632 |
* |
|
633 |
* Threads are <em>deadlocked</em> in a cycle waiting for a lock of |
|
634 |
* these two types if each thread owns one lock while |
|
635 |
* trying to acquire another lock already held |
|
636 |
* by another thread in the cycle. |
|
637 |
* <p> |
|
638 |
* This method is designed for troubleshooting use, but not for |
|
639 |
* synchronization control. It might be an expensive operation. |
|
640 |
* |
|
641 |
* @return an array of IDs of the threads that are |
|
642 |
* deadlocked waiting for object monitors or ownable synchronizers, if any; |
|
643 |
* <tt>null</tt> otherwise. |
|
644 |
* |
|
645 |
* @throws java.lang.SecurityException if a security manager |
|
646 |
* exists and the caller does not have |
|
647 |
* ManagementPermission("monitor"). |
|
648 |
* @throws java.lang.UnsupportedOperationException if the Java virtual |
|
649 |
* machine does not support monitoriing of ownable synchronizer usage. |
|
650 |
* |
|
651 |
* @see #isSynchronizerUsageSupported |
|
652 |
* @see #findMonitorDeadlockedThreads |
|
653 |
* @since 1.6 |
|
654 |
*/ |
|
655 |
public long[] findDeadlockedThreads(); |
|
656 |
||
657 |
/** |
|
658 |
* Tests if the Java virtual machine supports monitoring of |
|
659 |
* object monitor usage. |
|
660 |
* |
|
661 |
* @return |
|
662 |
* <tt>true</tt> |
|
663 |
* if the Java virtual machine supports monitoring of |
|
664 |
* object monitor usage; |
|
665 |
* <tt>false</tt> otherwise. |
|
666 |
* |
|
667 |
* @see #dumpAllThreads |
|
668 |
* @since 1.6 |
|
669 |
*/ |
|
670 |
public boolean isObjectMonitorUsageSupported(); |
|
671 |
||
672 |
/** |
|
673 |
* Tests if the Java virtual machine supports monitoring of |
|
674 |
* <a href="LockInfo.html#OwnableSynchronizer"> |
|
675 |
* ownable synchronizer</a> usage. |
|
676 |
* |
|
677 |
* @return |
|
678 |
* <tt>true</tt> |
|
679 |
* if the Java virtual machine supports monitoring of ownable |
|
680 |
* synchronizer usage; |
|
681 |
* <tt>false</tt> otherwise. |
|
682 |
* |
|
683 |
* @see #dumpAllThreads |
|
684 |
* @since 1.6 |
|
685 |
*/ |
|
686 |
public boolean isSynchronizerUsageSupported(); |
|
687 |
||
688 |
/** |
|
689 |
* Returns the thread info for each thread |
|
690 |
* whose ID is in the input array <tt>ids</tt>, with stack trace |
|
691 |
* and synchronization information. |
|
692 |
* |
|
693 |
* <p> |
|
694 |
* This method obtains a snapshot of the thread information |
|
695 |
* for each thread including: |
|
696 |
* <ul> |
|
697 |
* <li>the entire stack trace,</li> |
|
698 |
* <li>the object monitors currently locked by the thread |
|
699 |
* if <tt>lockedMonitors</tt> is <tt>true</tt>, and</li> |
|
700 |
* <li>the <a href="LockInfo.html#OwnableSynchronizer"> |
|
701 |
* ownable synchronizers</a> currently locked by the thread |
|
702 |
* if <tt>lockedSynchronizers</tt> is <tt>true</tt>.</li> |
|
703 |
* </ul> |
|
704 |
* <p> |
|
705 |
* This method returns an array of the <tt>ThreadInfo</tt> objects, |
|
706 |
* each is the thread information about the thread with the same index |
|
707 |
* as in the <tt>ids</tt> array. |
|
708 |
* If a thread of the given ID is not alive or does not exist, |
|
709 |
* <tt>null</tt> will be set in the corresponding element |
|
710 |
* in the returned array. A thread is alive if |
|
711 |
* it has been started and has not yet died. |
|
712 |
* <p> |
|
713 |
* If a thread does not lock any object monitor or <tt>lockedMonitors</tt> |
|
714 |
* is <tt>false</tt>, the returned <tt>ThreadInfo</tt> object will have an |
|
715 |
* empty <tt>MonitorInfo</tt> array. Similarly, if a thread does not |
|
716 |
* lock any synchronizer or <tt>lockedSynchronizers</tt> is <tt>false</tt>, |
|
717 |
* the returned <tt>ThreadInfo</tt> object |
|
718 |
* will have an empty <tt>LockInfo</tt> array. |
|
719 |
* |
|
720 |
* <p> |
|
721 |
* When both <tt>lockedMonitors</tt> and <tt>lockedSynchronizers</tt> |
|
722 |
* parameters are <tt>false</tt>, it is equivalent to calling: |
|
723 |
* <blockquote><pre> |
|
724 |
* {@link #getThreadInfo(long[], int) getThreadInfo(ids, Integer.MAX_VALUE)} |
|
725 |
* </pre></blockquote> |
|
726 |
* |
|
727 |
* <p> |
|
728 |
* This method is designed for troubleshooting use, but not for |
|
729 |
* synchronization control. It might be an expensive operation. |
|
730 |
* |
|
731 |
* <p> |
|
732 |
* <b>MBeanServer access</b>:<br> |
|
733 |
* The mapped type of <tt>ThreadInfo</tt> is |
|
734 |
* <tt>CompositeData</tt> with attributes as specified in the |
|
735 |
* {@link ThreadInfo#from ThreadInfo.from} method. |
|
736 |
* |
|
737 |
* @param ids an array of thread IDs. |
|
738 |
* @param lockedMonitors if <tt>true</tt>, retrieves all locked monitors. |
|
739 |
* @param lockedSynchronizers if <tt>true</tt>, retrieves all locked |
|
740 |
* ownable synchronizers. |
|
741 |
* |
|
742 |
* @return an array of the {@link ThreadInfo} objects, each containing |
|
743 |
* information about a thread whose ID is in the corresponding |
|
744 |
* element of the input array of IDs. |
|
745 |
* |
|
746 |
* @throws java.lang.SecurityException if a security manager |
|
747 |
* exists and the caller does not have |
|
748 |
* ManagementPermission("monitor"). |
|
749 |
* @throws java.lang.UnsupportedOperationException |
|
750 |
* <ul> |
|
751 |
* <li>if <tt>lockedMonitors</tt> is <tt>true</tt> but |
|
752 |
* the Java virtual machine does not support monitoring |
|
753 |
* of {@linkplain #isObjectMonitorUsageSupported |
|
754 |
* object monitor usage}; or</li> |
|
755 |
* <li>if <tt>lockedSynchronizers</tt> is <tt>true</tt> but |
|
756 |
* the Java virtual machine does not support monitoring |
|
757 |
* of {@linkplain #isSynchronizerUsageSupported |
|
758 |
* ownable synchronizer usage}.</li> |
|
759 |
* </ul> |
|
760 |
* |
|
761 |
* @see #isObjectMonitorUsageSupported |
|
762 |
* @see #isSynchronizerUsageSupported |
|
763 |
* |
|
764 |
* @since 1.6 |
|
765 |
*/ |
|
766 |
public ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers); |
|
767 |
||
768 |
/** |
|
769 |
* Returns the thread info for all live threads with stack trace |
|
770 |
* and synchronization information. |
|
771 |
* Some threads included in the returned array |
|
772 |
* may have been terminated when this method returns. |
|
773 |
* |
|
774 |
* <p> |
|
775 |
* This method returns an array of {@link ThreadInfo} objects |
|
776 |
* as specified in the {@link #getThreadInfo(long[], boolean, boolean)} |
|
777 |
* method. |
|
778 |
* |
|
779 |
* @param lockedMonitors if <tt>true</tt>, dump all locked monitors. |
|
780 |
* @param lockedSynchronizers if <tt>true</tt>, dump all locked |
|
781 |
* ownable synchronizers. |
|
782 |
* |
|
783 |
* @return an array of {@link ThreadInfo} for all live threads. |
|
784 |
* |
|
785 |
* @throws java.lang.SecurityException if a security manager |
|
786 |
* exists and the caller does not have |
|
787 |
* ManagementPermission("monitor"). |
|
788 |
* @throws java.lang.UnsupportedOperationException |
|
789 |
* <ul> |
|
790 |
* <li>if <tt>lockedMonitors</tt> is <tt>true</tt> but |
|
791 |
* the Java virtual machine does not support monitoring |
|
792 |
* of {@linkplain #isObjectMonitorUsageSupported |
|
793 |
* object monitor usage}; or</li> |
|
794 |
* <li>if <tt>lockedSynchronizers</tt> is <tt>true</tt> but |
|
795 |
* the Java virtual machine does not support monitoring |
|
796 |
* of {@linkplain #isSynchronizerUsageSupported |
|
797 |
* ownable synchronizer usage}.</li> |
|
798 |
* </ul> |
|
799 |
* |
|
800 |
* @see #isObjectMonitorUsageSupported |
|
801 |
* @see #isSynchronizerUsageSupported |
|
802 |
* |
|
803 |
* @since 1.6 |
|
804 |
*/ |
|
805 |
public ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers); |
|
806 |
} |