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 */ name()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 */ suspend()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 */ resume()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 */ suspendCount()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 */ stop(ObjectReference throwable)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 */ interrupt()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 */ status()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 */ isSuspended()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 */ isAtBreakpoint()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 */ threadGroup()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 */ frameCount()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 */ frames()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 */ frame(int index)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 < 0 235 * start >= {@link #frameCount} 236 * length < 0 237 * (start+length) > {@link #frameCount}</pre> 238 */ frames(int start, int length)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 */ ownedMonitors()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 */ ownedMonitorsAndFrames()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 */ currentContendedMonitor()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 */ popFrames(StackFrame frame)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 */ forceEarlyReturn(Value value)469 void forceEarlyReturn(Value value) throws InvalidTypeException, 470 ClassNotLoadedException, 471 IncompatibleThreadStateException; 472 473 } 474