Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 3f9882d9c246caad02e06d12ff863104eb37e8f2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
<!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 a debug model to support an extensible set of debug architectures.</p>

<h2>Package Specification</h2>

<p>This package defines classes and interfaces known as the &quot;debug model&quot; 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 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 contiguos 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 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 breakpoin marker with.</p>

<p>Breakpoint creation is a client responsibility, as the location in which a breakpoint may
be placed, and the attributes that a debug target requires to install a breakpoint is
specific to each debug architecture.</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 IBreakpoint interface and root breakpoint
implementation define a &quot;persisted&quot; 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>

Back to the top