模块 jdk.jdi
包 com.sun.jdi

接口 ThreadReference

所有父级接口：
Mirror , ObjectReference , Value
public interface ThreadReference extends ObjectReference
来自目标 VM 的线程对象。 ThreadReference 是一个 ObjectReference ，可以额外访问来自目标 VM 的线程特定信息。
自从：
1.3

  • 字段详细信息

  • 方法详情

    • name

      String  name()
      返回此线程的名称。
      返回：
      包含线程名称的字符串。

    • suspend

      void suspend()
      挂起这个线程。该线程可以通过 resume() 恢复或通过 VirtualMachine.resume() 与其他线程一起恢复。

      计算虚拟机和单个线程的挂起。在线程再次运行之前，它必须恢复（通过 resume() 或 VirtualMachine.resume() ）与暂停次数相同的次数。

      使用此方法挂起单个线程本质上很容易发生死锁。如果挂起的线程持有另一个正在运行的线程所需的监视器，则目标 VM 中可能出现死锁（至少在挂起的线程再次恢复之前）。

      挂起的线程保证保持挂起状态，直到通过上述 JDI 恢复方法之一恢复。

      抛出：
      VMCannotBeModifiedException - 如果虚拟机是只读的
      参见：

    • resume

      void resume()
      恢复此线程。如果此线程之前未通过 suspend() 或通过 VirtualMachine.suspend() 暂停，或者因为 SUSPEND_ALL 或 SUSPEND_EVENT_THREAD 事件，则调用此方法无效。否则，该线程上挂起的挂起计数将减少。如果减为0，线程会继续执行。注意：从事件相关暂停中恢复的正常方法是通过 EventSet.resume() 。
      抛出：
      VMCannotBeModifiedException - 如果虚拟机是只读的
      参见：

    • suspendCount

      int suspendCount()
      返回此线程的挂起挂起数。有关计数暂停的说明，请参阅 suspend() 。
      返回：
      挂起的挂起计数为整数

    • stop

      void stop(ObjectReference  throwable) throws InvalidTypeException
      以异步异常停止此线程。目标 VM 中的调试器线程将使用给定的 Throwable 对象停止该线程。

      目标 VM 可能不支持，或者可能只提供有限的支持，用于停止具有异步异常的虚拟线程。例如，当虚拟线程在断点或单步事件处挂起时，它可能仅支持此操作。

      参数：
      throwable - 要抛出的异步异常
      抛出：
      InvalidTypeException - 如果 throwable 不是目标 VM 中的 java.lang.Throwable 实例
      IllegalThreadStateException - 如果线程已终止
      UnsupportedOperationException - 如果线程是虚拟线程并且目标 VM 不支持虚拟线程上的此操作
      VMCannotBeModifiedException - 如果虚拟机是只读的
      参见：

    • interrupt

      void interrupt()
      中断此线程，除非该线程已被调试器挂起。
      抛出：
      VMCannotBeModifiedException - 如果虚拟机是只读的
      参见：

    • status

      int status()
      返回线程的状态。如果线程未挂起，则返回线程的当前状态。如果线程被挂起，则返回挂起前线程的状态（或THREAD_STATUS_UNKNOWN ，如果此信息不可用。isSuspended() 可用于确定线程是否已被挂起。
      返回：
      THREAD_STATUS_UNKNOWN 、THREAD_STATUS_ZOMBIE 、THREAD_STATUS_RUNNING 、THREAD_STATUS_SLEEPING 、THREAD_STATUS_MONITOR 、THREAD_STATUS_WAIT 、THREAD_STATUS_NOT_STARTED 、

    • isSuspended

      boolean isSuspended()
      确定线程是否已被调试器挂起。
      返回：
      true 如果线程当前挂起； false否则。

    • isAtBreakpoint

      boolean isAtBreakpoint()
      确定线程是否在断点处挂起。
      返回：
      true 如果线程当前在断点处停止； false否则。

    • threadGroup

      ThreadGroupReference  threadGroup()
      返回此线程的线程组。
      返回：
      a ThreadGroupReference 镜像目标 VM 中该线程的线程组。

    • frameCount

      int frameCount() throws IncompatibleThreadStateException
      返回线程当前调用堆栈中的堆栈帧数。线程必须被挂起（通常通过对 VM 的中断）来获取此信息，并且它仅在线程再次恢复之前有效。
      返回：
      整数帧数
      抛出：
      IncompatibleThreadStateException - 如果线程未在目标 VM 中挂起

    • frames

      List <StackFrame > frames() throws IncompatibleThreadStateException
      返回一个列表，其中包含线程当前调用堆栈中的每个 StackFrame 。线程必须被挂起（通常通过对 VM 的中断）来获取此信息，并且它仅在线程再次恢复之前有效。
      返回：
      StackFrame 列表，当前帧在前，然后是每个调用者的帧。
      抛出：
      IncompatibleThreadStateException - 如果线程未在目标 VM 中挂起

    • frame

      StackFrame  frame(int index) throws IncompatibleThreadStateException
      返回线程当前调用堆栈中给定索引处的 StackFrame 。索引 0 检索当前帧；更高的索引检索调用者框架。线程必须被挂起（通常通过对 VM 的中断）来获取此信息，并且它仅在线程再次恢复之前有效。
      参数：
      index - 所需的框架
      返回：
      请求的StackFrame
      抛出：
      IncompatibleThreadStateException - 如果线程未在目标 VM 中挂起
      IndexOutOfBoundsException - 如果索引大于或等于 frameCount() 或者为负数。

    • frames

      List <StackFrame > frames(int start, int length) throws IncompatibleThreadStateException
      返回一个列表，其中包含来自线程当前调用堆栈的一系列 StackFrame 镜像。线程必须被挂起（通常通过对 VM 的中断）来获取此信息，并且它仅在线程再次恢复之前有效。
      参数：
      start - 要检索的第一帧的索引。索引 0 表示当前帧。
      length - 要检索的帧数
      返回：
      StackFrame 列表，当前帧在前，然后是每个调用者的帧。
      抛出：
      IncompatibleThreadStateException - 如果线程未在目标 VM 中挂起
      IndexOutOfBoundsException - 如果指定范围不在堆栈帧索引范围内。也就是说，如果满足以下任一条件，则抛出异常： 
        start < 0
  start >= frameCount() 
  length < 0
  (start+length) > frameCount()

    • ownedMonitors

      List <ObjectReference > ownedMonitors() throws IncompatibleThreadStateException
      为线程拥有的每个监视器返回一个包含 ObjectReference 的列表。如果监视器已进入（通过同步语句或进入同步方法）并且尚未通过 Object.wait() 放弃，则监视器由线程拥有。

      并非所有目标虚拟机都支持此操作。使用 VirtualMachine.canGetOwnedMonitorInfo() 确定是否支持该操作。

      返回：
      ObjectReference 对象列表。如果此线程没有任何监视器，则该列表的长度为零。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      IncompatibleThreadStateException - 如果线程未在目标 VM 中挂起

    • ownedMonitorsAndFrames

      List <MonitorInfo > ownedMonitorsAndFrames() throws IncompatibleThreadStateException
      返回一个列表，其中包含线程拥有的每个监视器的 MonitorInfo 对象。如果监视器已进入（通过同步语句或进入同步方法）并且尚未通过 Object.wait() 放弃，则监视器由线程拥有。

      并非所有目标虚拟机都支持此操作。使用 VirtualMachine.canGetMonitorFrameInfo() 确定是否支持该操作。

      返回：
      MonitorInfo 对象列表。如果此线程没有任何监视器，则该列表的长度为零。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      IncompatibleThreadStateException - 如果线程未在目标 VM 中挂起
      自从：
      1.6

    • currentContendedMonitor

      ObjectReference  currentContendedMonitor() throws IncompatibleThreadStateException
      为监视器返回一个 ObjectReference ，如果有的话，这个线程当前正在等待。线程可以通过进入同步方法、同步语句或 Object.wait() 来等待监视器。 status() 方法可用于区分前两种情况和第三种情况。

      并非所有目标虚拟机都支持此操作。使用 VirtualMachine.canGetCurrentContendedMonitor() 确定是否支持该操作。

      返回：
      与竞争监视器对应的 ObjectReference ，如果它不在等待监视器，则为 null。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      IncompatibleThreadStateException - 如果线程未在目标 VM 中挂起

    • popFrames

      void popFrames(StackFrame  frame) throws IncompatibleThreadStateException
      弹出堆栈帧。

      直到并包括 frame 的所有帧都从堆栈中弹出。参数 frame 之前的帧将成为当前帧。

      执行此操作后，此线程将在创建 frame 的目标方法的 invoke 指令处挂起。 frame 的方法可以通过指令中的一个步骤重新进入。

      操作数堆栈已恢复，但是，对被调用方法中发生的参数的任何更改仍然存在。例如，如果方法 foo ：

        void foo(int x) {
    System.out.println("Foo: " + x);
    x = 4;
    System.out.println("pop here");
  }
      被 foo(7) 调用， foo 在第二个 println 弹出并恢复，它将打印： Foo: 4 。

      弹出框架获得的锁在弹出时释放。这适用于弹出的同步方法，以及其中的任何同步块。

      finally 块不被执行。

      除了此线程的执行点和锁之外，状态的任何方面都不受此调用的影响。具体来说，字段的值是不变的，外部资源（如 I/O 流）也是如此。此外，目标程序可能处于正常程序流程无法实现的状态；例如，锁获取的顺序可能会被扰乱。因此，目标程序可能会以不同于用户预期的方式进行。

      必须挂起指定的线程。

      此线程的所有 StackFrame 对象均无效。

      当线程是虚拟线程时，目标 VM 可能不支持或可能仅提供有限的支持来弹出堆栈帧。例如，当虚拟线程在断点或单步事件处挂起时，它可能仅支持此操作。

      此方法不生成任何事件。

      没有任何帧通过并包括调用者的帧frame可能是原生的。

      并非所有目标虚拟机都支持此操作。使用 VirtualMachine.canPopFrames() 确定是否支持该操作。

      参数：
      frame - 要弹出的堆栈框架。 frame 在此线程的调用堆栈上。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作 - 请参阅 VirtualMachine.canPopFrames() 。
      IncompatibleThreadStateException - 如果此线程未挂起。
      IllegalArgumentException - 如果 frame 不在此线程的调用堆栈上。
      OpaqueFrameException - 如果此线程是虚拟线程并且目标 VM 无法弹出帧。
      NativeMethodException - 如果要弹出的帧之一是本机方法的帧，或者如果之前的帧frame是原生的。
      InvalidStackFrameException - 如果 frame 无效。一旦该线程恢复，栈帧就不再有效。如果没有更多帧，也会抛出此异常。
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的。
      自从：
      1.4
      参见：

    • forceEarlyReturn

      void forceEarlyReturn(Value  value) throws InvalidTypeException , ClassNotLoadedException , IncompatibleThreadStateException
      强制方法在到达返回语句之前返回。

      提前返回的方法称为被调用方法。被调用的方法是调用此方法时指定线程的当前方法（由 Java 虚拟机规范中的框架部分定义）。

      线程必须挂起。在此线程上恢复执行 Java 编程语言代码时发生返回。在调用此方法和恢复线程执行之间，堆栈的状态是未定义的。

      当线程是虚拟线程时，目标 VM 可能不支持或可能仅提供有限的支持以强制方法返回。例如，当虚拟线程在断点或单步事件处挂起时，它可能仅支持此操作。

      在被调用的方法中没有执行进一步的指令。具体来说，finally 块不会被执行。注意：这可能会导致应用程序中出现不一致的状态。

      通过调用被调用方法（如果是同步方法）获得的锁和通过在被调用方法内部进入同步块获得的锁被释放。注意：这不适用于本机锁或 java.util.concurrent.locks 锁。

      事件（例如 MethodExit）的生成与正常返回中的一样。

      被调用的方法必须是非本机 Java 编程语言方法。在堆栈上只有一帧的线程上强制返回会导致线程在恢复时退出。

      value 参数是该方法要返回的值。如果方法的返回类型为 void，则值必须为 VoidValue 。对象值必须是与方法返回类型兼容的赋值（这意味着方法返回类型必须通过封闭类的类加载器加载）。原始值必须是与方法返回类型兼容的赋值，或者必须可转换为变量类型而不丢失信息。有关分配兼容性的更多信息，请参阅 JLS 5.2 节。

      并非所有目标虚拟机都支持此操作。使用 VirtualMachine.canForceEarlyReturn() 确定是否支持该操作。

      参数：
      value - 该方法要返回的值。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作 - 请参阅 canForceEarlyReturn()
      IncompatibleThreadStateException - 如果此线程未挂起。
      OpaqueFrameException - 如果此线程是虚拟线程并且目标 VM 无法强制方法返回。
      NativeMethodException - 如果要返回的帧是本地方法的帧。
      InvalidStackFrameException - 如果没有帧。
      InvalidTypeException - 如果值的类型与方法的返回类型不匹配。
      ClassNotLoadedException - 如果方法的返回类型尚未通过适当的类加载器加载。
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的。
      自从：
      1.6
      参见：

    • isVirtual

      default boolean isVirtual()
      isVirtual 是 Java 平台的反射预览 API。
      预览功能可能会在未来的版本中删除，或升级为 Java 平台的永久功能。
      如果线程是 虚拟线程，则返回 true。
      实现要求：
      默认实现抛出 UnsupportedOperationException 。
      返回：
      如果线程是虚拟线程则为真
      自从：
      19