Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD