Java Debug Interface

com.sun.jdi
Interface ThreadReference

All Superinterfaces:
Mirror, ObjectReference, Value

public interface ThreadReference
extends ObjectReference

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
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 - Thread.wait() or JVM_MonitorWait() was called
static int THREAD_STATUS_ZOMBIE
          Thread has completed execution
 
Fields inherited from interface com.sun.jdi.ObjectReference
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
 
Method Summary
 ObjectReference currentContendedMonitor()
          Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting.
 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 frames()
          Returns a List containing each StackFrame in the thread's current call stack.
 List 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 ownedMonitors()
          Returns a List containing an ObjectReference 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.
 
Methods inherited from interface com.sun.jdi.ObjectReference
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, setValue, uniqueID, waitingThreads
 
Methods inherited from interface com.sun.jdi.Value
type
 
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
 

Field Detail

THREAD_STATUS_UNKNOWN

public static final int THREAD_STATUS_UNKNOWN
Thread status is unknown

See Also:
Constant Field Values

THREAD_STATUS_ZOMBIE

public static final int THREAD_STATUS_ZOMBIE
Thread has completed execution

See Also:
Constant Field Values

THREAD_STATUS_RUNNING

public static final int THREAD_STATUS_RUNNING
Thread is runnable

See Also:
Constant Field Values

THREAD_STATUS_SLEEPING

public static final int THREAD_STATUS_SLEEPING
Thread is sleeping - Thread.sleep() or JVM_Sleep() was called

See Also:
Constant Field Values

THREAD_STATUS_MONITOR

public static final int THREAD_STATUS_MONITOR
Thread is waiting on a java monitor

See Also:
Constant Field Values

THREAD_STATUS_WAIT

public static final int THREAD_STATUS_WAIT
Thread is waiting - Thread.wait() or JVM_MonitorWait() was called

See Also:
Constant Field Values

THREAD_STATUS_NOT_STARTED

public static final int THREAD_STATUS_NOT_STARTED
Thread has not yet been started

See Also:
Constant Field Values
Method Detail

name

public String name()
Returns the name of this thread.

Returns:
the string containing the thread name.

suspend

public void suspend()
Suspends this thread. The thread can be resumed through 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().


resume

public 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().


suspendCount

public int suspendCount()
Returns the number of pending suspends for this thread. See suspend() for an explanation of counted suspends.

Returns:
pending suspend count as an integer

stop

public void stop(ObjectReference throwable)
          throws InvalidTypeException
Stops this thread with an asynchronous exception. A debugger thread in the target VM will stop this thread with the given Throwable object.

Parameters:
throwable - the asynchronous exception to throw.
Throws:
InvalidTypeException - if throwable is not an instance of java.lang.Throwable in the target VM.
See Also:
Thread.stop(Throwable)

interrupt

public void interrupt()
Interrupts this thread unless the thread has been suspended by the debugger.

See Also:
Thread.interrupt()

status

public 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 (or THREAD_STATUS_UNKNOWN if this information is not available. isSuspended() can be used to determine if the thread has been suspended.

Returns:
one of THREAD_STATUS_UNKNOWN, THREAD_STATUS_ZOMBIE, THREAD_STATUS_RUNNING, THREAD_STATUS_SLEEPING, THREAD_STATUS_MONITOR, THREAD_STATUS_WAIT, THREAD_STATUS_NOT_STARTED,

isSuspended

public boolean isSuspended()
Determines whether the thread has been suspended by the the debugger.

Returns:
true if the thread is currently suspended; false otherwise.

isAtBreakpoint

public 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

public ThreadGroupReference threadGroup()
Returns this thread's thread group.

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

frameCount

public int frameCount()
               throws IncompatibleThreadStateException
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 - if the thread is not suspended in the target VM

frames

public List frames()
            throws IncompatibleThreadStateException
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 - if the thread is not suspended in the target VM

frame

public StackFrame frame(int index)
                 throws IncompatibleThreadStateException
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 - if the thread is not suspended in the target VM
IndexOutOfBoundsException - if the index is greater than or equal to frameCount() or is negative.

frames

public List frames(int start,
                   int length)
            throws IncompatibleThreadStateException
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 - if the thread is not suspended in the target VM
IndexOutOfBoundsException - 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()

ownedMonitors

public List ownedMonitors()
                   throws IncompatibleThreadStateException
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(long).

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 - if the target virtual machine does not support this operation.
IncompatibleThreadStateException - if the thread is not suspended in the target VM

currentContendedMonitor

public ObjectReference currentContendedMonitor()
                                        throws IncompatibleThreadStateException
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, 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.

Returns:
the ObjectReference corresponding 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

popFrames

public void popFrames(StackFrame frame)
               throws IncompatibleThreadStateException
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.

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 - 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.
Since:
1.4

Java Debug Interface