public interface ThreadReference extends ObjectReference
ObjectReference
with additional
access to thread-specific information from the target VM.Modifier and Type | Field and Description |
---|---|
static int |
THREAD_STATUS_MONITOR
Thread is waiting on a java monitor
|
static int |
THREAD_STATUS_NOT_STARTED
Thread has not yet been started
|
static int |
THREAD_STATUS_RUNNING
Thread is runnable
|
static int |
THREAD_STATUS_SLEEPING
Thread is sleeping - Thread.sleep() or JVM_Sleep() was called
|
static int |
THREAD_STATUS_UNKNOWN
Thread status is unknown
|
static int |
THREAD_STATUS_WAIT
Thread is waiting - Object.wait() or JVM_MonitorWait() was called
|
static int |
THREAD_STATUS_ZOMBIE
Thread has completed execution
|
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
Modifier and Type | Method and Description |
---|---|
ObjectReference |
currentContendedMonitor()
Returns an
ObjectReference for the monitor, if any,
for which this thread is currently waiting. |
void |
forceEarlyReturn(Value value)
Force a method to return before it reaches a return
statement.
|
StackFrame |
frame(int index)
Returns the
StackFrame at the given index in the
thread's current call stack. |
int |
frameCount()
Returns the number of stack frames in the thread's current
call stack.
|
List<StackFrame> |
frames()
Returns a List containing each
StackFrame in the
thread's current call stack. |
List<StackFrame> |
frames(int start,
int length)
Returns a List containing a range of
StackFrame mirrors
from the thread's current call stack. |
void |
interrupt()
Interrupts this thread unless the thread has been suspended by the
debugger.
|
boolean |
isAtBreakpoint()
Determines whether the thread is suspended at a breakpoint.
|
boolean |
isSuspended()
Determines whether the thread has been suspended by the
the debugger.
|
String |
name()
Returns the name of this thread.
|
List<ObjectReference> |
ownedMonitors()
Returns a List containing an
ObjectReference for
each monitor owned by the thread. |
List<MonitorInfo> |
ownedMonitorsAndFrames()
Returns a List containing a
MonitorInfo object for
each monitor owned by the thread. |
void |
popFrames(StackFrame frame)
Pop stack frames.
|
void |
resume()
Resumes this thread.
|
int |
status()
Returns the thread's status.
|
void |
stop(ObjectReference throwable)
Stops this thread with an asynchronous exception.
|
void |
suspend()
Suspends this thread.
|
int |
suspendCount()
Returns the number of pending suspends for this thread.
|
ThreadGroupReference |
threadGroup()
Returns this thread's thread group.
|
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
toString, virtualMachine
static final int THREAD_STATUS_UNKNOWN
static final int THREAD_STATUS_ZOMBIE
static final int THREAD_STATUS_RUNNING
static final int THREAD_STATUS_SLEEPING
static final int THREAD_STATUS_MONITOR
static final int THREAD_STATUS_WAIT
static final int THREAD_STATUS_NOT_STARTED
String name()
void suspend()
resume()
or resumed with other threads through
VirtualMachine.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()
.
VMCannotBeModifiedException
- if the VirtualMachine is read-only - see VirtualMachine.canBeModified()
.void resume()
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()
.VMCannotBeModifiedException
- if the VirtualMachine is read-only - see VirtualMachine.canBeModified()
.int suspendCount()
suspend()
for an explanation of counted suspends.void stop(ObjectReference throwable) throws InvalidTypeException
Throwable
object.throwable
- the asynchronous exception to throw.InvalidTypeException
- if throwable
is not
an instance of java.lang.Throwable in the target VM.VMCannotBeModifiedException
- if the VirtualMachine is read-only - see VirtualMachine.canBeModified()
.Thread.stop(Throwable)
void interrupt()
VMCannotBeModifiedException
- if the VirtualMachine is read-only - see VirtualMachine.canBeModified()
.Thread.interrupt()
int status()
THREAD_STATUS_UNKNOWN
if this information is not available.
isSuspended()
can be used to determine if the thread has been
suspended.boolean isSuspended()
true
if the thread is currently suspended;
false
otherwise.boolean isAtBreakpoint()
true
if the thread is currently stopped at
a breakpoint; false
otherwise.ThreadGroupReference threadGroup()
ThreadGroupReference
that mirrors this thread's
thread group in the target VM.int frameCount() throws IncompatibleThreadStateException
IncompatibleThreadStateException
- if the thread is
not suspended in the target VMList<StackFrame> frames() throws IncompatibleThreadStateException
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.StackFrame
with the current frame first
followed by each caller's frame.IncompatibleThreadStateException
- if the thread is
not suspended in the target VMStackFrame frame(int index) throws IncompatibleThreadStateException
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.index
- the desired frameStackFrame
IncompatibleThreadStateException
- if the thread is
not suspended in the target VMIndexOutOfBoundsException
- if the index is greater than
or equal to frameCount()
or is negative.List<StackFrame> frames(int start, int length) throws IncompatibleThreadStateException
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.start
- the index of the first frame to retrieve.
Index 0 represents the current frame.length
- the number of frames to retrieveStackFrame
with the current frame first
followed by each caller's frame.IncompatibleThreadStateException
- if the thread is
not suspended in the target VMIndexOutOfBoundsException
- if the specified range is not
within the range of stack frame indicies.
That is, the exception is thrown if any of the following are true:
start < 0 start >=frameCount()
length < 0 (start+length) >frameCount()
List<ObjectReference> ownedMonitors() throws IncompatibleThreadStateException
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(long)
.
Not all target virtual machines support this operation.
Use VirtualMachine.canGetOwnedMonitorInfo()
to determine if the operation is supported.
ObjectReference
objects. The list
has zero length if no monitors are owned by this thread.UnsupportedOperationException
- if
the target virtual machine does not support this
operation.IncompatibleThreadStateException
- if the thread is
not suspended in the target VMList<MonitorInfo> ownedMonitorsAndFrames() throws IncompatibleThreadStateException
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(long)
.
Not all target virtual machines support this operation.
Use VirtualMachine.canGetMonitorFrameInfo()
to determine if the operation is supported.
MonitorInfo
objects. The list
has zero length if no monitors are owned by this thread.UnsupportedOperationException
- if
the target virtual machine does not support this
operation.IncompatibleThreadStateException
- if the thread is
not suspended in the target VMObjectReference currentContendedMonitor() throws IncompatibleThreadStateException
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, or
Object.wait(long)
. 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.
ObjectReference
corresponding to the
contended monitor, or null if it is not waiting for a monitor.UnsupportedOperationException
- if
the target virtual machine does not support this
operation.IncompatibleThreadStateException
- if the thread is
not suspended in the target VMvoid popFrames(StackFrame frame) throws IncompatibleThreadStateException
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.
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.
frame
- Stack frame to pop. frame
is on this
thread's call stack.UnsupportedOperationException
- if
the target virtual machine does not support this
operation - see
VirtualMachine.canPopFrames()
.IncompatibleThreadStateException
- if this
thread is not suspended.IllegalArgumentException
- if frame
is not on this thread's call stack.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 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
- if the VirtualMachine is read-only - see VirtualMachine.canBeModified()
.void forceEarlyReturn(Value value) throws InvalidTypeException, ClassNotLoadedException, IncompatibleThreadStateException
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.
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.
value
- the value the method is to return.UnsupportedOperationException
- if
the target virtual machine does not support this
operation - see
canForceEarlyReturn()
IncompatibleThreadStateException
- if this
thread is not suspended.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 - see VirtualMachine.canBeModified()
.
Copyright © 1999, 2020, Oracle and/or its affiliates. All rights reserved.