jdimodelsrc.org.eclipse.jdi.hcr.ThreadReference Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2023 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdi.hcr;
import com.sun.jdi.Value;
/**
* Hot code replacement extension to com.sun.jdi.ThreadReference.
*/
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.
*
* A breakpoint instruction at the current instruction is not triggered that is, this operation takes precedence over breakpoints.
* try-finally blocks enclosing the current location will be triggered in due course.
*
* The triggerFinallyAndSynchronizedBlocks option on this operation controls whether try-finally and synchronized blocks
* enclosing the current location should be triggered:
*
* - If no, the stack frame is popped, the return value is returned, and execution continues back in the caller. Note that
finally
* blocks are not run, and that if the code is nested within a synchronized statement, the monitor lock is not released (however, if
* the method is synchronized 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).
* - If yes, the VM checks to see whether there might be a
finally or synchronized block enclosing the current
* instruction.
*
* - If there is no enclosing
finally block, the operation reduces to the above case.ll
* - If there is an enclosing
finally block, the VM creates a VM exception and activates the finally 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.
*
*
*
* Note that a finally block manifests itself as (and is indistinguishable from) a catch Throwable block.
* synchronized statements also compile to a catch Throwable block. 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.
* The reply to the operation contains a flag indicating whether any finally or synchronized blocks are enclosing the
* current instruction.
* 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.
* The returned value is ignored if the method returns void.
* Throws an OperationRefusedException if the VM refused to perform this operation. This in recognition that the VM may be in an
* awkward state and unable to comply:
*
* - for example, execution is suspended in a native method,
*
- for example, execution is suspended during class preparation.
*
*
* @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);
}