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