/*******************************************************************************
 * Copyright (c) 2000, 2005 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>
	 */
	public boolean doReturn(Value returnValue, boolean triggerFinallyAndSynchronizedBlocks);
}