Defines interfaces for debug model elements, source lookup, and launching.
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 an implementation 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).
The Debug Model
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.
The common elements defined by the debug model are:
- Debug Target - A debug target represents a debuggable program - for example, a virtual machine or a process.
- Thread - A debug target may contain one or more threads.
- Stack Frame - A suspended thread may contain one or more stack frames.
- Variable - A stack frame may contain variables.
- Value - Each variable has an associated value, and a value may contain more variables (to represent complex data structures and objects).
- Register Group - A stack frame may (optionally) be associated with one or more register groups.
- Register - A register group contains one or more registers.
- Memory Blocks - A debug target may (optionally) support the retrieval of arbitrary contiguous segments of memory.
- Breakpoint - Breakpoints suspend the execution of a program.
- Expression - An expression is a snippet of code that can be evaluated to produce a value.
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.
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.
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 IBreakpoint. 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.
Breakpoints are persisted via their underlying marker. Breakpoint markers defined with the persisted attribute as false 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 IBreakpoint 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.
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.
New Features in the Debug Model, Eclipse 3.0
Launch Delegate Enhancements
Lanuch delegates can optionally implement the new interface
ILaunchConfigurationDelegate2. This allows launch delegates to provide a launch object to be used for a launch. For example, when debugging on a server a delegate could create a new launch object or may reuse an existing launch object if the server is already running in debug mode. As well, the inteface provides a mechanism for performing a scoped build prior to launching (i.e. scoped to the projects in the workspace pertaining to the launch), and searching for errors in the workspace which may prevent the launch from succeeding (for example, compilation errors).
Extensible Watch Expressions
The debug platform provides an implementation of watch expressions. Debug models can contribute watch expression delegates if they support watch expressions. When a stack frame is selected, the associated delegate is queried to provide a value for a watch expression in that context. The debug platform provides persistence, enabling, disabling, entering, and editing of watch expressions.
Automatic Array Partitioning
The debug plug-in supports automatic partitioning of indexed collections, which partitions large arrays into sub-ranges in the variables view. This is supported with the introduction of a new interface in the debug model representing an indexed value -
IIndexedValue. If a value implements this interface, the variables view will automatically partition its elements as required, into sub-ranges
Logical Structure Types
Often, it is convenient to navigate complex data structures in terms of a logical structure, rather than an implementation structure. For example, no matter how a list is implemented (i.e. linked list, collection of arrays, etc.), it is often convenient to be able to view the list as an ordered collection. To facilitate the display of logical structures in the variables view, an extension point has been added (
org.eclipse.debug.core.logicalStructureTypes) allowing debug models to contribute logical structures of its values, where applicable. Debug models may contribute delegates to translate raw implementation values into logical values. The variables view will display the logical values, when the option to display logical structures is turned on. More than one logical structure can be provided for a single value - the user can choose which structure to display.
To support step filters on all stepping functions (into, over, return), a new interface has been added to the debug platform -
IStepFilters- which can be implemented by debug targets. This interface replaces
IFilteredStep, which is now deprecated. The debugger provides a global toggle that turns step filters on/off for all stepping functions. Debug targets should implement this new interface and honor the step filter enablement setting when stepping.
This change maintains binary compatibility with previous releases. However, targets wishing to leverage the new function must implement the new interface.
Interface Summary Interface Description IBinaryStreamMonitorA variant of
IStreamMonitorwhich does not touch the received content and pass it as bytes instead of strings.
IBinaryStreamsProxyA variant of
IStreamsProxywhich does not touch the proxied content and pass it as bytes instead of strings.
IBreakpointA breakpoint is capable of suspending the execution of a program at a specific location when a program is running in debug mode. IBreakpointImportParticipantThis interface defines a breakpoint import participant. IDebugElementA debug element represents an artifact in a program being debugged. IDebugModelProviderA debug model provider provides debug model identifiers. IDebugTargetA debug target is a debuggable execution context. IDisconnectThe ability to end a debug session with a target program and allow the target to continue running. IDropToFrameProvides the ability to drop to frame. IErrorReportingExpressionAn expression that can report errors which occurred during the expression's evaluation. IExpressionAn expression is a snippet of code that can be evaluated to produce a value. IFilteredStep Deprecated.clients should implement
IFlushableStreamMonitorA stream monitor who's contents can be flushed. IIndexedValueA value containing an indexed collection of variables - for example, an array. ILaunchConfigurationDelegateA launch configuration delegate performs launching for a specific type of launch configuration. ILaunchConfigurationDelegate2Optional enhancements to the launch configuration delegate interface. ILineBreakpointA breakpoint that can be located at a specific line of source code. ILogicalStructureTypeDelegateA delegate that provides a value representing the logical structure of a raw implementation value from a debug model. ILogicalStructureTypeDelegate2Optional extension to
ILogicalStructureTypeDelegatethat allows a logical structure type delegate to provide a description for a value.
ILogicalStructureTypeDelegate3Optional extension to
ILogicalStructureTypeDelegatethat allows a logical structure type delegate to garbage collect its logical structures once they're no longer displayed.
IMemoryBlockA contiguous segment of memory in an execution context. IMemoryBlockExtensionExtensions to
IMemoryBlockRetrievalSupports the retrieval of arbitrary blocks of memory. IMemoryBlockRetrievalExtensionExtended capabilities for memory block retrieval. IPersistableSourceLocatorA source locator that can be persisted and restored, to be used with a specific launch configuration. IProcessA process represents a program running in normal (non-debug) mode. IRegisterA register is a special kind of variable that is contained in a register group. IRegisterGroupA register group is a group of registers that are assigned to a stack frame. ISourceLocatorA source locator locates source elements for stack frames. IStackFrameA stack frame represents an execution context in a suspended thread. IStepProvides the ability to step into, over, and return from the current execution location. IStepFilterProvides the ability to filter out steps based on some object. IStepFiltersSupport for step filters for a debug target. IStreamMonitorA stream monitor manages the contents of the stream a process is writing to, and notifies registered listeners of changes in the stream. IStreamsProxyA streams proxy acts as proxy between the streams of a process and interested clients. IStreamsProxy2Extension to a streams proxy that allows closing of the output stream connected to the standard input stream of a proxy's process. ISuspendResumeProvides the ability to suspend and resume a thread or debug target. ITerminateProvides the ability to terminate an execution context - for example, a thread, debug target or process. IThreadA thread is a sequential flow of execution in a debug target. ITriggerPointTriggerPoint is a breakpoint property which defines a dependency relationship between all the breakpoints of a workspace and trigger points defined in a workspace. IValueA value represents the value of a variable. IValueModificationProvides the ability to modify the value of a variable in a target. IVariableA variable represents a visible data structure in a stack frame or value. IWatchExpressionA watch expression is an expression that is evaluated in the context of a specific stack frame, thread, debug target, process, or launch. IWatchExpressionDelegateA delegate which computes the value of a watch expression when provided a context. IWatchExpressionListenerA watch expression listener is notified when an
org.eclipse.debug.core.model.IWatchExpressionDelegatecompletes an evaluation.
IWatchExpressionResultThe result of an evaluation performed by an
IWatchpointA breakpoint that suspends when an associated variable is read or written.
Class Summary Class Description BreakpointAbstract implementation of a breakpoint. DebugElementImplementation of common function for debug elements. LaunchConfigurationDelegateDefault implementation of a launch configuration delegate. LineBreakpointAbstract implementation of a line breakpoint. MemoryByteA byte of memory in a memory block. RuntimeProcessStandard implementation of an
IProcessthat wrappers a system process (