Commit | Line | Data |
---|---|---|
bcd7e15f | 1 | @c -*-texinfo-*- |
16d1a084 DJ |
2 | |
3 | @c This file is part of the GDB manual. | |
4 | @c | |
383f836e | 5 | @c Copyright (C) 2003, 2004, 2005, 2006, 2008 |
16d1a084 DJ |
6 | @c Free Software Foundation, Inc. |
7 | @c | |
8 | @c See the file gdbint.texinfo for copying conditions. | |
9 | @c | |
10 | @c Also, the @deftypefun lines from this file are processed into a | |
11 | @c header file during the GDB build process. Permission is granted | |
12 | @c to redistribute and/or modify those lines under the terms of the | |
13 | @c GNU General Public License as published by the Free Software | |
14 | @c Foundation; either version 2 of the License, or (at your option) | |
15 | @c any later version. | |
16 | ||
bcd7e15f JB |
17 | @node GDB Observers |
18 | @appendix @value{GDBN} Currently available observers | |
19 | ||
20 | @section Implementation rationale | |
21 | @cindex observers implementation rationale | |
22 | ||
23 | An @dfn{observer} is an entity which is interested in being notified | |
24 | when GDB reaches certain states, or certain events occur in GDB. | |
25 | The entity being observed is called the @dfn{subject}. To receive | |
26 | notifications, the observer attaches a callback to the subject. | |
27 | One subject can have several observers. | |
28 | ||
29 | @file{observer.c} implements an internal generic low-level event | |
6be67e67 | 30 | notification mechanism. This generic event notification mechanism is |
bcd7e15f JB |
31 | then re-used to implement the exported high-level notification |
32 | management routines for all possible notifications. | |
33 | ||
34 | The current implementation of the generic observer provides support | |
35 | for contextual data. This contextual data is given to the subject | |
36 | when attaching the callback. In return, the subject will provide | |
37 | this contextual data back to the observer as a parameter of the | |
38 | callback. | |
39 | ||
40 | Note that the current support for the contextual data is only partial, | |
41 | as it lacks a mechanism that would deallocate this data when the | |
42 | callback is detached. This is not a problem so far, as this contextual | |
43 | data is only used internally to hold a function pointer. Later on, if | |
44 | a certain observer needs to provide support for user-level contextual | |
6be67e67 | 45 | data, then the generic notification mechanism will need to be |
bcd7e15f JB |
46 | enhanced to allow the observer to provide a routine to deallocate the |
47 | data when attaching the callback. | |
48 | ||
49 | The observer implementation is also currently not reentrant. | |
50 | In particular, it is therefore not possible to call the attach | |
51 | or detach routines during a notification. | |
52 | ||
2b4855ab AC |
53 | @section Debugging |
54 | Observer notifications can be traced using the command @samp{set debug | |
55 | observer 1} (@pxref{Debugging Output, , Optional messages about | |
56 | internal happenings, gdb, Debugging with @var{GDBN}}). | |
57 | ||
bcd7e15f JB |
58 | @section @code{normal_stop} Notifications |
59 | @cindex @code{normal_stop} observer | |
60 | @cindex notification about inferior execution stop | |
61 | ||
6be67e67 JB |
62 | @value{GDBN} notifies all @code{normal_stop} observers when the |
63 | inferior execution has just stopped, the associated messages and | |
64 | annotations have been printed, and the control is about to be returned | |
16d1a084 | 65 | to the user. |
6be67e67 JB |
66 | |
67 | Note that the @code{normal_stop} notification is not emitted when | |
68 | the execution stops due to a breakpoint, and this breakpoint has | |
69 | a condition that is not met. If the breakpoint has any associated | |
70 | commands list, the commands are executed after the notification | |
71 | is emitted. | |
bcd7e15f | 72 | |
7a464420 | 73 | The following interfaces are available to manage observers: |
bcd7e15f | 74 | |
7a464420 AC |
75 | @deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f}) |
76 | Using the function @var{f}, create an observer that is notified when | |
d3e8051b | 77 | ever @var{event} occurs, return the observer. |
bcd7e15f JB |
78 | @end deftypefun |
79 | ||
7a464420 | 80 | @deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer}); |
bcd7e15f | 81 | Remove @var{observer} from the list of observers to be notified when |
7a464420 | 82 | @var{event} occurs. |
bcd7e15f JB |
83 | @end deftypefun |
84 | ||
7a464420 AC |
85 | @deftypefun extern void observer_notify_@var{event} (void); |
86 | Send a notification to all @var{event} observers. | |
bcd7e15f JB |
87 | @end deftypefun |
88 | ||
7a464420 | 89 | The following observable events are defined: |
bcd7e15f | 90 | |
1d33d6ba VP |
91 | @deftypefun void normal_stop (struct bpstats *@var{bs}, int @var{print_frame}) |
92 | The inferior has stopped for real. The @var{bs} argument describes | |
93 | the breakpoints were are stopped at, if any. Second argument | |
94 | @var{print_frame} non-zero means display the location where the | |
95 | inferior has stopped. | |
7a464420 | 96 | @end deftypefun |
79346bcb OF |
97 | |
98 | @deftypefun void target_changed (struct target_ops *@var{target}) | |
67ab9a76 | 99 | The target's register contents have changed. |
79346bcb | 100 | @end deftypefun |
59caf092 | 101 | |
781b42b0 | 102 | @deftypefun void executable_changed (void) |
ea53e89f JB |
103 | The executable being debugged by GDB has changed: The user decided |
104 | to debug a different program, or the program he was debugging has | |
105 | been modified since being loaded by the debugger (by being recompiled, | |
106 | for instance). | |
107 | @end deftypefun | |
108 | ||
59caf092 AC |
109 | @deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty}) |
110 | @value{GDBN} has just connected to an inferior. For @samp{run}, | |
111 | @value{GDBN} calls this observer while the inferior is still stopped | |
112 | at the entry-point instruction. For @samp{attach} and @samp{core}, | |
113 | @value{GDBN} calls this observer immediately after connecting to the | |
114 | inferior, and before any information on the inferior has been printed. | |
115 | @end deftypefun | |
f3bb6704 | 116 | |
fbd1b305 MK |
117 | @deftypefun void solib_loaded (struct so_list *@var{solib}) |
118 | The shared library specified by @var{solib} has been loaded. Note that | |
119 | when @value{GDBN} calls this observer, the library's symbols probably | |
120 | haven't been loaded yet. | |
f3bb6704 JJ |
121 | @end deftypefun |
122 | ||
fbd1b305 MK |
123 | @deftypefun void solib_unloaded (struct so_list *@var{solib}) |
124 | The shared library specified by @var{solib} has been unloaded. | |
125 | @end deftypefun | |
06d3b283 UW |
126 | |
127 | @deftypefun void new_objfile (struct objfile *@var{objfile}) | |
128 | The symbol file specified by @var{objfile} has been loaded. | |
129 | Called with @var{objfile} equal to @code{NULL} to indicate | |
130 | previously loaded symbol table data has now been invalidated. | |
131 | @end deftypefun | |
132 | ||
683f2885 VP |
133 | @deftypefun void new_thread (struct thread_info *@var{t}) |
134 | The thread specified by @var{t} has been created. | |
135 | @end deftypefun | |
136 | ||
a07daef3 PA |
137 | @deftypefun void thread_exit (struct thread_info *@var{t}, int @var{silent}) |
138 | The thread specified by @var{t} has exited. The @var{silent} argument | |
139 | indicates that @value{GDBN} is removing the thread from its tables | |
140 | without wanting to notify the user about it. | |
063bfe2e VP |
141 | @end deftypefun |
142 | ||
252fbfc8 PA |
143 | @deftypefun void thread_stop_requested (ptid_t @var{ptid}) |
144 | An explicit stop request was issued to @var{ptid}. If @var{ptid} | |
145 | equals @var{minus_one_ptid}, the request applied to all threads. If | |
146 | @code{ptid_is_pid(ptid)} returns true, the request applied to all | |
147 | threads of the process pointed at by @var{ptid}. Otherwise, the | |
148 | request applied to the single thread pointed at by @var{ptid}. | |
149 | @end deftypefun | |
150 | ||
e1ac3328 VP |
151 | @deftypefun void target_resumed (ptid_t @var{ptid}) |
152 | The target was resumed. The @var{ptid} parameter specifies which | |
153 | thread was resume, and may be RESUME_ALL if all threads are resumed. | |
154 | @end deftypefun | |
383f836e | 155 | |
f3b1572e PA |
156 | @deftypefun void about_to_proceed (void) |
157 | The target is about to be proceeded. | |
158 | @end deftypefun | |
159 | ||
383f836e TT |
160 | @deftypefun void breakpoint_created (int @var{bpnum}) |
161 | A new breakpoint has been created. The argument @var{bpnum} is the | |
162 | number of the newly-created breakpoint. | |
163 | @end deftypefun | |
164 | ||
165 | @deftypefun void breakpoint_deleted (int @var{bpnum}) | |
166 | A breakpoint has been destroyed. The argument @var{bpnum} is the | |
167 | number of the newly-destroyed breakpoint. | |
168 | @end deftypefun | |
169 | ||
170 | @deftypefun void breakpoint_modified (int @var{bpnum}) | |
171 | A breakpoint has been modified in some way. The argument @var{bpnum} | |
172 | is the number of the modified breakpoint. | |
173 | @end deftypefun | |
174 | ||
175 | @deftypefun void tracepoint_created (int @var{tpnum}) | |
176 | A new tracepoint has been created. The argument @var{tpnum} is the | |
177 | number of the newly-created tracepoint. | |
178 | @end deftypefun | |
179 | ||
180 | @deftypefun void tracepoint_deleted (int @var{tpnum}) | |
181 | A tracepoint has been destroyed. The argument @var{tpnum} is the | |
182 | number of the newly-destroyed tracepoint. | |
183 | @end deftypefun | |
184 | ||
185 | @deftypefun void tracepoint_modified (int @var{tpnum}) | |
186 | A tracepoint has been modified in some way. The argument @var{tpnum} | |
187 | is the number of the modified tracepoint. | |
188 | @end deftypefun | |
189 | ||
190 | @deftypefun void architecture_changed (struct gdbarch *@var{newarch}) | |
191 | The current architecture has changed. The argument @var{newarch} is | |
192 | a pointer to the new architecture. | |
193 | @end deftypefun | |
194 | ||
5231c1fd PA |
195 | @deftypefun void thread_ptid_changed (ptid_t @var{old_ptid}, ptid_t @var{new_ptid}) |
196 | The thread's ptid has changed. The @var{old_ptid} parameter specifies | |
197 | the old value, and @var{new_ptid} specifies the new value. | |
198 | @end deftypefun | |
4a92f99b VP |
199 | |
200 | @deftypefun void new_inferior (int @var{pid}) | |
201 | @value{GDBN} has attached to a new inferior identified by @var{pid}. | |
202 | @end deftypefun | |
203 | ||
204 | @deftypefun void inferior_exit (int @var{pid}) | |
205 | Either @value{GDBN} detached from the inferior, or the inferior | |
206 | exited. The argument @var{pid} identifies the inferior. | |
207 | @end deftypefun | |
208 | ||
3ea85240 VP |
209 | @deftypefun void test_notification (int @var{somearg}) |
210 | This observer is used for internal testing. Do not use. | |
211 | See testsuite/gdb.gdb/observer.exp. | |
212 | @end deftypefun | |
213 |