1 /*
  2  * Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
  3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  4  *
  5  * This code is free software; you can redistribute it and/or modify it
  6  * under the terms of the GNU General Public License version 2 only, as
  7  * published by the Free Software Foundation.  Oracle designates this
  8  * particular file as subject to the "Classpath" exception as provided
  9  * by Oracle in the LICENSE file that accompanied this code.
 10  *
 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package com.sun.jdi;
 27 
 28 import java.util.List;
 29 
 30 import com.sun.jdi.event.EventSet;
 31 
 32 /**
 33  * A thread object from the target VM.
 34  * A ThreadReference is an {@link ObjectReference} with additional
 35  * access to thread-specific information from the target VM.
 36  *
 37  * @author Robert Field
 38  * @author Gordon Hirsch
 39  * @author James McIlree
 40  * @since  1.3
 41  */
 42 public interface ThreadReference extends ObjectReference {
 43 
 44     /** Thread status is unknown */
 45     public final int THREAD_STATUS_UNKNOWN  =-1;
 46     /** Thread has completed execution */
 47     public final int THREAD_STATUS_ZOMBIE = 0;
 48     /** Thread is runnable */
 49     public final int THREAD_STATUS_RUNNING = 1;
 50     /** Thread is sleeping - Thread.sleep() or JVM_Sleep() was called */
 51     public final int THREAD_STATUS_SLEEPING = 2;
 52     /** Thread is waiting on a java monitor */
 53     public final int THREAD_STATUS_MONITOR = 3;
 54     /** Thread is waiting - Object.wait() or JVM_MonitorWait() was called */
 55     public final int THREAD_STATUS_WAIT = 4;
 56     /** Thread has not yet been started */
 57     public final int THREAD_STATUS_NOT_STARTED = 5;
 58 
 59     /**
 60      * Returns the name of this thread.
 61      *
 62      * @return the string containing the thread name.
 63      */
 64     String name();
 65 
 66     /**
 67      * Suspends this thread. The thread can be resumed through
 68      * {@link #resume} or resumed with other threads through
 69      * {@link VirtualMachine#resume}.
 70      * <p>
 71      * Unlike {@link java.lang.Thread#suspend},
 72      * suspends of both the virtual machine and individual threads are
 73      * counted. Before a thread will run again, it must be resumed
 74      * (through {@link #resume} or {@link ThreadReference#resume})
 75      * the same number of times it has been suspended.
 76      * <p>
 77      * Suspending single threads with this method has the same dangers
 78      * as {@link java.lang.Thread#suspend()}. If the suspended thread
 79      * holds a monitor needed by another running thread, deadlock is
 80      * possible in the target VM (at least until the suspended thread
 81      * is resumed again).
 82      * <p>
 83      * The suspended thread is guaranteed to remain suspended until
 84      * resumed through one of the JDI resume methods mentioned above;
 85      * the application in the target VM cannot resume the suspended thread
 86      * through {@link java.lang.Thread#resume}.
 87      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
 88      */
 89     @SuppressWarnings("javadoc")
 90     void suspend();
 91 
 92     /**
 93      * Resumes this thread. If this thread was not previously suspended
 94      * through {@link #suspend} or through {@link VirtualMachine#suspend},
 95      * or because of a SUSPEND_ALL or SUSPEND_EVENT_THREAD event, then
 96      * invoking this method has no effect. Otherwise, the count of pending
 97      * suspends on this thread is decremented. If it is decremented to 0,
 98      * the thread will continue to execute.
 99      * Note: the normal way to resume from an event related suspension is
100      * via {@link EventSet#resume}.
101      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
102      */
103     void resume();
104 
105     /**
106      * Returns the number of pending suspends for this thread. See
107      * {@link #suspend} for an explanation of counted suspends.
108      * @return pending suspend count as an integer
109      */
110     int suspendCount();
111 
112     /**
113      * Stops this thread with an asynchronous exception.
114      * A debugger thread in the target VM will stop this thread
115      * with the given {@link java.lang.Throwable} object.
116      *
117      * @param throwable the asynchronous exception to throw.
118      * @throws InvalidTypeException if <code>throwable</code> is not
119      * an instance of java.lang.Throwable in the target VM.
120      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
121      */
122     @SuppressWarnings("javadoc")
123     void stop(ObjectReference throwable) throws InvalidTypeException;
124 
125     /**
126      * Interrupts this thread unless the thread has been suspended by the
127      * debugger.
128      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
129      *
130      * @see java.lang.Thread#interrupt()
131      */
132     void interrupt();
133 
134     /**
135      * Returns the thread's status. If the thread is not suspended the
136      * thread's current status is returned. If the thread is suspended, the
137      * thread's status before the suspension is returned (or
138      * {@link #THREAD_STATUS_UNKNOWN} if this information is not available.
139      * {@link #isSuspended} can be used to determine if the thread has been
140      * suspended.
141      *
142      * @return one of
143      * {@link #THREAD_STATUS_UNKNOWN},
144      * {@link #THREAD_STATUS_ZOMBIE},
145      * {@link #THREAD_STATUS_RUNNING},
146      * {@link #THREAD_STATUS_SLEEPING},
147      * {@link #THREAD_STATUS_MONITOR},
148      * {@link #THREAD_STATUS_WAIT},
149      * {@link #THREAD_STATUS_NOT_STARTED},
150      */
151     int status();
152 
153     /**
154      * Determines whether the thread has been suspended by the
155      * the debugger.
156      *
157      * @return <code>true</code> if the thread is currently suspended;
158      * <code>false</code> otherwise.
159      */
160     boolean isSuspended();
161 
162     /**
163      * Determines whether the thread is suspended at a breakpoint.
164      *
165      * @return <code>true</code> if the thread is currently stopped at
166      * a breakpoint; <code>false</code> otherwise.
167      */
168     boolean isAtBreakpoint();
169 
170     /**
171      * Returns this thread's thread group.
172      * @return a {@link ThreadGroupReference} that mirrors this thread's
173      * thread group in the target VM.
174      */
175     ThreadGroupReference threadGroup();
176 
177     /**
178      * Returns the number of stack frames in the thread's current
179      * call stack.
180      * The thread must be suspended (normally through an interruption
181      * to the VM) to get this information, and
182      * it is only valid until the thread is resumed again.
183      *
184      * @return an integer frame count
185      * @throws IncompatibleThreadStateException if the thread is
186      * not suspended in the target VM
187      */
188     int frameCount() throws IncompatibleThreadStateException;
189 
190     /**
191      * Returns a List containing each {@link StackFrame} in the
192      * thread's current call stack.
193      * The thread must be suspended (normally through an interruption
194      * to the VM) to get this information, and
195      * it is only valid until the thread is resumed again.
196      *
197      * @return a List of {@link StackFrame} with the current frame first
198      * followed by each caller's frame.
199      * @throws IncompatibleThreadStateException if the thread is
200      * not suspended in the target VM
201      */
202     List<StackFrame> frames() throws IncompatibleThreadStateException;
203 
204     /**
205      * Returns the {@link StackFrame} at the given index in the
206      * thread's current call stack. Index 0 retrieves the current
207      * frame; higher indices retrieve caller frames.
208      * The thread must be suspended (normally through an interruption
209      * to the VM) to get this information, and
210      * it is only valid until the thread is resumed again.
211      *
212      * @param index the desired frame
213      * @return the requested {@link StackFrame}
214      * @throws IncompatibleThreadStateException if the thread is
215      * not suspended in the target VM
216      * @throws java.lang.IndexOutOfBoundsException if the index is greater than
217      * or equal to {@link #frameCount} or is negative.
218      */
219     StackFrame frame(int index) throws IncompatibleThreadStateException;
220 
221     /**
222      * Returns a List containing a range of {@link StackFrame} mirrors
223      * from the thread's current call stack.
224      * The thread must be suspended (normally through an interruption
225      * to the VM) to get this information, and
226      * it is only valid until the thread is resumed again.
227      *
228      * @param start the index of the first frame to retrieve.
229      *       Index 0 represents the current frame.
230      * @param length the number of frames to retrieve
231      * @return a List of {@link StackFrame} with the current frame first
232      * followed by each caller's frame.
233      * @throws IncompatibleThreadStateException if the thread is
234      * not suspended in the target VM
235      * @throws IndexOutOfBoundsException if the specified range is not
236      * within the range of stack frame indicies.
237      * That is, the exception is thrown if any of the following are true:
238      * <pre>    start &lt; 0
239      *    start &gt;= {@link #frameCount}
240      *    length &lt; 0
241      *    (start+length) &gt; {@link #frameCount}</pre>
242      */
243     List<StackFrame> frames(int start, int length)
244         throws IncompatibleThreadStateException;
245 
246     /**
247      * Returns a List containing an {@link ObjectReference} for
248      * each monitor owned by the thread.
249      * A monitor is owned by a thread if it has been entered
250      * (via the synchronized statement or entry into a synchronized
251      * method) and has not been relinquished through {@link Object#wait}.
252      * <p>
253      * Not all target virtual machines support this operation.
254      * Use {@link VirtualMachine#canGetOwnedMonitorInfo()}
255      * to determine if the operation is supported.
256      *
257      * @return a List of {@link ObjectReference} objects. The list
258      * has zero length if no monitors are owned by this thread.
259      * @throws java.lang.UnsupportedOperationException if
260      * the target virtual machine does not support this
261      * operation.
262      * @throws IncompatibleThreadStateException if the thread is
263      * not suspended in the target VM
264      */
265     List<ObjectReference> ownedMonitors()
266         throws IncompatibleThreadStateException;
267 
268     /**
269      * Returns a List containing a {@link MonitorInfo} object for
270      * each monitor owned by the thread.
271      * A monitor is owned by a thread if it has been entered
272      * (via the synchronized statement or entry into a synchronized
273      * method) and has not been relinquished through {@link Object#wait}.
274      * <p>
275      * Not all target virtual machines support this operation.
276      * Use {@link VirtualMachine#canGetMonitorFrameInfo()}
277      * to determine if the operation is supported.
278      *
279      * @return a List of {@link MonitorInfo} objects. The list
280      * has zero length if no monitors are owned by this thread.
281      * @throws java.lang.UnsupportedOperationException if
282      * the target virtual machine does not support this
283      * operation.
284      * @throws IncompatibleThreadStateException if the thread is
285      * not suspended in the target VM
286      *
287      * @since 1.6
288      */
289     List<MonitorInfo> ownedMonitorsAndFrames()
290         throws IncompatibleThreadStateException;
291 
292     /**
293      * Returns an {@link ObjectReference} for the monitor, if any,
294      * for which this thread is currently waiting.
295      * The thread can be waiting for a monitor through entry into a
296      * synchronized method, the synchronized statement, or
297      * {@link Object#wait}.  The {@link #status} method can be used
298      * to differentiate between the first two cases and the third.
299      * <p>
300      * Not all target virtual machines support this operation.
301      * Use {@link VirtualMachine#canGetCurrentContendedMonitor()}
302      * to determine if the operation is supported.
303      *
304      * @return the {@link ObjectReference} corresponding to the
305      * contended monitor, or null if it is not waiting for a monitor.
306      * @throws java.lang.UnsupportedOperationException if
307      * the target virtual machine does not support this
308      * operation.
309      * @throws IncompatibleThreadStateException if the thread is
310      * not suspended in the target VM
311      */
312     ObjectReference currentContendedMonitor() throws IncompatibleThreadStateException;
313 
314     /**
315      * Pop stack frames.
316      * <P>
317      * All frames up to and including the <CODE>frame</CODE> are
318      * popped off the stack.
319      * The frame previous to the parameter <CODE>frame</CODE>
320      * will become the current frame.
321      * <P>
322      * After this operation, this thread will be
323      * suspended at the invoke instruction of the target method
324      * that created <CODE>frame</CODE>.
325      * The <CODE>frame</CODE>'s method can be reentered with a step into
326      * the instruction.
327      * <P>
328      * The operand stack is restored, however, any changes
329      * to the arguments that occurred in the called method, remain.
330      * For example, if the method <CODE>foo</CODE>:
331      * <PRE>
332      *    void foo(int x) {
333      *        System.out.println("Foo: " + x);
334      *        x = 4;
335      *        System.out.println("pop here");
336      *    }
337      * </PRE>
338      * was called with <CODE>foo(7)</CODE> and <CODE>foo</CODE>
339      * is popped at the second <CODE>println</CODE> and resumed,
340      * it will print: <CODE>Foo: 4</CODE>.
341      * <P>
342      * Locks acquired by a popped frame are released when it
343      * is popped. This applies to synchronized methods that
344      * are popped, and to any synchronized blocks within them.
345      * <P>
346      * Finally blocks are not executed.
347      * <P>
348      * No aspect of state, other than this thread's execution point and
349      * locks, is affected by this call.  Specifically, the values of
350      * fields are unchanged, as are external resources such as
351      * I/O streams.  Additionally, the target program might be
352      * placed in a state that is impossible with normal program flow;
353      * for example, order of lock acquisition might be perturbed.
354      * Thus the target program may
355      * proceed differently than the user would expect.
356      * <P>
357      * The specified thread must be suspended.
358      * <P>
359      * All <code>StackFrame</code> objects for this thread are
360      * invalidated.
361      * <P>
362      * No events are generated by this method.
363      * <P>
364      * None of the frames through and including the frame for the caller
365      * of <i>frame</i> may be native.
366      * <P>
367      * Not all target virtual machines support this operation.
368      * Use {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()}
369      * to determine if the operation is supported.
370      *
371      * @param frame Stack frame to pop.  <CODE>frame</CODE> is on this
372      * thread's call stack.
373      *
374      * @throws java.lang.UnsupportedOperationException if
375      * the target virtual machine does not support this
376      * operation - see
377      * {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()}.
378      *
379      * @throws IncompatibleThreadStateException if this
380      * thread is not suspended.
381      *
382      * @throws java.lang.IllegalArgumentException if <CODE>frame</CODE>
383      * is not on this thread's call stack.
384      *
385      * @throws NativeMethodException if one of the frames that would be
386      * popped is that of a native method or if the frame previous to
387      * <i>frame</i> is native.
388      *
389      * @throws InvalidStackFrameException if <CODE>frame</CODE> has become
390      * invalid. Once this thread is resumed, the stack frame is
391      * no longer valid.  This exception is also thrown if there are no
392      * more frames.
393      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
394      *
395      * @since 1.4 */
396     void popFrames(StackFrame frame) throws IncompatibleThreadStateException;
397 
398     /**
399      * Force a method to return before it reaches a return
400      * statement.
401      * <p>
402      * The method which will return early is referred to as the
403      * called method. The called method is the current method (as
404      * defined by the Frames section in the Java Virtual Machine
405      * Specification) for the specified thread at the time this
406      * method is called.
407      * <p>
408      * The thread must be suspended.
409      * The return occurs when execution of Java programming
410      * language code is resumed on this thread. Between the call to
411      * this method and resumption of thread execution, the
412      * state of the stack is undefined.
413      * <p>
414      * No further instructions are executed in the called
415      * method. Specifically, finally blocks are not executed. Note:
416      * this can cause inconsistent states in the application.
417      * <p>
418      * A lock acquired by calling the called method (if it is a
419      * synchronized method) and locks acquired by entering
420      * synchronized blocks within the called method are
421      * released. Note: this does not apply to native locks or
422      * java.util.concurrent.locks locks.
423      * <p>
424      * Events, such as MethodExit, are generated as they would be in
425      * a normal return.
426      * <p>
427      * The called method must be a non-native Java programming
428      * language method. Forcing return on a thread with only one
429      * frame on the stack causes the thread to exit when resumed.
430      * <p>
431      * The <code>value</code> argument is the value that the
432      * method is to return.
433      * If the return type of the method is void, then value must
434      * be a  {@link VoidValue VoidValue}.
435      * Object values must be assignment compatible with the method return type
436      * (This implies that the method return type must be loaded through the
437      * enclosing class's class loader). Primitive values must be
438      * either assignment compatible with the method return type or must be
439      * convertible to the variable type without loss of information.
440      * See JLS section 5.2 for more information on assignment
441      * compatibility.
442      * <p>
443      * Not all target virtual machines support this operation.
444      * Use {@link VirtualMachine#canForceEarlyReturn()}
445      * to determine if the operation is supported.
446      *
447      * @param value the value the method is to return.
448      *
449      * @throws java.lang.UnsupportedOperationException if
450      * the target virtual machine does not support this
451      * operation - see
452      * {@link VirtualMachine#canGetInstanceInfo() canForceEarlyReturn()}
453      *
454      * @throws IncompatibleThreadStateException if this
455      * thread is not suspended.
456      *
457      * @throws NativeMethodException if the frame to be returned from
458      * is that of a native method.
459      *
460      * @throws InvalidStackFrameException if there are no frames.
461      *
462      * @throws InvalidTypeException if the value's type does not match
463      * the method's return type.
464      *
465      * @throws ClassNotLoadedException if the method's return type has not yet
466      * been loaded through the appropriate class loader.
467      *
468      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
469      *
470      * @since 1.6
471      */
472     void forceEarlyReturn(Value value) throws InvalidTypeException,
473                                               ClassNotLoadedException,
474                                               IncompatibleThreadStateException;
475 
476 }