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