Module jdk.jdi
Package com.sun.jdi

Interface ThreadReference

所有超接口:
Mirror, ObjectReference, Value
public interface ThreadReference extends ObjectReference
来自目标VM的线程对象。ThreadReference是一个ObjectReference，额外提供了从目标VM获取线程特定信息的访问权限。
自JDK版本:
1.3

  • Field Details

  • Method Details

    • 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对象停止此线程。

      此方法可用于在事件暂停时向虚拟线程发送异步异常。实现可能支持在其他情况下向暂停的虚拟线程发送异步异常。

      参数:
      throwable - 要抛出的异步异常
      抛出:
      InvalidTypeException - 如果throwable不是目标VM中java.lang.Throwable的实例
      IllegalThreadStateException - 如果线程已终止，或者如果线程是虚拟线程并且未被暂停
      OpaqueFrameException - 如果线程是暂停的虚拟线程，并且实现无法从线程的当前帧中抛出异步异常
      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()
      返回此线程的线程组。
      返回值:
      一个在目标虚拟机中反映此线程线程组的 ThreadGroupReference。

    • frameCount

      int frameCount() throws IncompatibleThreadStateException
      返回线程当前调用堆栈中的帧数。必须暂停线程（通常通过对虚拟机的中断）才能获取此信息，且仅在线程再次恢复之前有效。
      返回值:
      一个整数帧计数
      抛出:
      IncompatibleThreadStateException - 如果线程在目标虚拟机中未被暂停

    • frames

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

    • frame

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

    • frames

      List<StackFrame> frames(int start, int length) throws IncompatibleThreadStateException
      返回一个包含线程当前调用堆栈中一系列 StackFrame 镜像的列表。必须暂停线程（通常通过对虚拟机的中断）才能获取此信息，且仅在线程再次恢复之前有效。
      参数:
      start - 要检索的第一个帧的索引。索引 0 代表当前帧。
      length - 要检索的帧数
      返回值:
      一个包含当前帧在前，然后是每个调用者帧的 StackFrame 列表。
      抛出:
      IncompatibleThreadStateException - 如果线程在目标虚拟机中未被暂停
      IndexOutOfBoundsException - 如果指定范围不在堆栈帧索引范围内。也就是说，如果以下任何情况为真，则抛出异常： 
          start < 0
    start >= frameCount()
    length < 0
    (start+length) > frameCount()

    • ownedMonitors

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

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

      返回值:
      一个包含 ObjectReference 对象的列表。如果此线程未拥有任何监视器，则列表长度为零。
      抛出:
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      IncompatibleThreadStateException - 如果线程在目标虚拟机中未被暂停

    • ownedMonitorsAndFrames

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

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

      返回值:
      一个包含 MonitorInfo 对象的列表。如果此线程未拥有任何监视器，则列表长度为零。
      抛出:
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      IncompatibleThreadStateException - 如果线程在目标虚拟机中未被暂停
      自版本:
      1.6

    • currentContendedMonitor

      ObjectReference currentContendedMonitor() throws IncompatibleThreadStateException
      返回一个 ObjectReference，表示此线程当前正在等待的监视器（如果有）。线程可以通过进入同步方法、synchronized 语句或 Object.wait() 来等待监视器。可以使用 VirtualMachine.canGetCurrentContendedMonitor() 来确定是否支持该操作。
      返回值:
      对应于争用监视器的 ObjectReference，如果它未等待监视器则为 null。
      抛出:
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      IncompatibleThreadStateException - 如果线程在目标虚拟机中未被暂停

    • popFrames

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

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

      此操作后，此线程将在创建 frame 的目标方法的调用指令处暂停。可以通过步入指令重新进入 frame 的方法。

      操作数栈将被恢复，但是在调用方法中发生的任何参数更改将保留。例如，如果方法 foo:

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

      弹出的帧获取的锁将被释放。这适用于被弹出的同步方法以及其中的任何同步块。

      finally 块不会被执行。

      此调用不会影响除此线程的执行点和锁之外的任何状态。具体来说，字段的值不会改变，外部资源如 I/O 流也不会改变。此外，目标程序可能处于正常程序流无法达到的状态；例如，锁获取顺序可能会被扰乱。因此，目标程序可能会与用户的预期不同。

      此线程必须被暂停。

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

      当此线程在事件处暂停时，可以使用此方法弹出虚拟线程的帧。实现可能支持在其他情况下弹出暂停的虚拟线程的帧。

      此方法不会生成任何事件。

      通过此方法，不得有任何帧通过并包括 frame 的调用者帧为本地帧。

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

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

    • forceEarlyReturn

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

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

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

      此方法可用于在事件中强制从虚拟线程的当前帧返回。实现可能支持在其他情况下强制从挂起的虚拟线程的当前帧返回。

      被调用方法中不会执行进一步的指令。特别地，finally 块不会执行。注意：这可能导致应用程序中的不一致状态。

      通过调用被调用方法（如果它是同步方法）获取的锁以及在被调用方法中进入同步块时获取的锁将被释放。注意：这不适用于本地锁或 java.util.concurrent.locks 锁。

      事件，如 MethodExit，会生成与正常返回时相同。

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

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

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

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

    • isVirtual

      default boolean isVirtual()
      如果线程是一个虚拟线程，则返回true。
      实现要求:
      默认实现会抛出UnsupportedOperationException。
      返回:
      如果线程是虚拟线程，则返回true
      自从:
      21