/*******************************************************************************
 * 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);
}