OpenJDK 27 · sun.jvm.hotspot.debugger.cdbg.ProcessControl

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.

Method Summary

Modifier and Type	Method and Description
public void	clearBreakpoint(Address addr) Clears a breakpoint at the given address.
public void	debugEventContinue() Informs the target process to resume past this debug event.
public DebugEvent	Returns: The pending debug event, or null if none pending. debugEventPoll() Polls for the presence of a debug event.
public boolean	isBreakpointSet(Address addr) Indicates whether a breakpoint is set at the given address.
public boolean	isSuspended() Indicates whether the target process is suspended.
public void	resume() Resumes all threads in the target process.
public void	setBreakpoint(Address addr) Sets a breakpoint at the given address.
public void	suspend() Suspends all threads in the target process.

Method Detail

clearBreakpoint	back to summary
public void clearBreakpoint(Address addr) throws DebuggerException Clears a breakpoint at the given address. The target process must be suspended in order to clear a breakpoint. Exceptions DebuggerException: if the breakpoint could not be cleared for some reason, including that there was no breakpoint at that address.

clearBreakpoint

back to summary

public void clearBreakpoint(Address addr) throws DebuggerException

Clears a breakpoint at the given address. The target process must be suspended in order to clear a breakpoint.

Exceptions

DebuggerException:: if the breakpoint could not be cleared for some reason, including that there was no breakpoint at that address.

debugEventContinue	back to summary
public void debugEventContinue() 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. Exceptions DebuggerException: if no debug event is pending.

debugEventContinue

back to summary

public void debugEventContinue() 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.

Exceptions

DebuggerException:: if no debug event is pending.

debugEventPoll	back to summary
public DebugEvent debugEventPoll() 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:DebugEvent The pending debug event, or null if none pending.

debugEventPoll

back to summary

public DebugEvent debugEventPoll() 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:DebugEvent: The pending debug event, or null if none pending.

isBreakpointSet	back to summary
public boolean isBreakpointSet(Address addr) throws DebuggerException Indicates whether a breakpoint is set at the given address.

isSuspended	back to summary
public boolean isSuspended() throws DebuggerException Indicates whether the target process is suspended.

resume	back to summary
public void resume() throws DebuggerException Resumes all threads in the target process. Exceptions DebuggerException: if the process is not suspended or if the resumption failed for some other reason.

resume

back to summary

public void resume() throws DebuggerException

Resumes all threads in the target process.

Exceptions

DebuggerException:: if the process is not suspended or if the resumption failed for some other reason.

setBreakpoint	back to summary
public void setBreakpoint(Address addr) throws UnmappedAddressException, DebuggerException Sets a breakpoint at the given address. The target process must be suspended in order to set a breakpoint. Exceptions 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.

setBreakpoint

back to summary

public void setBreakpoint(Address addr) throws UnmappedAddressException, DebuggerException

Sets a breakpoint at the given address. The target process must be suspended in order to set a breakpoint.

Exceptions

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.

suspend back to summary

suspend	back to summary
public void suspend() throws DebuggerException 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.) Exceptions DebuggerException: if the process is already suspended or if the suspension failed for some other reason.

public void suspend() throws DebuggerException

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.)

Exceptions

DebuggerException:: if the process is already suspended or if the suspension failed for some other reason.

public Interface ProcessControl

Method Summary

Method Detail