Spec-Zone .ru спецификации, руководства, описания, API

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

THREAD_STATUS_ZOMBIE

public static final int THREAD_STATUS_ZOMBIE

Thread has completed execution

THREAD_STATUS_RUNNING

public static final int THREAD_STATUS_RUNNING

Thread is runnable

THREAD_STATUS_SLEEPING

public static final int THREAD_STATUS_SLEEPING

Thread is sleeping - Thread.sleep() or JVM_Sleep() was called

THREAD_STATUS_MONITOR

public static final int THREAD_STATUS_MONITOR

Thread is waiting on a java monitor

THREAD_STATUS_WAIT

public static final int THREAD_STATUS_WAIT

Thread is waiting - Thread.wait() or JVM_MonitorWait() was called

THREAD_STATUS_NOT_STARTED

public static final int THREAD_STATUS_NOT_STARTED

Thread has not yet been started

Method Detail

name

public String name()

Returns the name of this thread.

Returns:

the string containing the thread name.

Throws:

ObjectCollectedException - if this object has been garbage collected.

suspend

public void suspend()

Suspends this thread. The thread can be resumed through resume() or resumed with other threads through VirtualMachine.resume().

Unlike java.lang.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 java.lang.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 java.lang.Thread#resume.

Throws:

ObjectCollectedException - if this object has been garbage collected.

resume

public void resume()

Resumes this thread. If this thread was not previously suspended through suspend() or through VirtualMachine.suspend(), 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.

Throws:

ObjectCollectedException - if this object has been garbage collected.

suspendCount

public int suspendCount()

Resumes the number of pending suspends for this thread. See suspend() for an explanation of counted suspends.

Returns:

the integer pending suspend count

Throws:

ObjectCollectedException - if this object has been garbage collected.

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.

ObjectCollectedException - if this object or the asynchronous exception has been garbage collected.

See Also:

java.lang.Thread#stop(Throwable)

interrupt

public void interrupt()

Interrupts this thread.

Throws:

ObjectCollectedException - if this object has been garbage collected.

See Also:

java.lang.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,

Throws:

ObjectCollectedException - if this object has been garbage collected.

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.

Throws:

ObjectCollectedException - if this object has been garbage collected.

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.

Throws:

ObjectCollectedException - if this object has been garbage collected.

threadGroup

public ThreadGroupReference threadGroup()

Returns this thread's thread group.

Returns:

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

Throws:

ObjectCollectedException - if this object has been garbage collected.

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

ObjectCollectedException - if this object has been garbage collected.

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

ObjectCollectedException - if this object has been garbage collected.

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

java.lang.IndexOutOfBoundsException - if the index is greater than or equal to frameCount() or is negative.

ObjectCollectedException - if this object has been garbage collected.

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

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 from 0 to frameCount() - 1.

ObjectCollectedException - if this object has been garbage collected.

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 VMs support this operation. See 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:

java.lang.UnsupportedOperationException - if the target target VM does not support this operation.

IncompatibleThreadStateException - if the thread is not suspended in the target VM

ObjectCollectedException - if this object has been garbage collected.

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 VMs support this operation. See 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:

java.lang.UnsupportedOperationException - if the target target VM does not support this operation.

IncompatibleThreadStateException - if the thread is not suspended in the target VM

ObjectCollectedException - if this object has been garbage collected.