Commit | Line | Data |
---|---|---|
bcd7e15f JB |
1 | @c -*-texinfo-*- |
2 | @node GDB Observers | |
3 | @appendix @value{GDBN} Currently available observers | |
4 | ||
5 | @section Implementation rationale | |
6 | @cindex observers implementation rationale | |
7 | ||
8 | An @dfn{observer} is an entity which is interested in being notified | |
9 | when GDB reaches certain states, or certain events occur in GDB. | |
10 | The entity being observed is called the @dfn{subject}. To receive | |
11 | notifications, the observer attaches a callback to the subject. | |
12 | One subject can have several observers. | |
13 | ||
14 | @file{observer.c} implements an internal generic low-level event | |
6be67e67 | 15 | notification mechanism. This generic event notification mechanism is |
bcd7e15f JB |
16 | then re-used to implement the exported high-level notification |
17 | management routines for all possible notifications. | |
18 | ||
19 | The current implementation of the generic observer provides support | |
20 | for contextual data. This contextual data is given to the subject | |
21 | when attaching the callback. In return, the subject will provide | |
22 | this contextual data back to the observer as a parameter of the | |
23 | callback. | |
24 | ||
25 | Note that the current support for the contextual data is only partial, | |
26 | as it lacks a mechanism that would deallocate this data when the | |
27 | callback is detached. This is not a problem so far, as this contextual | |
28 | data is only used internally to hold a function pointer. Later on, if | |
29 | a certain observer needs to provide support for user-level contextual | |
6be67e67 | 30 | data, then the generic notification mechanism will need to be |
bcd7e15f JB |
31 | enhanced to allow the observer to provide a routine to deallocate the |
32 | data when attaching the callback. | |
33 | ||
34 | The observer implementation is also currently not reentrant. | |
35 | In particular, it is therefore not possible to call the attach | |
36 | or detach routines during a notification. | |
37 | ||
2b4855ab AC |
38 | @section Debugging |
39 | Observer notifications can be traced using the command @samp{set debug | |
40 | observer 1} (@pxref{Debugging Output, , Optional messages about | |
41 | internal happenings, gdb, Debugging with @var{GDBN}}). | |
42 | ||
bcd7e15f JB |
43 | @section @code{normal_stop} Notifications |
44 | @cindex @code{normal_stop} observer | |
45 | @cindex notification about inferior execution stop | |
46 | ||
6be67e67 JB |
47 | @value{GDBN} notifies all @code{normal_stop} observers when the |
48 | inferior execution has just stopped, the associated messages and | |
49 | annotations have been printed, and the control is about to be returned | |
50 | to the user. | |
51 | ||
52 | Note that the @code{normal_stop} notification is not emitted when | |
53 | the execution stops due to a breakpoint, and this breakpoint has | |
54 | a condition that is not met. If the breakpoint has any associated | |
55 | commands list, the commands are executed after the notification | |
56 | is emitted. | |
bcd7e15f | 57 | |
7a464420 | 58 | The following interfaces are available to manage observers: |
bcd7e15f | 59 | |
7a464420 AC |
60 | @deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f}) |
61 | Using the function @var{f}, create an observer that is notified when | |
62 | ever @var{event} occures, return the observer. | |
bcd7e15f JB |
63 | @end deftypefun |
64 | ||
7a464420 | 65 | @deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer}); |
bcd7e15f | 66 | Remove @var{observer} from the list of observers to be notified when |
7a464420 | 67 | @var{event} occurs. |
bcd7e15f JB |
68 | @end deftypefun |
69 | ||
7a464420 AC |
70 | @deftypefun extern void observer_notify_@var{event} (void); |
71 | Send a notification to all @var{event} observers. | |
bcd7e15f JB |
72 | @end deftypefun |
73 | ||
7a464420 | 74 | The following observable events are defined: |
bcd7e15f | 75 | |
7a464420 AC |
76 | @c note: all events must take at least one parameter. |
77 | ||
78 | @deftypefun void normal_stop (struct bpstats *@var{bs}) | |
79 | The inferior has stopped for real. | |
80 | @end deftypefun | |
79346bcb OF |
81 | |
82 | @deftypefun void target_changed (struct target_ops *@var{target}) | |
67ab9a76 | 83 | The target's register contents have changed. |
79346bcb | 84 | @end deftypefun |
59caf092 | 85 | |
ea53e89f JB |
86 | @deftypefun void executable_changed (void *@var{unused_args}) |
87 | The executable being debugged by GDB has changed: The user decided | |
88 | to debug a different program, or the program he was debugging has | |
89 | been modified since being loaded by the debugger (by being recompiled, | |
90 | for instance). | |
91 | @end deftypefun | |
92 | ||
59caf092 AC |
93 | @deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty}) |
94 | @value{GDBN} has just connected to an inferior. For @samp{run}, | |
95 | @value{GDBN} calls this observer while the inferior is still stopped | |
96 | at the entry-point instruction. For @samp{attach} and @samp{core}, | |
97 | @value{GDBN} calls this observer immediately after connecting to the | |
98 | inferior, and before any information on the inferior has been printed. | |
99 | @end deftypefun | |
f3bb6704 | 100 | |
fbd1b305 MK |
101 | @deftypefun void solib_loaded (struct so_list *@var{solib}) |
102 | The shared library specified by @var{solib} has been loaded. Note that | |
103 | when @value{GDBN} calls this observer, the library's symbols probably | |
104 | haven't been loaded yet. | |
f3bb6704 JJ |
105 | @end deftypefun |
106 | ||
fbd1b305 MK |
107 | @deftypefun void solib_unloaded (struct so_list *@var{solib}) |
108 | The shared library specified by @var{solib} has been unloaded. | |
109 | @end deftypefun |