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