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