2362N/A * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A thread object from the target VM. 0N/A * A ThreadReference is an {@link ObjectReference} with additional 0N/A * access to thread-specific information from the target VM. 0N/A * @author Robert Field 0N/A * @author Gordon Hirsch 0N/A * @author James McIlree 0N/A /** Thread status is unknown */ 0N/A /** Thread has completed execution */ 0N/A /** Thread is runnable */ 0N/A /** Thread is sleeping - Thread.sleep() or JVM_Sleep() was called */ 0N/A /** Thread is waiting on a java monitor */ 0N/A /** Thread is waiting - Object.wait() or JVM_MonitorWait() was called */ 0N/A /** Thread has not yet been started */ 0N/A * Returns the name of this thread. 0N/A * @return the string containing the thread name. 0N/A * Suspends this thread. The thread can be resumed through 0N/A * {@link #resume} or resumed with other threads through 0N/A * {@link VirtualMachine#resume}. 0N/A * Unlike {@link java.lang.Thread#suspend}, 0N/A * suspends of both the virtual machine and individual threads are 0N/A * counted. Before a thread will run again, it must be resumed 0N/A * (through {@link #resume} or {@link ThreadReference#resume}) 0N/A * the same number of times it has been suspended. 0N/A * Suspending single threads with this method has the same dangers 0N/A * as {@link java.lang.Thread#suspend()}. If the suspended thread 0N/A * holds a monitor needed by another running thread, deadlock is 0N/A * possible in the target VM (at least until the suspended thread 0N/A * is resumed again). 0N/A * The suspended thread is guaranteed to remain suspended until 0N/A * resumed through one of the JDI resume methods mentioned above; 0N/A * the application in the target VM cannot resume the suspended thread 0N/A * through {@link java.lang.Thread#resume}. 0N/A * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 0N/A * Resumes this thread. If this thread was not previously suspended 0N/A * through {@link #suspend} or through {@link VirtualMachine#suspend}, 0N/A * or because of a SUSPEND_ALL or SUSPEND_EVENT_THREAD event, then 0N/A * invoking this method has no effect. Otherwise, the count of pending 0N/A * suspends on this thread is decremented. If it is decremented to 0, 0N/A * the thread will continue to execute. 0N/A * Note: the normal way to resume from an event related suspension is 0N/A * via {@link com.sun.jdi.event.EventSet#resume}. 0N/A * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 0N/A * Returns the number of pending suspends for this thread. See 0N/A * {@link #suspend} for an explanation of counted suspends. 0N/A * @return pending suspend count as an integer 0N/A * Stops this thread with an asynchronous exception. 0N/A * A debugger thread in the target VM will stop this thread 0N/A * with the given {@link java.lang.Throwable} object. 0N/A * @param throwable the asynchronous exception to throw. 0N/A * @throws InvalidTypeException if <code>throwable</code> is not 0N/A * an instance of java.lang.Throwable in the target VM. 0N/A * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 0N/A * @see java.lang.Thread#stop(Throwable) 0N/A * Interrupts this thread unless the thread has been suspended by the 0N/A * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 0N/A * @see java.lang.Thread#interrupt() 0N/A * Returns the thread's status. If the thread is not suspended the 0N/A * thread's current status is returned. If the thread is suspended, the 0N/A * thread's status before the suspension is returned (or 0N/A * {@link #THREAD_STATUS_UNKNOWN} if this information is not available. 0N/A * {@link #isSuspended} can be used to determine if the thread has been 0N/A * {@link #THREAD_STATUS_UNKNOWN}, 0N/A * {@link #THREAD_STATUS_ZOMBIE}, 0N/A * {@link #THREAD_STATUS_RUNNING}, 0N/A * {@link #THREAD_STATUS_SLEEPING}, 0N/A * {@link #THREAD_STATUS_MONITOR}, 0N/A * {@link #THREAD_STATUS_WAIT}, 0N/A * {@link #THREAD_STATUS_NOT_STARTED}, 0N/A * Determines whether the thread has been suspended by the 0N/A * @return <code>true</code> if the thread is currently suspended; 0N/A * <code>false</code> otherwise. 0N/A * Determines whether the thread is suspended at a breakpoint. 0N/A * @return <code>true</code> if the thread is currently stopped at 0N/A * a breakpoint; <code>false</code> otherwise. 0N/A * Returns this thread's thread group. 0N/A * @return a {@link ThreadGroupReference} that mirrors this thread's 0N/A * thread group in the target VM. 0N/A * Returns the number of stack frames in the thread's current 0N/A * The thread must be suspended (normally through an interruption 0N/A * to the VM) to get this information, and 0N/A * it is only valid until the thread is resumed again. 0N/A * @return an integer frame count 0N/A * @throws IncompatibleThreadStateException if the thread is 0N/A * not suspended in the target VM 0N/A * Returns a List containing each {@link StackFrame} in the 0N/A * thread's current call stack. 0N/A * The thread must be suspended (normally through an interruption 0N/A * to the VM) to get this information, and 0N/A * it is only valid until the thread is resumed again. 0N/A * @return a List of {@link StackFrame} with the current frame first 0N/A * followed by each caller's frame. 0N/A * @throws IncompatibleThreadStateException if the thread is 0N/A * not suspended in the target VM 0N/A * Returns the {@link StackFrame} at the given index in the 0N/A * thread's current call stack. Index 0 retrieves the current 0N/A * frame; higher indices retrieve caller frames. 0N/A * The thread must be suspended (normally through an interruption 0N/A * to the VM) to get this information, and 0N/A * it is only valid until the thread is resumed again. 0N/A * @param index the desired frame 0N/A * @return the requested {@link StackFrame} 0N/A * @throws IncompatibleThreadStateException if the thread is 0N/A * not suspended in the target VM 0N/A * @throws java.lang.IndexOutOfBoundsException if the index is greater than 0N/A * or equal to {@link #frameCount} or is negative. 0N/A * Returns a List containing a range of {@link StackFrame} mirrors 0N/A * from the thread's current call stack. 0N/A * The thread must be suspended (normally through an interruption 0N/A * to the VM) to get this information, and 0N/A * it is only valid until the thread is resumed again. 0N/A * @param start the index of the first frame to retrieve. 0N/A * Index 0 represents the current frame. 0N/A * @param length the number of frames to retrieve 0N/A * @return a List of {@link StackFrame} with the current frame first 0N/A * followed by each caller's frame. 0N/A * @throws IncompatibleThreadStateException if the thread is 0N/A * not suspended in the target VM 0N/A * @throws IndexOutOfBoundsException if the specified range is not 0N/A * within the range of stack frame indicies. 0N/A * That is, the exception is thrown if any of the following are true: 0N/A * <pre> start < 0 0N/A * start >= {@link #frameCount} 0N/A * (start+length) > {@link #frameCount}</pre> 0N/A * Returns a List containing an {@link ObjectReference} for 0N/A * each monitor owned by the thread. 0N/A * A monitor is owned by a thread if it has been entered 0N/A * (via the synchronized statement or entry into a synchronized 0N/A * method) and has not been relinquished through {@link Object#wait}. 0N/A * Not all target virtual machines support this operation. 0N/A * Use {@link VirtualMachine#canGetOwnedMonitorInfo()} 0N/A * to determine if the operation is supported. 0N/A * @return a List of {@link ObjectReference} objects. The list 0N/A * has zero length if no monitors are owned by this thread. 0N/A * @throws java.lang.UnsupportedOperationException if 0N/A * the target virtual machine does not support this 0N/A * @throws IncompatibleThreadStateException if the thread is 0N/A * not suspended in the target VM 0N/A * Returns a List containing a {@link MonitorInfo} object for 0N/A * each monitor owned by the thread. 0N/A * A monitor is owned by a thread if it has been entered 0N/A * (via the synchronized statement or entry into a synchronized 0N/A * method) and has not been relinquished through {@link Object#wait}. 0N/A * Not all target virtual machines support this operation. 0N/A * Use {@link VirtualMachine#canGetMonitorFrameInfo()} 0N/A * to determine if the operation is supported. 0N/A * @return a List of {@link MonitorInfo} objects. The list 0N/A * has zero length if no monitors are owned by this thread. 0N/A * @throws java.lang.UnsupportedOperationException if 0N/A * the target virtual machine does not support this 0N/A * @throws IncompatibleThreadStateException if the thread is 0N/A * not suspended in the target VM 0N/A * Returns an {@link ObjectReference} for the monitor, if any, 0N/A * for which this thread is currently waiting. 0N/A * The thread can be waiting for a monitor through entry into a 0N/A * synchronized method, the synchronized statement, or 0N/A * {@link Object#wait}. The {@link #status} method can be used 0N/A * to differentiate between the first two cases and the third. 0N/A * Not all target virtual machines support this operation. 0N/A * Use {@link VirtualMachine#canGetCurrentContendedMonitor()} 0N/A * to determine if the operation is supported. 0N/A * @return the {@link ObjectReference} corresponding to the 0N/A * contended monitor, or null if it is not waiting for a monitor. 0N/A * @throws java.lang.UnsupportedOperationException if 0N/A * the target virtual machine does not support this 0N/A * @throws IncompatibleThreadStateException if the thread is 0N/A * not suspended in the target VM 0N/A * All frames up to and including the <CODE>frame</CODE> are 0N/A * popped off the stack. 0N/A * The frame previous to the parameter <CODE>frame</CODE> 0N/A * will become the current frame. 0N/A * After this operation, this thread will be 0N/A * suspended at the invoke instruction of the target method 0N/A * that created <CODE>frame</CODE>. 0N/A * The <CODE>frame</CODE>'s method can be reentered with a step into 0N/A * The operand stack is restored, however, any changes 0N/A * to the arguments that occurred in the called method, remain. 0N/A * For example, if the method <CODE>foo</CODE>: 0N/A * System.out.println("Foo: " + x); 0N/A * System.out.println("pop here"); 0N/A * was called with <CODE>foo(7)</CODE> and <CODE>foo</CODE> 0N/A * is popped at the second <CODE>println</CODE> and resumed, 0N/A * it will print: <CODE>Foo: 4</CODE>. 0N/A * Locks acquired by a popped frame are released when it 0N/A * is popped. This applies to synchronized methods that 0N/A * are popped, and to any synchronized blocks within them. 0N/A * Finally blocks are not executed. 0N/A * No aspect of state, other than this thread's execution point and 0N/A * locks, is affected by this call. Specifically, the values of 0N/A * fields are unchanged, as are external resources such as 0N/A * I/O streams. Additionally, the target program might be 0N/A * placed in a state that is impossible with normal program flow; 0N/A * for example, order of lock acquisition might be perturbed. 0N/A * Thus the target program may 0N/A * proceed differently than the user would expect. 0N/A * The specified thread must be suspended. 0N/A * All <code>StackFrame</code> objects for this thread are 0N/A * No events are generated by this method. 0N/A * None of the frames through and including the frame for the caller 0N/A * of <i>frame</i> may be native. 0N/A * Not all target virtual machines support this operation. 0N/A * Use {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()} 0N/A * to determine if the operation is supported. 0N/A * @param frame Stack frame to pop. <CODE>frame</CODE> is on this 0N/A * thread's call stack. 0N/A * @throws java.lang.UnsupportedOperationException if 0N/A * the target virtual machine does not support this 0N/A * {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()}. 0N/A * @throws IncompatibleThreadStateException if this 0N/A * thread is not suspended. 0N/A * @throws java.lang.IllegalArgumentException if <CODE>frame</CODE> 0N/A * is not on this thread's call stack. 0N/A * @throws NativeMethodException if one of the frames that would be 0N/A * popped is that of a native method or if the frame previous to 0N/A * <i>frame</i> is native. 0N/A * @throws InvalidStackFrameException if <CODE>frame</CODE> has become 0N/A * invalid. Once this thread is resumed, the stack frame is 0N/A * no longer valid. This exception is also thrown if there are no 0N/A * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 0N/A * Force a method to return before it reaches a return 0N/A * The method which will return early is referred to as the 0N/A * called method. The called method is the current method (as 0N/A * defined by the Frames section in the Java Virtual Machine 0N/A * Specification) for the specified thread at the time this 0N/A * The thread must be suspended. 0N/A * The return occurs when execution of Java programming 0N/A * language code is resumed on this thread. Between the call to 0N/A * this method and resumption of thread execution, the 0N/A * state of the stack is undefined. 0N/A * No further instructions are executed in the called 0N/A * method. Specifically, finally blocks are not executed. Note: 0N/A * this can cause inconsistent states in the application. 0N/A * A lock acquired by calling the called method (if it is a 0N/A * synchronized method) and locks acquired by entering 0N/A * synchronized blocks within the called method are 0N/A * released. Note: this does not apply to native locks or 0N/A * java.util.concurrent.locks locks. 0N/A * Events, such as MethodExit, are generated as they would be in 0N/A * The called method must be a non-native Java programming 0N/A * language method. Forcing return on a thread with only one 0N/A * frame on the stack causes the thread to exit when resumed. 0N/A * The <code>value</code> argument is the value that the 0N/A * method is to return. 0N/A * If the return type of the method is void, then value must 0N/A * be a {@link VoidValue VoidValue}. 0N/A * Object values must be assignment compatible with the method return type 0N/A * (This implies that the method return type must be loaded through the 0N/A * enclosing class's class loader). Primitive values must be 0N/A * either assignment compatible with the method return type or must be 0N/A * convertible to the variable type without loss of information. 0N/A * See JLS section 5.2 for more information on assignment 0N/A * Not all target virtual machines support this operation. 0N/A * Use {@link VirtualMachine#canForceEarlyReturn()} 0N/A * to determine if the operation is supported. 0N/A * @param value the value the method is to return. 0N/A * @throws java.lang.UnsupportedOperationException if 0N/A * the target virtual machine does not support this 0N/A * {@link VirtualMachine#canGetInstanceInfo() canForceEarlyReturn()} 0N/A * @throws IncompatibleThreadStateException if this 0N/A * thread is not suspended. 0N/A * @throws NativeMethodException if the frame to be returned from 0N/A * is that of a native method. 0N/A * @throws InvalidStackFrameException if there are no frames. 0N/A * @throws InvalidTypeException if the value's type does not match 0N/A * the method's return type. 0N/A * @throws ClassNotLoadedException if the method's return type has not yet 0N/A * been loaded through the appropriate class loader. 0N/A * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.