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