JavaTM 2 Platform
Standard Ed. 5.0

java.lang.management
接口 ThreadMXBean


public interface ThreadMXBean

Java 虚拟机线程系统的管理接口。

Java 虚拟机具有此接口的实现类的单一实例。实现此接口的实例是一个 MXBean,可以通过调用 ManagementFactory.getThreadMXBean() 方法或从平台 MBeanServer 方法获得。

在 MBeanServer 内惟一标识线程系统的 MXBean 的 ObjectName 为:

java.lang:type=Threading

线程 ID

线程 ID 是一个通过调用线程的 Thread.getId() 方法返回的 long 型正值。线程 ID 在其生存期间是惟一的。线程终止时,该线程 ID 可以被重新使用。

此接口中的某些方法将线程 ID 或线程 ID 数组作为输入参数,并返回每个线程的信息。

线程 CPU 时间

Java 虚拟机实现可能支持测量当前线程的 CPU 时间、测量任何线程的 CPU 时间,或不能测量任何线程的 CPU 时间。

isThreadCpuTimeSupported() 方法可以用于确定 Java 虚拟机是否支持测量任何线程的 CPU 时间。isCurrentThreadCpuTimeSupported() 方法可以用于确定 Java 虚拟机是否支持测量当前线程的 CPU 时间。支持任何线程 CPU 时间测量的 Java 虚拟机实现也支持当前线程的 CPU 时间测量。

此接口提供的 CPU 时间具有毫微秒精度,但并不具有毫微秒的准确性。

Java 虚拟机可能默认禁用 CPU 时间测量。isThreadCpuTimeEnabled()setThreadCpuTimeEnabled(boolean) 方法可用于测试是否启用 CPU 时间测量,并可分别启用/禁用此支持。启用线程 CPU 测量在某些 Java 虚拟机实现中可能开销很大。

线程争用监视

某些 Java 虚拟机可能支持线程争用监视。isThreadContentionMonitoringSupported() 方法可用于确定 Java 虚拟机是否支持线程争用监视。 默认情况下,线程争用监视是禁用的。setThreadContentionMonitoringEnabled(boolean) 方法可用于启用线程争用监视。

从以下版本开始:
1.5
另请参见:
JMX Specification., 访问 MXBeans 的方式

方法摘要
 long[] findMonitorDeadlockedThreads()
          找到处于死锁状态(等待获取对象监视器)的线程的周期。
 long[] getAllThreadIds()
          返回活动线程 ID。
 long getCurrentThreadCpuTime()
          返回当前线程的总 CPU 时间(以毫微秒为单位)。
 long getCurrentThreadUserTime()
          返回当前线程在用户模式中执行的 CPU 时间(以毫微秒为单位)。
 int getDaemonThreadCount()
          返回活动守护线程的当前数目。
 int getPeakThreadCount()
          返回自从 Java 虚拟机启动或峰值重置以来峰值活动线程计数。
 int getThreadCount()
          返回活动线程的当前数目,包括守护线程和非守护线程。
 long getThreadCpuTime(long id)
          返回指定 ID 的线程的总 CPU 时间(以毫微秒为单位)。
 ThreadInfo getThreadInfo(long id)
          返回指定 id 的不具有堆栈跟踪的线程的线程信息。
 ThreadInfo[] getThreadInfo(long[] ids)
          返回其 ID 在输出数组 ids 中的每个线程的线程信息,这些线程不具有堆栈跟踪。
 ThreadInfo[] getThreadInfo(long[] ids, int maxDepth)
          返回其 ID 在输入数组 ids 中的每个线程的线程信息。
 ThreadInfo getThreadInfo(long id, int maxDepth)
          返回指定的 id 的线程的线程信息。
 long getThreadUserTime(long id)
          返回指定 ID 的线程在用户模式中执行的 CPU 时间(以毫微秒为单位)。
 long getTotalStartedThreadCount()
          返回自从 Java 虚拟机启动以来创建和启动的线程总数目。
 boolean isCurrentThreadCpuTimeSupported()
          测试 Java 虚拟机是否支持当前线程的 CPU 时间测量。
 boolean isThreadContentionMonitoringEnabled()
          测试是否启用了线程争用监视。
 boolean isThreadContentionMonitoringSupported()
          测试 Java 虚拟机是否支持线程争用监视。
 boolean isThreadCpuTimeEnabled()
          测试是否启用了线程 CPU 时间测量。
 boolean isThreadCpuTimeSupported()
          测试 Java 虚拟机实现是否支持任何线程的 CPU 时间测量。
 void resetPeakThreadCount()
          将峰值线程计数重置为当前活动线程的数量。
 void setThreadContentionMonitoringEnabled(boolean enable)
          启用或禁用线程争用监视。
 void setThreadCpuTimeEnabled(boolean enable)
          启用或禁用线程 CPU 时间测量。
 

方法详细信息

getThreadCount

int getThreadCount()
返回活动线程的当前数目,包括守护线程和非守护线程。

返回:
活动线程的当前数目。

getPeakThreadCount

int getPeakThreadCount()
返回自从 Java 虚拟机启动或峰值重置以来峰值活动线程计数。

返回:
峰值活动线程计数。

getTotalStartedThreadCount

long getTotalStartedThreadCount()
返回自从 Java 虚拟机启动以来创建和启动的线程总数目。

返回:
已启动的线程的总数。

getDaemonThreadCount

int getDaemonThreadCount()
返回活动守护线程的当前数目。

返回:
活动守护线程的当前数目。

getAllThreadIds

long[] getAllThreadIds()
返回活动线程 ID。在返回的数组中包含的某些线程可能在此方法返回时已经终止。

返回:
long 数组,每个成员都是线程 ID。
抛出:
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("monitor")。

getThreadInfo

ThreadInfo getThreadInfo(long id)
返回指定 id 的不具有堆栈跟踪的线程的线程信息。 此方法等效于调用:
getThreadInfo(id, 0);

此方法返回表示指定 ID 的线程的线程信息的 ThreadInfo 对象。返回的 ThreadInfo 对象中的堆栈跟踪将为一个空的 StackTraceElement 数组。 如果给定 ID 的线程不为活动状态,或不存在,此方法将返回 null。如果线程已经启动且尚未终止,则该线程处于活动状态。

MBeanServer 访问
ThreadInfo 的映射类型为 CompositeData,具有 ThreadInfo 中指定的那些属性。

参数:
id - 线程的线程 ID。必须为正数。
返回:
给定 ID 的不具有堆栈跟踪的线程的 ThreadInfo 对象;如果给定 ID 的线程不为活动状态,或不存在,则返回 null
抛出:
IllegalArgumentException - 如果 id <= 0
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("monitor")。

getThreadInfo

ThreadInfo[] getThreadInfo(long[] ids)
返回其 ID 在输出数组 ids 中的每个线程的线程信息,这些线程不具有堆栈跟踪。此方法等效于调用:
   getThreadInfo(ids, 0);
 

此方法返回 ThreadInfo 对象数组。每个 ThreadInfo 对象中的堆栈跟踪将为空的 StackTraceElement 数组。 如果给定 ID 的线程不为活动状态,或不存在,返回数组中的对应元素将包含 null。如果线程已经启动且尚未终止,则该线程处于活动状态。

MBeanServer 访问
ThreadInfo 的映射类型为 CompositeData,具有 ThreadInfo 中指定的那些属性。

参数:
ids - 线程 ID 数组
返回:
一个 ThreadInfo 对象的数组,每个成员均包含关于其 ID 在 IDs 输入数组的对应元素中的线程的信息。
抛出:
IllegalArgumentException - 如果输入数组 ids 中的任何元素 <= 0
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("monitor")。

getThreadInfo

ThreadInfo getThreadInfo(long id,
                         int maxDepth)
返回指定的 id 的线程的线程信息。maxDepth 参数指示可从堆栈跟踪检索的 StackTraceElement 的最大数目。如果 maxDepth == Integer.MAX_VALUE,则将转储线程的整个堆栈跟踪。如果 maxDepth == 0,将不转储线程的任何堆栈跟踪。

当 Java 虚拟机没有关于线程的堆栈跟踪信息或 maxDepth == 0 时,ThreadInfo 对象中的堆栈跟踪将为空的 StackTraceElement 数组。

如果给定 ID 的线程不为活动状态,或不存在,此方法将返回 null。如果线程已经启动且尚未终止,则该线程处于活动状态。

MBeanServer 访问
ThreadInfo 的映射类型为 CompositeData,具有 ThreadInfo 中指定的那些属性。

参数:
id - 线程的线程 ID。必须为正数。
maxDepth - 要转储的堆栈跟踪中的最大项数。Integer.MAX_VALUE 可以用于请求将整个堆栈转储。
返回:
给定 ID 的线程的 ThreadInfo。如果给定 ID 的线程不为活动状态,或不存在,则返回 null
抛出:
IllegalArgumentException - 如果 id <= 0
IllegalArgumentException - 如果 maxDepth 为负数
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("monitor")。

getThreadInfo

ThreadInfo[] getThreadInfo(long[] ids,
                           int maxDepth)
返回其 ID 在输入数组 ids 中的每个线程的线程信息。maxDepth 参数指示可从堆栈跟踪检索的 StackTraceElement 的最大数目。如果 maxDepth == Integer.MAX_VALUE,则将转储线程的整个堆栈跟踪。如果 maxDepth == 0,将不转储线程的任何堆栈跟踪。

当 Java 虚拟机没有关于线程的堆栈跟踪信息或 maxDepth == 0 时,ThreadInfo 对象中的堆栈跟踪将为空的 StackTraceElement 数组。

此方法返回一个 ThreadInfo 对象的数组,其每个成员均为关于线程的线程信息,索引顺序与 ids 数组中索引相同。如果给定 ID 的线程不为活动状态,或不存在,返回数组中的对应元素将设置为 null。如果线程已经启动且尚未终止,则该线程处于活动状态。

MBeanServer 访问
ThreadInfo 的映射类型为 CompositeData,具有 ThreadInfo 中指定的那些属性。

参数:
ids - 线程 ID 数组
maxDepth - 要转储的堆栈跟踪中的最大项数。Integer.MAX_VALUE 可以用于请求将整个堆栈转储。
返回:
一个 ThreadInfo 对象的数组,每个成员均包含关于其 ID 在 IDs 输入数组的对应元素中的线程的信息。
抛出:
IllegalArgumentException - 如果 maxDepth 为负数
IllegalArgumentException - 如果输入数组 ids 中的任何元素 <= 0
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("monitor")。

isThreadContentionMonitoringSupported

boolean isThreadContentionMonitoringSupported()
测试 Java 虚拟机是否支持线程争用监视。

返回:
如果 Java 虚拟机支持线程争用监视,则返回 true;否则返回 false

isThreadContentionMonitoringEnabled

boolean isThreadContentionMonitoringEnabled()
测试是否启用了线程争用监视。

返回:
如果启用了线程争用监视,则返回 true;否则返回 false
抛出:
UnsupportedOperationException - 如果 Java 虚拟机不支持线程争用监视。
另请参见:
isThreadContentionMonitoringSupported()

setThreadContentionMonitoringEnabled

void setThreadContentionMonitoringEnabled(boolean enable)
启用或禁用线程争用监视。默认情况下,线程争用监视是禁用的。

参数:
enable - 为 true 则启用;为 false 则禁用。
抛出:
UnsupportedOperationException - 如果 Java 虚拟机不支持线程争用监视。
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("control")。
另请参见:
isThreadContentionMonitoringSupported()

getCurrentThreadCpuTime

long getCurrentThreadCpuTime()
返回当前线程的总 CPU 时间(以毫微秒为单位)。返回的值具有毫微秒的精度,但未必具有毫微秒的准确度。如果实现对用户模式时间和系统模式时间加以区别,则返回的 CPU 时间为当前线程在用户模式或系统模式中执行的时间总量。

这是一个便于局部管理的方法,等效于调用:

   getThreadCpuTime(Thread.currentThread().getId());
 

返回:
如果启用了 CPU 时间测量,则返回当前线程的总 CPU 时间;否则返回 -1
抛出:
UnsupportedOperationException - 如果 Java 虚拟机不支持当前线程的 CPU 时间测量。
另请参见:
getCurrentThreadUserTime(), isCurrentThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

getCurrentThreadUserTime

long getCurrentThreadUserTime()
返回当前线程在用户模式中执行的 CPU 时间(以毫微秒为单位)。返回的具有毫微秒的精度,但未必具有毫微秒的准确度。

这是一个便于局部管理的方法,等效于调用:

   getThreadUserTime(Thread.currentThread().getId());
 

返回:
如果启用了 CPU 时间测量,则返回当前线程的用户级 CPU 时间;否则返回 -1
抛出:
UnsupportedOperationException - 如果 Java 虚拟机不支持当前线程的 CPU 时间测量。
另请参见:
getCurrentThreadCpuTime(), isCurrentThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

getThreadCpuTime

long getThreadCpuTime(long id)
返回指定 ID 的线程的总 CPU 时间(以毫微秒为单位)。返回的值具有毫微秒的精度,但未必具有毫微秒的准确度。如果实现对用户模式时间和系统模式时间加以区别,返回的 CPU 时间则为线程在用户模式或系统模式中执行的时间总量。

如果指定 ID 的线程不为活动状态,或不存在,此方法将返回 -1。如果 CPU 时间测量,此方法将返回 -1。如果线程已经启动且尚未终止,则该线程处于活动状态。

如果线程启动后启用了 CPU 时间测量,Java 虚拟机实现可能选择任何时间作为启动 CPU 时间测量的时间,包括启用此功能的时间。

参数:
id - 线程的线程 ID
返回:
如果指定的 ID 存在,线程为活动状态,且启用了 CPU 时间测量,则返回指定 ID 的线程的总 CPU 时间;否则返回 -1
抛出:
IllegalArgumentException - 如果 id <= 0
UnsupportedOperationException - 如果 Java 虚拟机不支持其他线程的 CPU 时间测定。
另请参见:
getThreadUserTime(long), isThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

getThreadUserTime

long getThreadUserTime(long id)
返回指定 ID 的线程在用户模式中执行的 CPU 时间(以毫微秒为单位)。返回的值具有毫微秒的精度,但未必具有毫微秒的准确度。

如果指定 ID 的线程不为活动状态,或不存在,此方法将返回 -1。如果禁用 CPU 时间测量,此方法将返回 -1。如果线程已经启动且尚未终止,则该线程处于活动状态。

如果线程启动后启用了 CPU 时间测量,Java 虚拟机实现可能选择任何时间作为启动 CPU 时间测量的时间,包括启用此功能的时间。

参数:
id - 线程的线程 ID
返回:
如果指定的 ID 存在,线程为活动状态,且启用了 CPU 时间测量,则返回指定 ID 的线程的用户级 CPU 时间;否则返回 -1
抛出:
IllegalArgumentException - 如果 id <= 0
UnsupportedOperationException - 如果 Java 虚拟机不支持其他线程的 CPU 时间测定。
另请参见:
getThreadCpuTime(long), isThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

isThreadCpuTimeSupported

boolean isThreadCpuTimeSupported()
测试 Java 虚拟机实现是否支持任何线程的 CPU 时间测量。支持任何线程 CPU 时间测定的 Java 虚拟机实现也支持当前线程的 CPU 时间测定。

返回:
如果 Java 虚拟机支持任何线程的 CPU 时间测量,则返回 true;否则返回 false

isCurrentThreadCpuTimeSupported

boolean isCurrentThreadCpuTimeSupported()
测试 Java 虚拟机是否支持当前线程的 CPU 时间测量。如果 isThreadCpuTimeSupported() 返回 true,此方法将返回 true

返回:
如果 Java 虚拟机支持当前线程的 CPU 时间测量,则返回 true;否则返回 false

isThreadCpuTimeEnabled

boolean isThreadCpuTimeEnabled()
测试是否启用了线程 CPU 时间测量。

返回:
如果启用了线程 CPU 时间测量,则返回 true;否则返回 false
抛出:
UnsupportedOperationException - 如果 Java 虚拟机不支持其他线程或当前线程的 CPU 时间测量。
另请参见:
isThreadCpuTimeSupported(), isCurrentThreadCpuTimeSupported()

setThreadCpuTimeEnabled

void setThreadCpuTimeEnabled(boolean enable)
启用或禁用线程 CPU 时间测量。此默认值与平台有关。

参数:
enable - 为 true 则启用;为 false 则禁用。
抛出:
UnsupportedOperationException - 如果 Java 虚拟机不支持任何线程或当前线程的 CPU 时间测量。
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("control")。
另请参见:
isThreadCpuTimeSupported(), isCurrentThreadCpuTimeSupported()

findMonitorDeadlockedThreads

long[] findMonitorDeadlockedThreads()
找到处于死锁状态(等待获取对象监视器)的线程的周期。即线程被阻塞,等待进入同步块或在 Object.wait 调用后等待重新进入同步块,此时每个线程拥有一个监视器,且同时试图获取已经由周期中的另一个线程拥有的另一个监视器。

更正式地说,如果线程属于某个周期,处于“等待已被占用的对象监视器”的关系中,则该线程处于监视器死锁 状态。在最简单的情况下,线程 A 被阻塞,等待由线程 B 拥有的监视器,线程 B 被阻塞,等待由线程 A 拥有的监视器。

此方法设计用于进行故障排除,但不适合进行同步控制。它可能成为开销很大的操作。

返回:
处于监视器死锁状态的线程(如果有)的 ID 数组;否则返回 null
抛出:
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission("monitor")。

resetPeakThreadCount

void resetPeakThreadCount()
将峰值线程计数重置为当前活动线程的数量。

抛出:
SecurityException - 如果存在安全管理器,且调用方不具有 ManagementPermission(("control")。
另请参见:
getPeakThreadCount(), getThreadCount()

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策