| /* |
| * 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; |
| |
| } |
