| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <title>Eclipse Debug Platform [org.eclipse.debug.core.model]</title> |
| </head> |
| |
| <body bgcolor="#FFFFFF"> |
| |
| <p>Defines interfaces for debug model elements, source lookup, and launching.</p> |
| |
| <h2>Package Specification</h2> |
| |
| <p>This package defines classes and interfaces known as the "debug model" |
| which support an extensible set of debug architectures and languages. The debug |
| model is a set of interfaces representing common artifacts in debuggable programs. |
| The debug plug-in itself does not provide any implementations of a debug model. |
| It is intended that third parties providing an integrated set of development |
| tools for a specific language will also implement a debug model for that language, |
| using an underlying debug architecture of their choice. For example, Java development |
| tooling provides an implementation of a debug model based on the standard Java |
| Platform Debug Architecture (JPDA).</p> |
| |
| <h4>The Debug Model</h4> |
| |
| <p>A client implements a debug model by |
| providing an implementation of the interfaces defined in this package. (There is no explicit |
| extension point that represents a debug model). Each debug model provides one or more |
| launch configuration types capable of initiating a debug session.</p> |
| |
| <p>The common elements defined by the debug model are: |
| |
| <ul> |
| <li>Debug Target - A debug target represents a debuggable program - for example, a virtual |
| machine or a process.</li> |
| <li>Thread - A debug target may contain one or more threads.</li> |
| <li>Stack Frame - A suspended thread may contain one or more stack frames.</li> |
| <li>Variable - A stack frame may contain variables.</li> |
| <li>Value - Each variable has an associated value, and a value may contain more variables (to |
| represent complex data structures and objects).</li> |
| <li>Register Group - A stack frame may (optionally) be associated with one or more register |
| groups.</li> |
| <li>Register - A register group contains one or more registers.</li> |
| <li>Memory Blocks - A debug target may (optionally) support the retrieval of |
| arbitrary contiguous segments of memory.</li> |
| <li>Breakpoint - Breakpoints suspend the execution of a program.</li> |
| <li>Expression - An expression is a snippet of code that can be evaluated to |
| produce a value.</li> |
| </ul> |
| |
| <p>A debug model implementation is responsible for firing debug events. A debug event |
| corresponds to an event in a program being debugged - for example the creation or |
| termination of a thread.</p> |
| |
| <h4>Breakpoints</h4> |
| |
| <p>Breakpoints are used to suspend the execution of a program being debugged. There are |
| many kinds of breakpoints - line breakpoints, conditional line breakpoints, hit count |
| breakpoints, exception breakpoints, etc. The kinds of breakpoints supported by each debug |
| architecture, and the information required to create those breakpoints |
| is dictated by each debug architecture. The debug platform supports an extensible |
| set of breakpoint via the breakpoints extension point.</p> |
| |
| <p>The debug platform provides a breakpoint manager that maintains the collection |
| of all registered breakpoints. Clients add and remove breakpoints via this manager. |
| Breakpoints are implemented by instances of <b>IBreakpoint</b>. |
| Each breakpoint object has an associated marker, which provides persistence |
| and presentation in editors. The debug platform defines a generic breakpoint |
| and line breakpoint, as well as their corresponding marker definitions. Breakpoint |
| creation is a client responsibility - that is, defining the attributes of a |
| breakpoint and the resource to associate a breakpoint marker with.</p> |
| |
| <h5>Persistence</h5> |
| |
| <p>Breakpoints are persisted via their underlying marker. Breakpoint markers defined |
| with the <b>persisted</b> attribute as <b>false</b> will not be persisted. Breakpoints |
| are restored at workspace startup time by the breakpoint manager - that is, |
| breakpoint objects are created for all persisted markers which are a subtype |
| of the root breakpoint marker and are added to the breakpoint manager. To allow |
| for selective persistence of breakpoints (of the same kind), the <b>IBreakpoint</b> |
| interface and root breakpoint implementation defines a "persisted" |
| attribute. If this value is set to false, the breakpoint will not be persisted |
| across workspace invocations.</p> |
| |
| <h5>Change Notification</h5> |
| |
| <p>As breakpoint markers are modified (created, removed, and changed), resource deltas |
| are created by the platform. The breakpoint manager translates pertinent resource deltas |
| into breakpoint change notifications (breakpoint added/removed/changed messages). Interested |
| listeners may register with the breakpoint manager. The breakpoint manager only fires change |
| notifications for registered breakpoints. This simplifies breakpoint processing for clients, |
| as resource delta traversal and analysis is not required. Debug targets that support breakpoints |
| should register for breakpoint change notifications.</p> |
| |
| </body> |
| </html> |
