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