1 /* 2 * Copyright (c) 2001, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. 8 * 9 * This code is distributed in the hope that it will be useful, but WITHOUT 10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 12 * version 2 for more details (a copy is included in the LICENSE file that 13 * accompanied this code). 14 * 15 * You should have received a copy of the GNU General Public License version 16 * 2 along with this work; if not, write to the Free Software Foundation, 17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 18 * 19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 20 * or visit www.oracle.com if you need additional information or have any 21 * questions. 22 * 23 */ 24 25 package sun.jvm.hotspot.debugger.cdbg; 26 27 import sun.jvm.hotspot.debugger.*; 28 29 /** <P> A highly experimental interface for process control and debug 30 events. May not be sufficiently portable; for this reason it has 31 been factored out from the CDebugger interface and support for it 32 is optional. </P> 33 34 <P> The ProcessControl interface defines a process control and 35 event model for debugging. When a process is attached to by the 36 base Debugger, all threads in the target process are suspended. 37 The ProcessControl interface allows resumption and re-suspension 38 of the threads in the target process, setting of breakpoints, and 39 reception of debugging events (breakpoint hit, signal received, 40 etc.). </P> 41 42 <P> Debugging events are generated one at a time by the target 43 process. They must be queued up by the underlying debugging 44 mechanism so that an attempt to send a second debugging event 45 blocks until the first has been serviced with a call to 46 debugEventResume. </P> */ 47 48 public interface ProcessControl { 49 /** Suspends all threads in the target process. A process is already 50 suspended when attached to by {@link 51 sun.jvm.hotspot.debugger.Debugger.attach(int)}. The application 52 should check for the presence of a debug event via 53 debugEventPoll() upon re-suspending the target process (if one 54 is not yet known to be present.) 55 56 @throw DebuggerException if the process is already suspended or 57 if the suspension failed for some other reason. */ suspend()58 public void suspend() throws DebuggerException; 59 60 /** Resumes all threads in the target process. 61 62 @throw DebuggerException if the process is not suspended or if 63 the resumption failed for some other reason. */ resume()64 public void resume() throws DebuggerException; 65 66 /** Indicates whether the target process is suspended. */ isSuspended()67 public boolean isSuspended() throws DebuggerException; 68 69 /** Sets a breakpoint at the given address. The target process must 70 be suspended in order to set a breakpoint. 71 72 @throw DebuggerException if the breakpoint could not be set for 73 some reason, including that a breakpoint is already set at that 74 address or that the underlying debugging mechanism does not 75 support that many breakpoints. */ setBreakpoint(Address addr)76 public void setBreakpoint(Address addr) 77 throws UnmappedAddressException, DebuggerException; 78 79 /** Clears a breakpoint at the given address. The target process 80 must be suspended in order to clear a breakpoint. 81 82 @throw DebuggerException if the breakpoint could not be cleared 83 for some reason, including that there was no breakpoint at that 84 address. */ clearBreakpoint(Address addr)85 public void clearBreakpoint(Address addr) throws DebuggerException; 86 87 /** Indicates whether a breakpoint is set at the given address. */ isBreakpointSet(Address addr)88 public boolean isBreakpointSet(Address addr) throws DebuggerException; 89 90 /** Polls for the presence of a debug event. Does not wait for one 91 to be generated; returns null if none was pending. The target 92 process does not need to be suspended. Returns the same 93 DebugEvent object until the debug event is handled via 94 debugEventContinue. Typically the application will suspend the 95 target process upon reception of a debug event but before 96 handling it via a call to debugEventContinue. This ensures that 97 the state of the thread which generated the debug event is 98 precisely what it was when the event was generated. 99 100 @return The pending debug event, or null if none pending. */ debugEventPoll()101 public DebugEvent debugEventPoll() throws DebuggerException; 102 103 /** Informs the target process to resume past this debug event. The 104 target process does not need to be suspended. Breakpoint debug 105 events must be handled transparently by the implementation to 106 re-execute the instruction and replace the breakpoint. (Ideally 107 they should be replaced in such a way that there is no race 108 condition between the re-execution and the re-insertion of the 109 breakpoint.) All other kinds of exceptions or signals are passed 110 on to the target process. 111 112 @throw DebuggerException if no debug event is pending. */ debugEventContinue()113 public void debugEventContinue() 114 throws DebuggerException; 115 } 116