KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdi > hcr > ThreadReference


1 /*******************************************************************************
2  * Copyright (c) 2000, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jdi.hcr;
12
13
14 import com.sun.jdi.Value;
15
16 /**
17  * Hot code replacement extension to <code>com.sun.jdi.ThreadReference</code>.
18  */
19 public interface ThreadReference {
20     /**
21      * Resumes the execution of this thread as if the next instruction was a return
22      * instruction with the given value. This causes the top stack frame to be popped with
23      * the given value.
24      * <p>
25      * A breakpoint instruction at the current instruction is not triggered that is, this
26      * operation takes precedence over breakpoints. <code>try-finally</code> blocks enclosing
27      * the current location will be triggered in due course.
28      * <p>
29      * The triggerFinallyAndSynchronizedBlocks option on this operation controls whether
30      * <code>try-finally</code> and <code>synchronized</code> blocks enclosing the current
31      * location should be triggered:
32      * <ul>
33      * <li>If no, the stack frame is popped, the return value is returned, and execution
34      * continues back in the caller. Note that <code>finally</code> blocks are not run,
35      * and that if the code is nested within a <code>synchronized</code> statement, the
36      * monitor lock is not released (however, if the method is </code>synchronized</code>
37      * the monitor lock will be properly released). This mechanism is sure-fire, but at
38      * the risk of not letting the target program clean itself up (e.g., close its files).
39      * <li>If yes, the VM checks to see whether there might be a <code>finally</code> or
40      * <code>synchronized</code> block enclosing the current instruction.
41      * <ul>
42      * <li>If there is no enclosing <code>finally</code> block, the operation reduces
43      * to the above case.
44      * <li>If there is an enclosing <code>finally</code> block, the VM creates a VM
45      * exception and activates the <code>finally</code> block with it. If this
46      * exception eventually causes the stack frame to be popped, the exception is
47      * caught by the VM itself, the return value is returned, and execution continues
48      * back in the caller.
49      * <ul>
50      * </ul>
51      * <p>
52      * Note that a <code>finally</code> block manifests itself as (and is indistinguishable
53      * from) a <code>catch Throwable</code> block. <code>synchronized</code> statements
54      * also compile to a <code> catch Throwable block<code>.The target program may inadventently
55      * end up catching this exception.
56      *
57      * Since the choices each have their pros and cons, making the decision
58      * is left to the debugger. However the later option is the recommended choice.
59      * <p>
60      * The reply to the operation contains a flag indicating whether any <code>finally</code> or
61      * <code>synchronized</code> blocks are enclosing the current instruction.
62      * <p>
63      * This operation is ignored if the thread was not suspended. If the thread was suspended multiple
64      * times, wait for the same number of resumes before executing the return instruction.
65      * <p>
66      * The returned value is ignored if the method returns void.
67      * <p>
68      * Throws an <code>OperationRefusedException</code> if the VM refused to perform this operation.
69      * This in recognition that the VM may be in an awkward state and unable to comply:
70      * <ul>
71      * <li>for example, execution is suspended in a native method,
72      * <li>for example, execution is suspended during class preparation.
73      * </ul>
74      */
75     public boolean doReturn(Value returnValue, boolean triggerFinallyAndSynchronizedBlocks);
76 }
77
Popular Tags