Interface ThreadReference
- All Superinterfaces:
- Mirror,- ObjectReference,- Value
ObjectReference with additional
 access to thread-specific information from the target VM.- Since:
- 1.3
- 
Field SummaryFieldsModifier and TypeFieldDescriptionstatic final intThread is waiting on a java monitorstatic final intThread has not yet been startedstatic final intThread is runnablestatic final intThread is sleeping -Thread.sleep(long).static final intThread status is unknownstatic final intThread is waiting -Object.wait()orLockSupport.park().static final intThread has completed executionFields declared in interface com.sun.jdi.ObjectReferenceINVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
- 
Method SummaryModifier and TypeMethodDescriptionReturns anObjectReferencefor the monitor, if any, for which this thread is currently waiting.voidforceEarlyReturn(Value value) Force a method to return before it reaches a return statement.frame(int index) Returns theStackFrameat the given index in the thread's current call stack.intReturns the number of stack frames in the thread's current call stack.frames()Returns a List containing eachStackFramein the thread's current call stack.frames(int start, int length) Returns a List containing a range ofStackFramemirrors from the thread's current call stack.voidInterrupts this thread unless the thread has been suspended by the debugger.booleanDetermines whether the thread is suspended at a breakpoint.booleanDetermines whether the thread has been suspended by the the debugger.default booleanReturnstrueif the thread is a virtual thread.name()Returns the name of this thread.Returns a List containing anObjectReferencefor each monitor owned by the thread.Returns a List containing aMonitorInfoobject for each monitor owned by the thread.voidpopFrames(StackFrame frame) Pop stack frames.voidresume()Resumes this thread.intstatus()Returns the thread's status.voidstop(ObjectReference throwable) Stops this thread with an asynchronous exception.voidsuspend()Suspends this thread.intReturns the number of pending suspends for this thread.Returns this thread's thread group.Methods declared in interface com.sun.jdi.MirrortoString, virtualMachineMethods declared in interface com.sun.jdi.ObjectReferencedisableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
- 
Field Details- 
THREAD_STATUS_UNKNOWNstatic final int THREAD_STATUS_UNKNOWNThread status is unknown- See Also:
 
- 
THREAD_STATUS_ZOMBIEstatic final int THREAD_STATUS_ZOMBIEThread has completed execution- See Also:
 
- 
THREAD_STATUS_RUNNINGstatic final int THREAD_STATUS_RUNNINGThread is runnable- See Also:
 
- 
THREAD_STATUS_SLEEPING
- 
THREAD_STATUS_MONITORstatic final int THREAD_STATUS_MONITORThread is waiting on a java monitor- See Also:
 
- 
THREAD_STATUS_WAITstatic final int THREAD_STATUS_WAITThread is waiting -Object.wait()orLockSupport.park(). A virtual thread that is sleeping inThread.sleep(long)may have this thread status instead ofTHREAD_STATUS_SLEEPING.- See Also:
 
- 
THREAD_STATUS_NOT_STARTEDstatic final int THREAD_STATUS_NOT_STARTEDThread has not yet been started- See Also:
 
 
- 
- 
Method Details- 
name
- 
suspendvoid suspend()Suspends this thread. The thread can be resumed throughresume()or resumed with other threads throughVirtualMachine.resume().Suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed (through resume()orVirtualMachine.resume()) the same number of times it has been suspended.Suspending single threads with this method is inherently deadlock-prone. 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. - Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only
- See Also:
 
- 
resumevoid resume()Resumes this thread. If this thread was not previously suspended throughsuspend()or throughVirtualMachine.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 viaEventSet.resume().- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only
- See Also:
 
- 
suspendCountint suspendCount()Returns the number of pending suspends for this thread. Seesuspend()for an explanation of counted suspends.- Returns:
- pending suspend count as an integer
 
- 
stopStops this thread with an asynchronous exception. A debugger thread in the target VM will stop this thread with the givenThrowableobject.This method may be used to send an asynchronous exception to a virtual thread when it is suspended at an event. An implementation may support sending an asynchronous exception to a suspended virtual thread in other cases. - Parameters:
- throwable- the asynchronous exception to throw
- Throws:
- InvalidTypeException- if- throwableis not an instance of java.lang.Throwable in the target VM
- IllegalThreadStateException- if the thread has terminated, or if the thread is a virtual thread and was not suspended
- OpaqueFrameException- if the thread is a suspended virtual thread and the implementation was unable to throw an asynchronous exception from the thread's current frame
- VMCannotBeModifiedException- if the VirtualMachine is read-only
- See Also:
 
- 
interruptvoid interrupt()Interrupts this thread unless the thread has been suspended by the debugger.- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only
- See Also:
 
- 
statusint 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_UNKNOWNif this information is not available.isSuspended()can be used to determine if the thread has been suspended.
- 
isSuspendedboolean isSuspended()Determines whether the thread has been suspended by the the debugger.- Returns:
- trueif the thread is currently suspended;- falseotherwise.
 
- 
isAtBreakpointboolean isAtBreakpoint()Determines whether the thread is suspended at a breakpoint.- Returns:
- trueif the thread is currently stopped at a breakpoint;- falseotherwise.
 
- 
threadGroupThreadGroupReference threadGroup()Returns this thread's thread group.- Returns:
- a ThreadGroupReferencethat mirrors this thread's thread group in the target VM.
 
- 
frameCountReturns 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- if the thread is not suspended in the target VM
 
- 
framesReturns a List containing eachStackFramein 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 StackFramewith the current frame first followed by each caller's frame.
- Throws:
- IncompatibleThreadStateException- if the thread is not suspended in the target VM
 
- 
frameReturns theStackFrameat 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- if the thread is not suspended in the target VM
- IndexOutOfBoundsException- if the index is greater than or equal to- frameCount()or is negative.
 
- 
framesReturns a List containing a range ofStackFramemirrors 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 StackFramewith the current frame first followed by each caller's frame.
- Throws:
- IncompatibleThreadStateException- if the thread is not suspended in the target VM
- IndexOutOfBoundsException- 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()
 
- 
ownedMonitorsReturns a List containing anObjectReferencefor 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 throughObject.wait().Not all target virtual machines support this operation. Use VirtualMachine.canGetOwnedMonitorInfo()to determine if the operation is supported.- Returns:
- a List of ObjectReferenceobjects. The list has zero length if no monitors are owned by this thread.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation.
- IncompatibleThreadStateException- if the thread is not suspended in the target VM
 
- 
ownedMonitorsAndFramesReturns a List containing aMonitorInfoobject 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 throughObject.wait().Not all target virtual machines support this operation. Use VirtualMachine.canGetMonitorFrameInfo()to determine if the operation is supported.- Returns:
- a List of MonitorInfoobjects. The list has zero length if no monitors are owned by this thread.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation.
- IncompatibleThreadStateException- if the thread is not suspended in the target VM
- Since:
- 1.6
 
- 
currentContendedMonitorReturns anObjectReferencefor 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()waiting to re-enter the monitor after being notified, interrupted, or timed-out.Not all target virtual machines support this operation. Use VirtualMachine.canGetCurrentContendedMonitor()to determine if the operation is supported.- Returns:
- the ObjectReferencecorresponding to the contended monitor, or null if it is not waiting for a monitor.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation.
- IncompatibleThreadStateException- if the thread is not suspended in the target VM
 
- 
popFramesPop stack frames.All frames up to and including the frameare popped off the stack. The frame previous to the parameterframewill become the current frame.After this operation, this thread will be suspended at the invoke instruction of the target method that created frame. Theframe'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 withfoo(7)andfoois popped at the secondprintlnand 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. This thread must be suspended. All StackFrameobjects for this thread are invalidated.This method may be used to pop frames of a virtual thread when it is suspended at an event. An implementation may support popping the frames of a suspended virtual thread in other cases. 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.- frameis on this thread's call stack.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation - see- VirtualMachine.canPopFrames().
- IncompatibleThreadStateException- if this thread is not suspended.
- IllegalArgumentException- if- frameis not on this thread's call stack.
- OpaqueFrameException- if this thread is a suspended virtual thread and the target VM was unable to pop the frames.
- NativeMethodException- 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- if- framehas 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- if the VirtualMachine is read-only.
- Since:
- 1.4
- See Also:
 
- 
forceEarlyReturnvoid forceEarlyReturn(Value value) throws InvalidTypeException, ClassNotLoadedException, IncompatibleThreadStateException 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. This method may be used to force a return from the current frame of a virtual thread when it is suspended at an event. An implementation may support forcing a return from the current frame of a suspended virtual thread in other cases. 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 valueargument is the value that the method is to return. If the return type of the method is void, then value must be aVoidValue. 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- if the target virtual machine does not support this operation - see- canForceEarlyReturn()
- IncompatibleThreadStateException- if this thread is not suspended.
- OpaqueFrameException- if this thread is a suspended virtual thread and the target VM is unable to force the method to return.
- NativeMethodException- if the frame to be returned from is that of a native method.
- InvalidStackFrameException- if there are no frames.
- InvalidTypeException- if the value's type does not match the method's return type.
- ClassNotLoadedException- if the method's return type has not yet been loaded through the appropriate class loader.
- VMCannotBeModifiedException- if the VirtualMachine is read-only.
- Since:
- 1.6
- See Also:
 
- 
isVirtualdefault boolean isVirtual()Returnstrueif the thread is a virtual thread.- Implementation Requirements:
- The default implementation throws UnsupportedOperationException.
- Returns:
- true if the thread is a virtual thread
- Since:
- 21
 
 
-