474 lines
20 KiB
Java
474 lines
20 KiB
Java
/*
|
|
* 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
|
|
*/
|
|
@jdk.Exported
|
|
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;
|
|
|
|
}
|