/*
* Copyright (c) 2001, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*
*/
package sun.jvm.hotspot.debugger.cdbg;
import sun.jvm.hotspot.debugger.*;
A highly experimental interface for process control and debug
events. May not be sufficiently portable; for this reason it has
been factored out from the CDebugger interface and support for it
is optional.
The ProcessControl interface defines a process control and
event model for debugging. When a process is attached to by the
base Debugger, all threads in the target process are suspended.
The ProcessControl interface allows resumption and re-suspension
of the threads in the target process, setting of breakpoints, and
reception of debugging events (breakpoint hit, signal received,
etc.).
Debugging events are generated one at a time by the target
process. They must be queued up by the underlying debugging
mechanism so that an attempt to send a second debugging event
blocks until the first has been serviced with a call to
debugEventResume.
/** <P> A highly experimental interface for process control and debug
events. May not be sufficiently portable; for this reason it has
been factored out from the CDebugger interface and support for it
is optional. </P>
<P> The ProcessControl interface defines a process control and
event model for debugging. When a process is attached to by the
base Debugger, all threads in the target process are suspended.
The ProcessControl interface allows resumption and re-suspension
of the threads in the target process, setting of breakpoints, and
reception of debugging events (breakpoint hit, signal received,
etc.). </P>
<P> Debugging events are generated one at a time by the target
process. They must be queued up by the underlying debugging
mechanism so that an attempt to send a second debugging event
blocks until the first has been serviced with a call to
debugEventResume. </P> */
public interface ProcessControl {
Suspends all threads in the target process. A process is already suspended when attached to by
sun.jvm.hotspot.debugger.Debugger.attach(int). The application should check for the presence of a debug event via debugEventPoll() upon re-suspending the target process (if one is not yet known to be present.) @throw DebuggerException if the process is already suspended or
if the suspension failed for some other reason.
/** Suspends all threads in the target process. A process is already
suspended when attached to by {@link
sun.jvm.hotspot.debugger.Debugger.attach(int)}. The application
should check for the presence of a debug event via
debugEventPoll() upon re-suspending the target process (if one
is not yet known to be present.)
@throw DebuggerException if the process is already suspended or
if the suspension failed for some other reason. */
public void suspend() throws DebuggerException;
Resumes all threads in the target process.
@throw DebuggerException if the process is not suspended or if
the resumption failed for some other reason.
/** Resumes all threads in the target process.
@throw DebuggerException if the process is not suspended or if
the resumption failed for some other reason. */
public void resume() throws DebuggerException;
Indicates whether the target process is suspended. /** Indicates whether the target process is suspended. */
public boolean isSuspended() throws DebuggerException;
Sets a breakpoint at the given address. The target process must
be suspended in order to set a breakpoint.
@throw DebuggerException if the breakpoint could not be set for
some reason, including that a breakpoint is already set at that
address or that the underlying debugging mechanism does not
support that many breakpoints.
/** Sets a breakpoint at the given address. The target process must
be suspended in order to set a breakpoint.
@throw DebuggerException if the breakpoint could not be set for
some reason, including that a breakpoint is already set at that
address or that the underlying debugging mechanism does not
support that many breakpoints. */
public void setBreakpoint(Address addr)
throws UnmappedAddressException, DebuggerException;
Clears a breakpoint at the given address. The target process
must be suspended in order to clear a breakpoint.
@throw DebuggerException if the breakpoint could not be cleared
for some reason, including that there was no breakpoint at that
address.
/** Clears a breakpoint at the given address. The target process
must be suspended in order to clear a breakpoint.
@throw DebuggerException if the breakpoint could not be cleared
for some reason, including that there was no breakpoint at that
address. */
public void clearBreakpoint(Address addr) throws DebuggerException;
Indicates whether a breakpoint is set at the given address. /** Indicates whether a breakpoint is set at the given address. */
public boolean isBreakpointSet(Address addr) throws DebuggerException;
Polls for the presence of a debug event. Does not wait for one
to be generated; returns null if none was pending. The target
process does not need to be suspended. Returns the same
DebugEvent object until the debug event is handled via
debugEventContinue. Typically the application will suspend the
target process upon reception of a debug event but before
handling it via a call to debugEventContinue. This ensures that
the state of the thread which generated the debug event is
precisely what it was when the event was generated.
Returns: The pending debug event, or null if none pending.
/** Polls for the presence of a debug event. Does not wait for one
to be generated; returns null if none was pending. The target
process does not need to be suspended. Returns the same
DebugEvent object until the debug event is handled via
debugEventContinue. Typically the application will suspend the
target process upon reception of a debug event but before
handling it via a call to debugEventContinue. This ensures that
the state of the thread which generated the debug event is
precisely what it was when the event was generated.
@return The pending debug event, or null if none pending. */
public DebugEvent debugEventPoll() throws DebuggerException;
Informs the target process to resume past this debug event. The
target process does not need to be suspended. Breakpoint debug
events must be handled transparently by the implementation to
re-execute the instruction and replace the breakpoint. (Ideally
they should be replaced in such a way that there is no race
condition between the re-execution and the re-insertion of the
breakpoint.) All other kinds of exceptions or signals are passed
on to the target process.
@throw DebuggerException if no debug event is pending.
/** Informs the target process to resume past this debug event. The
target process does not need to be suspended. Breakpoint debug
events must be handled transparently by the implementation to
re-execute the instruction and replace the breakpoint. (Ideally
they should be replaced in such a way that there is no race
condition between the re-execution and the re-insertion of the
breakpoint.) All other kinds of exceptions or signals are passed
on to the target process.
@throw DebuggerException if no debug event is pending. */
public void debugEventContinue()
throws DebuggerException;
}