/*******************************************************************************
* Copyright (c) 2000, 2011 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdi.hcr;
import com.sun.jdi.Value;
/**
* Hot code replacement extension to <code>com.sun.jdi.ThreadReference</code>.
*/
public interface ThreadReference {
/**
* Resumes the execution of this thread as if the next instruction was a
* return instruction with the given value. This causes the top stack frame
* to be popped with the given value.
* <p>
* A breakpoint instruction at the current instruction is not triggered that
* is, this operation takes precedence over breakpoints.
* <code>try-finally</code> blocks enclosing the current location will be
* triggered in due course.
* <p>
* The triggerFinallyAndSynchronizedBlocks option on this operation controls
* whether <code>try-finally</code> and <code>synchronized</code> blocks
* enclosing the current location should be triggered:
* <ul>
* <li>If no, the stack frame is popped, the return value is returned, and
* execution continues back in the caller. Note that <code>finally</code>
* blocks are not run, and that if the code is nested within a
* <code>synchronized</code> statement, the monitor lock is not released
* (however, if the method is </code>synchronized</code> the monitor lock
* will be properly released). This mechanism is sure-fire, but at the risk
* of not letting the target program clean itself up (e.g., close its
* files).
* <li>If yes, the VM checks to see whether there might be a
* <code>finally</code> or <code>synchronized</code> block enclosing the
* current instruction.
* <ul>
* <li>If there is no enclosing <code>finally</code> block, the operation
* reduces to the above case.
* <li>If there is an enclosing <code>finally</code> block, the VM creates a
* VM exception and activates the <code>finally</code> block with it. If
* this exception eventually causes the stack frame to be popped, the
* exception is caught by the VM itself, the return value is returned, and
* execution continues back in the caller.
* <ul>
* </ul>
* <p>
* Note that a <code>finally</code> block manifests itself as (and is
* indistinguishable from) a <code>catch Throwable</code> block.
* <code>synchronized</code> statements also compile to a
* <code> catch Throwable block<code>.The target program may inadventently
* end up catching this exception.
*
* Since the choices each have their pros and cons, making the decision
* is left to the debugger. However the later option is the recommended choice.
* <p>
* The reply to the operation contains a flag indicating whether any <code>finally</code>
* or <code>synchronized</code> blocks are enclosing the current
* instruction.
* <p>
* This operation is ignored if the thread was not suspended. If the thread
* was suspended multiple times, wait for the same number of resumes before
* executing the return instruction.
* <p>
* The returned value is ignored if the method returns void.
* <p>
* Throws an <code>OperationRefusedException</code> if the VM refused to
* perform this operation. This in recognition that the VM may be in an
* awkward state and unable to comply:
* <ul>
* <li>for example, execution is suspended in a native method,
* <li>for example, execution is suspended during class preparation.
* </ul>
* @param returnValue the value to return from the thread with
* @param triggerFinallyAndSynchronizedBlocks if finally / synchronization blocks should be executed before resuming
* @return if the forced return was successful
*/
public boolean doReturn(Value returnValue,
boolean triggerFinallyAndSynchronizedBlocks);
}