/*
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package com.sun.jdi;
import java.util.List;
/**
* A thread object from the target VM.
* A ThreadReference is an {@link ObjectReference} with additional
* access to thread-specific information from the target VM.
*
* @author Robert Field
* @author Gordon Hirsch
* @author James McIlree
* @since 1.3
*/
public interface ThreadReference extends ObjectReference {
/** Thread status is unknown */
public final int THREAD_STATUS_UNKNOWN =-1;
/** Thread has completed execution */
public final int THREAD_STATUS_ZOMBIE = 0;
/** Thread is runnable */
public final int THREAD_STATUS_RUNNING = 1;
/** Thread is sleeping - Thread.sleep() or JVM_Sleep() was called */
public final int THREAD_STATUS_SLEEPING = 2;
/** Thread is waiting on a java monitor */
public final int THREAD_STATUS_MONITOR = 3;
/** Thread is waiting - Object.wait() or JVM_MonitorWait() was called */
public final int THREAD_STATUS_WAIT = 4;
/** Thread has not yet been started */
public final int THREAD_STATUS_NOT_STARTED = 5;
/**
* Returns the name of this thread.
*
* @return the string containing the thread name.
*/
String name();
/**
* Suspends this thread. The thread can be resumed through
* {@link #resume} or resumed with other threads through
* {@link VirtualMachine#resume}.
* <p>
* Unlike {@link 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 {@link #resume} or {@link ThreadReference#resume})
* the same number of times it has been suspended.
* <p>
* Suspending single threads with this method has the same dangers
* as {@link 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).
* <p>
* 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 {@link java.lang.Thread#resume}.
* @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
*/
void suspend();
/**
* Resumes this thread. If this thread was not previously suspended
* through {@link #suspend} or through {@link 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 {@link com.sun.jdi.event.EventSet#resume}.
* @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
*/
void resume();
/**
* Returns the number of pending suspends for this thread. See
* {@link #suspend} for an explanation of counted suspends.
* @return pending suspend count as an integer
*/
int suspendCount();
/**
* Stops this thread with an asynchronous exception.
* A debugger thread in the target VM will stop this thread
* with the given {@link java.lang.Throwable} object.
*
* @param throwable the asynchronous exception to throw.
* @throws InvalidTypeException if <code>throwable</code> is not
* an instance of java.lang.Throwable in the target VM.
* @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
* @see java.lang.Thread#stop(Throwable)
*/
void stop(ObjectReference throwable) throws InvalidTypeException;
/**
* Interrupts this thread unless the thread has been suspended by the
* debugger.
* @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
*
* @see java.lang.Thread#interrupt()
*/
void interrupt();
/**
* 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
* {@link #THREAD_STATUS_UNKNOWN} if this information is not available.
* {@link #isSuspended} can be used to determine if the thread has been
* suspended.
*
* @return one of
* {@link #THREAD_STATUS_UNKNOWN},
* {@link #THREAD_STATUS_ZOMBIE},
* {@link #THREAD_STATUS_RUNNING},
* {@link #THREAD_STATUS_SLEEPING},
* {@link #THREAD_STATUS_MONITOR},
* {@link #THREAD_STATUS_WAIT},
* {@link #THREAD_STATUS_NOT_STARTED},
*/
int status();
/**
* Determines whether the thread has been suspended by the
* the debugger.
*
* @return <code>true</code> if the thread is currently suspended;
* <code>false</code> otherwise.
*/
boolean isSuspended();
/**
* Determines whether the thread is suspended at a breakpoint.
*
* @return <code>true</code> if the thread is currently stopped at
* a breakpoint; <code>false</code> otherwise.
*/
boolean isAtBreakpoint();
/**
* Returns this thread's thread group.
* @return a {@link ThreadGroupReference} that mirrors this thread's
* thread group in the target VM.
*/
ThreadGroupReference threadGroup();
/**
* 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.
*
* @return an integer frame count
* @throws IncompatibleThreadStateException if the thread is
* not suspended in the target VM
*/
int frameCount() throws IncompatibleThreadStateException;
/**
* Returns a List containing each {@link 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.
*
* @return a List of {@link StackFrame} with the current frame first
* followed by each caller's frame.
* @throws IncompatibleThreadStateException if the thread is
* not suspended in the target VM
*/
List<StackFrame> frames() throws IncompatibleThreadStateException;
/**
* Returns the {@link 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.
*
* @param index the desired frame
* @return the requested {@link StackFrame}
* @throws IncompatibleThreadStateException if the thread is
* not suspended in the target VM
* @throws java.lang.IndexOutOfBoundsException if the index is greater than
* or equal to {@link #frameCount} or is negative.
*/
StackFrame frame(int index) throws IncompatibleThreadStateException;
/**
* Returns a List containing a range of {@link 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.
*
* @param start the index of the first frame to retrieve.
* Index 0 represents the current frame.
* @param length the number of frames to retrieve
* @return a List of {@link StackFrame} with the current frame first
* followed by each caller's frame.
* @throws IncompatibleThreadStateException if the thread is
* not suspended in the target VM
* @throws 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:
* <pre> start < 0
* start >= {@link #frameCount}
* length < 0
* (start+length) > {@link #frameCount}</pre>
*/
List<StackFrame> frames(int start, int length)
throws IncompatibleThreadStateException;
/**
* Returns a List containing an {@link 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 {@link Object#wait}.
* <p>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canGetOwnedMonitorInfo()}
* to determine if the operation is supported.
*
* @return a List of {@link ObjectReference} objects. The list
* has zero length if no monitors are owned by this thread.
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation.
* @throws IncompatibleThreadStateException if the thread is
* not suspended in the target VM
*/
List<ObjectReference> ownedMonitors()
throws IncompatibleThreadStateException;
/**
* Returns a List containing a {@link 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 {@link Object#wait}.
* <p>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canGetMonitorFrameInfo()}
* to determine if the operation is supported.
*
* @return a List of {@link MonitorInfo} objects. The list
* has zero length if no monitors are owned by this thread.
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation.
* @throws IncompatibleThreadStateException if the thread is
* not suspended in the target VM
*
* @since 1.6
*/
List<MonitorInfo> ownedMonitorsAndFrames()
throws IncompatibleThreadStateException;
/**
* Returns an {@link 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
* {@link Object#wait}. The {@link #status} method can be used
* to differentiate between the first two cases and the third.
* <p>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canGetCurrentContendedMonitor()}
* to determine if the operation is supported.
*
* @return the {@link ObjectReference} corresponding to the
* contended monitor, or null if it is not waiting for a monitor.
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation.
* @throws IncompatibleThreadStateException if the thread is
* not suspended in the target VM
*/
ObjectReference currentContendedMonitor() throws IncompatibleThreadStateException;
/**
* Pop stack frames.
* <P>
* All frames up to and including the <CODE>frame</CODE> are
* popped off the stack.
* The frame previous to the parameter <CODE>frame</CODE>
* will become the current frame.
* <P>
* After this operation, this thread will be
* suspended at the invoke instruction of the target method
* that created <CODE>frame</CODE>.
* The <CODE>frame</CODE>'s method can be reentered with a step into
* the instruction.
* <P>
* The operand stack is restored, however, any changes
* to the arguments that occurred in the called method, remain.
* For example, if the method <CODE>foo</CODE>:
* <PRE>
* void foo(int x) {
* System.out.println("Foo: " + x);
* x = 4;
* System.out.println("pop here");
* }
* </PRE>
* was called with <CODE>foo(7)</CODE> and <CODE>foo</CODE>
* is popped at the second <CODE>println</CODE> and resumed,
* it will print: <CODE>Foo: 4</CODE>.
* <P>
* 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.
* <P>
* Finally blocks are not executed.
* <P>
* 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.
* <P>
* The specified thread must be suspended.
* <P>
* All <code>StackFrame</code> objects for this thread are
* invalidated.
* <P>
* No events are generated by this method.
* <P>
* None of the frames through and including the frame for the caller
* of <i>frame</i> may be native.
* <P>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()}
* to determine if the operation is supported.
*
* @param frame Stack frame to pop. <CODE>frame</CODE> is on this
* thread's call stack.
*
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation - see
* {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()}.
*
* @throws IncompatibleThreadStateException if this
* thread is not suspended.
*
* @throws java.lang.IllegalArgumentException if <CODE>frame</CODE>
* is not on this thread's call stack.
*
* @throws NativeMethodException if one of the frames that would be
* popped is that of a native method or if the frame previous to
* <i>frame</i> is native.
*
* @throws InvalidStackFrameException if <CODE>frame</CODE> 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.
* @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
*
* @since 1.4 */
void popFrames(StackFrame frame) throws IncompatibleThreadStateException;
/**
* Force a method to return before it reaches a return
* statement.
* <p>
* 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.
* <p>
* 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.
* <p>
* No further instructions are executed in the called
* method. Specifically, finally blocks are not executed. Note:
* this can cause inconsistent states in the application.
* <p>
* 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.
* <p>
* Events, such as MethodExit, are generated as they would be in
* a normal return.
* <p>
* 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.
* <p>
* The <code>value</code> argument is the value that the
* method is to return.
* If the return type of the method is void, then value must
* be a {@link VoidValue 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.
* <p>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canForceEarlyReturn()}
* to determine if the operation is supported.
*
* @param value the value the method is to return.
*
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation - see
* {@link VirtualMachine#canGetInstanceInfo() canForceEarlyReturn()}
*
* @throws IncompatibleThreadStateException if this
* thread is not suspended.
*
* @throws NativeMethodException if the frame to be returned from
* is that of a native method.
*
* @throws InvalidStackFrameException if there are no frames.
*
* @throws InvalidTypeException if the value's type does not match
* the method's return type.
*
* @throws ClassNotLoadedException if the method's return type has not yet
* been loaded through the appropriate class loader.
*
* @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
*
* @since 1.6
*/
void forceEarlyReturn(Value value) throws InvalidTypeException,
ClassNotLoadedException,
IncompatibleThreadStateException;
}