ThreadReference (Java SE 19 & JDK 19) (original) (raw)

All Superinterfaces:

[Mirror](Mirror.html "interface in com.sun.jdi"), [ObjectReference](ObjectReference.html "interface in com.sun.jdi"), [Value](Value.html "interface in com.sun.jdi")

A thread object from the target VM. A ThreadReference is an ObjectReference with additional access to thread-specific information from the target VM.

Since:

1.3

• Field Summary

Fields
static final int
Thread is waiting on a java monitor
static final int
Thread has not yet been started
static final int
static final int
static final int
static final int
static final int
Thread has completed execution

• Method Summary

Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting.
void
Force a method to return before it reaches a return statement.
[frame](#frame%28int%29)(int index)
Returns the StackFrame at the given index in the thread's current call stack.
int
Returns the number of stack frames in the thread's current call stack.
[frames](#frames%28%29)()
Returns a List containing each StackFrame in the thread's current call stack.
[frames](#frames%28int,int%29)(int start, int length)
Returns a List containing a range of StackFrame mirrors from the thread's current call stack.
void
[interrupt](#interrupt%28%29)()
Interrupts this thread unless the thread has been suspended by the debugger.
boolean
Determines whether the thread is suspended at a breakpoint.
boolean
Determines whether the thread has been suspended by the the debugger.
default boolean
[isVirtual](#isVirtual%28%29)()
[name](#name%28%29)()
Returns the name of this thread.
Returns a List containing an ObjectReference for each monitor owned by the thread.
Returns a List containing a MonitorInfo object for each monitor owned by the thread.
void
void
[resume](#resume%28%29)()
int
[status](#status%28%29)()
Returns the thread's status.
void
Stops this thread with an asynchronous exception.
void
[suspend](#suspend%28%29)()
int
Returns the number of pending suspends for this thread.
Returns this thread's thread group.

Methods declared in interface com.sun.jdi.ObjectReference

[disableCollection](ObjectReference.html#disableCollection%28%29), [enableCollection](ObjectReference.html#enableCollection%28%29), [entryCount](ObjectReference.html#entryCount%28%29), [equals](ObjectReference.html#equals%28java.lang.Object%29), [getValue](ObjectReference.html#getValue%28com.sun.jdi.Field%29), [getValues](ObjectReference.html#getValues%28java.util.List%29), [hashCode](ObjectReference.html#hashCode%28%29), [invokeMethod](ObjectReference.html#invokeMethod%28com.sun.jdi.ThreadReference,com.sun.jdi.Method,java.util.List,int%29), [isCollected](ObjectReference.html#isCollected%28%29), [owningThread](ObjectReference.html#owningThread%28%29), [referenceType](ObjectReference.html#referenceType%28%29), [referringObjects](ObjectReference.html#referringObjects%28long%29), [setValue](ObjectReference.html#setValue%28com.sun.jdi.Field,com.sun.jdi.Value%29), [uniqueID](ObjectReference.html#uniqueID%28%29), [waitingThreads](ObjectReference.html#waitingThreads%28%29)

Methods declared in interface com.sun.jdi.Value

[type](Value.html#type%28%29)

• Field Details

  • THREAD_STATUS_UNKNOWN

  static final int THREAD_STATUS_UNKNOWN
  Thread status is unknown
  See Also:
  * Constant Field Values

  • THREAD_STATUS_ZOMBIE

  static final int THREAD_STATUS_ZOMBIE
  Thread has completed execution
  See Also:
  * Constant Field Values

  • THREAD_STATUS_RUNNING

  static final int THREAD_STATUS_RUNNING
  Thread is runnable
  See Also:
  * Constant Field Values

  • THREAD_STATUS_SLEEPING

  static final int THREAD_STATUS_SLEEPING
  See Also:
  * Constant Field Values

  • THREAD_STATUS_MONITOR

  static final int THREAD_STATUS_MONITOR
  Thread is waiting on a java monitor
  See Also:
  * Constant Field Values

  • THREAD_STATUS_WAIT

  static final int THREAD_STATUS_WAIT
  See Also:
  * Constant Field Values

  • THREAD_STATUS_NOT_STARTED

  static final int THREAD_STATUS_NOT_STARTED
  Thread has not yet been started
  See Also:
  * Constant Field Values

• Method Details

  • name

  Returns the name of this thread.
  Returns:
  the string containing the thread name.

  • suspend

  void suspend()
  Suspends this thread. The thread can be resumed throughresume() or resumed with other threads throughVirtualMachine.resume().
  Unlike Thread.suspend(), suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed (through resume() or resume()) the same number of times it has been suspended.
  Suspending single threads with this method has the same dangers as Thread.suspend(). If the suspended thread holds a monitor needed by another running thread, deadlock is possible in the target VM (at least until the suspended thread is resumed again).
  The suspended thread is guaranteed to remain suspended until resumed through one of the JDI resume methods mentioned above; the application in the target VM cannot resume the suspended thread through Thread.resume().
  Throws:
  [VMCannotBeModifiedException](VMCannotBeModifiedException.html "class in com.sun.jdi") - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

  • resume

  void resume()
  Resumes this thread. If this thread was not previously suspended through suspend() or through VirtualMachine.suspend(), or because of a SUSPEND_ALL or SUSPEND_EVENT_THREAD event, then invoking this method has no effect. Otherwise, the count of pending suspends on this thread is decremented. If it is decremented to 0, the thread will continue to execute. Note: the normal way to resume from an event related suspension is via EventSet.resume().
  Throws:
  [VMCannotBeModifiedException](VMCannotBeModifiedException.html "class in com.sun.jdi") - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

  • suspendCount

  int suspendCount()
  Returns the number of pending suspends for this thread. Seesuspend() for an explanation of counted suspends.
  Returns:
  pending suspend count as an integer

  • stop

  Stops this thread with an asynchronous exception. A debugger thread in the target VM will stop this thread with the given Throwable object.
  The target VM may not support, or may only provide limited support, for stopping a virtual thread with an asynchronous exception. It may, for example, only support this operation when the virtual thread is suspended at a breakpoint or singlestep event.
  Parameters:
  throwable - the asynchronous exception to throw
  Throws:
  [InvalidTypeException](InvalidTypeException.html "class in com.sun.jdi") - if throwable is not an instance of java.lang.Throwable in the target VM
  [IllegalThreadStateException](../../../../java.base/java/lang/IllegalThreadStateException.html "class in java.lang") - if the thread has terminated
  [UnsupportedOperationException](../../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - if the thread is a virtual thread and the target VM does not support this operation on virtual threads
  [VMCannotBeModifiedException](VMCannotBeModifiedException.html "class in com.sun.jdi") - if the VirtualMachine is read-only
  See Also:
  * VirtualMachine.canBeModified()

  • interrupt

  void interrupt()
  Interrupts this thread unless the thread has been suspended by the debugger.
  Throws:
  [VMCannotBeModifiedException](VMCannotBeModifiedException.html "class in com.sun.jdi") - if the VirtualMachine is read-only
  See Also:
  * Thread.interrupt()
  * VirtualMachine.canBeModified()

  • status

  int status()
  Returns the thread's status. If the thread is not suspended the thread's current status is returned. If the thread is suspended, the thread's status before the suspension is returned (orTHREAD_STATUS_UNKNOWN if this information is not available.isSuspended() can be used to determine if the thread has been suspended.
  Returns:
  one ofTHREAD_STATUS_UNKNOWN,THREAD_STATUS_ZOMBIE,THREAD_STATUS_RUNNING,THREAD_STATUS_SLEEPING,THREAD_STATUS_MONITOR,THREAD_STATUS_WAIT,THREAD_STATUS_NOT_STARTED,

  • isSuspended

  boolean isSuspended()
  Determines whether the thread has been suspended by the the debugger.
  Returns:
  true if the thread is currently suspended;false otherwise.

  • isAtBreakpoint

  boolean isAtBreakpoint()
  Determines whether the thread is suspended at a breakpoint.
  Returns:
  true if the thread is currently stopped at a breakpoint; false otherwise.

  • threadGroup

  Returns this thread's thread group.
  Returns:
  a ThreadGroupReference that mirrors this thread's thread group in the target VM.

  • frameCount

  Returns the number of stack frames in the thread's current call stack. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.
  Returns:
  an integer frame count
  Throws:
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if the thread is not suspended in the target VM

  • frames

  Returns a List containing each StackFrame in the thread's current call stack. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.
  Returns:
  a List of StackFrame with the current frame first followed by each caller's frame.
  Throws:
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if the thread is not suspended in the target VM

  • frame

  Returns the StackFrame at the given index in the thread's current call stack. Index 0 retrieves the current frame; higher indices retrieve caller frames. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.
  Parameters:
  index - the desired frame
  Returns:
  the requested StackFrame
  Throws:
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if the thread is not suspended in the target VM
  [IndexOutOfBoundsException](../../../../java.base/java/lang/IndexOutOfBoundsException.html "class in java.lang") - if the index is greater than or equal to frameCount() or is negative.

  • frames

  Returns a List containing a range of StackFrame mirrors from the thread's current call stack. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.
  Parameters:
  start - the index of the first frame to retrieve. Index 0 represents the current frame.
  length - the number of frames to retrieve
  Returns:
  a List of StackFrame with the current frame first followed by each caller's frame.
  Throws:
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if the thread is not suspended in the target VM
  [IndexOutOfBoundsException](../../../../java.base/java/lang/IndexOutOfBoundsException.html "class in java.lang") - if the specified range is not within the range of stack frame indices. That is, the exception is thrown if any of the following are true:
  start < 0
  start >= frameCount()
  length < 0
  (start+length) > frameCount()

  • ownedMonitors

  Returns a List containing an ObjectReference for each monitor owned by the thread. A monitor is owned by a thread if it has been entered (via the synchronized statement or entry into a synchronized method) and has not been relinquished through Object.wait().
  Not all target virtual machines support this operation. Use VirtualMachine.canGetOwnedMonitorInfo() to determine if the operation is supported.
  Returns:
  a List of ObjectReference objects. The list has zero length if no monitors are owned by this thread.
  Throws:
  [UnsupportedOperationException](../../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - if the target virtual machine does not support this operation.
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if the thread is not suspended in the target VM

  • ownedMonitorsAndFrames

  Returns a List containing a MonitorInfo object for each monitor owned by the thread. A monitor is owned by a thread if it has been entered (via the synchronized statement or entry into a synchronized method) and has not been relinquished through Object.wait().
  Not all target virtual machines support this operation. Use VirtualMachine.canGetMonitorFrameInfo() to determine if the operation is supported.
  Returns:
  a List of MonitorInfo objects. The list has zero length if no monitors are owned by this thread.
  Throws:
  [UnsupportedOperationException](../../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - if the target virtual machine does not support this operation.
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if the thread is not suspended in the target VM
  Since:
  1.6

  • currentContendedMonitor

  Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting. The thread can be waiting for a monitor through entry into a synchronized method, the synchronized statement, orObject.wait(). The status() method can be used to differentiate between the first two cases and the third.
  Not all target virtual machines support this operation. Use VirtualMachine.canGetCurrentContendedMonitor() to determine if the operation is supported.
  Returns:
  the ObjectReference corresponding to the contended monitor, or null if it is not waiting for a monitor.
  Throws:
  [UnsupportedOperationException](../../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - if the target virtual machine does not support this operation.
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if the thread is not suspended in the target VM

  • popFrames

  Pop stack frames.
  All frames up to and including the frame are popped off the stack. The frame previous to the parameter frame will become the current frame.
  After this operation, this thread will be suspended at the invoke instruction of the target method that created frame. The frame's method can be reentered with a step into the instruction.
  The operand stack is restored, however, any changes to the arguments that occurred in the called method, remain. For example, if the method foo:
  void foo(int x) {
  System.out.println("Foo: " + x);
  x = 4;
  System.out.println("pop here");
  }

  was called with foo(7) and foo is popped at the second println and resumed, it will print: Foo: 4.
  Locks acquired by a popped frame are released when it is popped. This applies to synchronized methods that are popped, and to any synchronized blocks within them.
  Finally blocks are not executed.
  No aspect of state, other than this thread's execution point and locks, is affected by this call. Specifically, the values of fields are unchanged, as are external resources such as I/O streams. Additionally, the target program might be placed in a state that is impossible with normal program flow; for example, order of lock acquisition might be perturbed. Thus the target program may proceed differently than the user would expect.
  The specified thread must be suspended.
  All StackFrame objects for this thread are invalidated.
  The target VM may not support, or may only provide limited support, for popping stack frames when the thread is a virtual thread. It may, for example, only support this operation when the virtual thread is suspended at a breakpoint or singlestep event.
  No events are generated by this method.
  None of the frames through and including the frame for the caller of frame may be native.
  Not all target virtual machines support this operation. Use VirtualMachine.canPopFrames() to determine if the operation is supported.
  Parameters:
  frame - Stack frame to pop. frame is on this thread's call stack.
  Throws:
  [UnsupportedOperationException](../../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - if the target virtual machine does not support this operation - seeVirtualMachine.canPopFrames().
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if this thread is not suspended.
  [IllegalArgumentException](../../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if frame is not on this thread's call stack.
  [OpaqueFrameException](OpaqueFrameException.html "class in com.sun.jdi") - if this thread is a virtual thread and the target VM is unable to pop the frames.
  [NativeMethodException](NativeMethodException.html "class in com.sun.jdi") - if one of the frames that would be popped is that of a native method or if the frame previous to_frame_ is native.
  [InvalidStackFrameException](InvalidStackFrameException.html "class in com.sun.jdi") - if frame has become invalid. Once this thread is resumed, the stack frame is no longer valid. This exception is also thrown if there are no more frames.
  [VMCannotBeModifiedException](VMCannotBeModifiedException.html "class in com.sun.jdi") - if the VirtualMachine is read-only.
  Since:
  1.4
  See Also:
  * VirtualMachine.canBeModified()

  • forceEarlyReturn

  Force a method to return before it reaches a return statement.
  The method which will return early is referred to as the called method. The called method is the current method (as defined by the Frames section in the Java Virtual Machine Specification) for the specified thread at the time this method is called.
  The thread must be suspended. The return occurs when execution of Java programming language code is resumed on this thread. Between the call to this method and resumption of thread execution, the state of the stack is undefined.
  The target VM may not support, or may only provide limited support, for forcing a method to return when the thread is a virtual thread. It may, for example, only support this operation when the virtual thread is suspended at a breakpoint or singlestep event.
  No further instructions are executed in the called method. Specifically, finally blocks are not executed. Note: this can cause inconsistent states in the application.
  A lock acquired by calling the called method (if it is a synchronized method) and locks acquired by entering synchronized blocks within the called method are released. Note: this does not apply to native locks or java.util.concurrent.locks locks.
  Events, such as MethodExit, are generated as they would be in a normal return.
  The called method must be a non-native Java programming language method. Forcing return on a thread with only one frame on the stack causes the thread to exit when resumed.
  The value argument is the value that the method is to return. If the return type of the method is void, then value must be a VoidValue. Object values must be assignment compatible with the method return type (This implies that the method return type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the method return type or must be convertible to the variable type without loss of information. See JLS section 5.2 for more information on assignment compatibility.
  Not all target virtual machines support this operation. Use VirtualMachine.canForceEarlyReturn() to determine if the operation is supported.
  Parameters:
  value - the value the method is to return.
  Throws:
  [UnsupportedOperationException](../../../../java.base/java/lang/UnsupportedOperationException.html "class in java.lang") - if the target virtual machine does not support this operation - seecanForceEarlyReturn()
  [IncompatibleThreadStateException](IncompatibleThreadStateException.html "class in com.sun.jdi") - if this thread is not suspended.
  [OpaqueFrameException](OpaqueFrameException.html "class in com.sun.jdi") - if this thread is a virtual thread and the target VM is unable to force the method to return.
  [NativeMethodException](NativeMethodException.html "class in com.sun.jdi") - if the frame to be returned from is that of a native method.
  [InvalidStackFrameException](InvalidStackFrameException.html "class in com.sun.jdi") - if there are no frames.
  [InvalidTypeException](InvalidTypeException.html "class in com.sun.jdi") - if the value's type does not match the method's return type.
  [ClassNotLoadedException](ClassNotLoadedException.html "class in com.sun.jdi") - if the method's return type has not yet been loaded through the appropriate class loader.
  [VMCannotBeModifiedException](VMCannotBeModifiedException.html "class in com.sun.jdi") - if the VirtualMachine is read-only.
  Since:
  1.6
  See Also:
  * VirtualMachine.canBeModified()

  • isVirtual

  default boolean isVirtual()
  isVirtual is a reflective preview API of the Java platform.
  Implementation Requirements:
  The default implementation throws UnsupportedOperationException.
  Returns:
  true if the thread is a virtual thread
  Since:
  19