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