| 1 | @c -*-texinfo-*- |
| 2 | |
| 3 | @c This file is part of the GDB manual. |
| 4 | @c |
| 5 | @c Copyright (C) 2003-2006, 2008-2012 Free Software Foundation, Inc. |
| 6 | @c |
| 7 | @c See the file gdbint.texinfo for copying conditions. |
| 8 | @c |
| 9 | @c Also, the @deftypefun lines from this file are processed into a |
| 10 | @c header file during the GDB build process. Permission is granted |
| 11 | @c to redistribute and/or modify those lines under the terms of the |
| 12 | @c GNU General Public License as published by the Free Software |
| 13 | @c Foundation; either version 3 of the License, or (at your option) |
| 14 | @c any later version. |
| 15 | |
| 16 | @node GDB Observers |
| 17 | @appendix @value{GDBN} Currently available observers |
| 18 | |
| 19 | @section Implementation rationale |
| 20 | @cindex observers implementation rationale |
| 21 | |
| 22 | An @dfn{observer} is an entity which is interested in being notified |
| 23 | when GDB reaches certain states, or certain events occur in GDB. |
| 24 | The entity being observed is called the @dfn{subject}. To receive |
| 25 | notifications, the observer attaches a callback to the subject. |
| 26 | One subject can have several observers. |
| 27 | |
| 28 | @file{observer.c} implements an internal generic low-level event |
| 29 | notification mechanism. This generic event notification mechanism is |
| 30 | then re-used to implement the exported high-level notification |
| 31 | management routines for all possible notifications. |
| 32 | |
| 33 | The current implementation of the generic observer provides support |
| 34 | for contextual data. This contextual data is given to the subject |
| 35 | when attaching the callback. In return, the subject will provide |
| 36 | this contextual data back to the observer as a parameter of the |
| 37 | callback. |
| 38 | |
| 39 | Note that the current support for the contextual data is only partial, |
| 40 | as it lacks a mechanism that would deallocate this data when the |
| 41 | callback is detached. This is not a problem so far, as this contextual |
| 42 | data is only used internally to hold a function pointer. Later on, if |
| 43 | a certain observer needs to provide support for user-level contextual |
| 44 | data, then the generic notification mechanism will need to be |
| 45 | enhanced to allow the observer to provide a routine to deallocate the |
| 46 | data when attaching the callback. |
| 47 | |
| 48 | The observer implementation is also currently not reentrant. |
| 49 | In particular, it is therefore not possible to call the attach |
| 50 | or detach routines during a notification. |
| 51 | |
| 52 | @section Debugging |
| 53 | Observer notifications can be traced using the command @samp{set debug |
| 54 | observer 1} (@pxref{Debugging Output, , Optional messages about |
| 55 | internal happenings, gdb, Debugging with @var{GDBN}}). |
| 56 | |
| 57 | @section @code{normal_stop} Notifications |
| 58 | @cindex @code{normal_stop} observer |
| 59 | @cindex notification about inferior execution stop |
| 60 | |
| 61 | @value{GDBN} notifies all @code{normal_stop} observers when the |
| 62 | inferior execution has just stopped, the associated messages and |
| 63 | annotations have been printed, and the control is about to be returned |
| 64 | to the user. |
| 65 | |
| 66 | Note that the @code{normal_stop} notification is not emitted when |
| 67 | the execution stops due to a breakpoint, and this breakpoint has |
| 68 | a condition that is not met. If the breakpoint has any associated |
| 69 | commands list, the commands are executed after the notification |
| 70 | is emitted. |
| 71 | |
| 72 | The following interfaces are available to manage observers: |
| 73 | |
| 74 | @deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f}) |
| 75 | Using the function @var{f}, create an observer that is notified when |
| 76 | ever @var{event} occurs, return the observer. |
| 77 | @end deftypefun |
| 78 | |
| 79 | @deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer}); |
| 80 | Remove @var{observer} from the list of observers to be notified when |
| 81 | @var{event} occurs. |
| 82 | @end deftypefun |
| 83 | |
| 84 | @deftypefun extern void observer_notify_@var{event} (void); |
| 85 | Send a notification to all @var{event} observers. |
| 86 | @end deftypefun |
| 87 | |
| 88 | The following observable events are defined: |
| 89 | |
| 90 | @deftypefun void normal_stop (struct bpstats *@var{bs}, int @var{print_frame}) |
| 91 | The inferior has stopped for real. The @var{bs} argument describes |
| 92 | the breakpoints were are stopped at, if any. Second argument |
| 93 | @var{print_frame} non-zero means display the location where the |
| 94 | inferior has stopped. |
| 95 | @end deftypefun |
| 96 | |
| 97 | @deftypefun void target_changed (struct target_ops *@var{target}) |
| 98 | The target's register contents have changed. |
| 99 | @end deftypefun |
| 100 | |
| 101 | @deftypefun void executable_changed (void) |
| 102 | The executable being debugged by GDB has changed: The user decided |
| 103 | to debug a different program, or the program he was debugging has |
| 104 | been modified since being loaded by the debugger (by being recompiled, |
| 105 | for instance). |
| 106 | @end deftypefun |
| 107 | |
| 108 | @deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty}) |
| 109 | @value{GDBN} has just connected to an inferior. For @samp{run}, |
| 110 | @value{GDBN} calls this observer while the inferior is still stopped |
| 111 | at the entry-point instruction. For @samp{attach} and @samp{core}, |
| 112 | @value{GDBN} calls this observer immediately after connecting to the |
| 113 | inferior, and before any information on the inferior has been printed. |
| 114 | @end deftypefun |
| 115 | |
| 116 | @deftypefun void record_changed (struct inferior *@var{inferior}, int @var{started}) |
| 117 | The status of process record for inferior @var{inferior} in |
| 118 | @value{GDBN} has changed. The process record is started if |
| 119 | @var{started} is true, and the process record is stopped if |
| 120 | @var{started} is false. |
| 121 | @end deftypefun |
| 122 | |
| 123 | @deftypefun void solib_loaded (struct so_list *@var{solib}) |
| 124 | The shared library specified by @var{solib} has been loaded. Note that |
| 125 | when @value{GDBN} calls this observer, the library's symbols probably |
| 126 | haven't been loaded yet. |
| 127 | @end deftypefun |
| 128 | |
| 129 | @deftypefun void solib_unloaded (struct so_list *@var{solib}) |
| 130 | The shared library specified by @var{solib} has been unloaded. |
| 131 | Note that when @value{GDBN} calls this observer, the library's |
| 132 | symbols have not been unloaded yet, and thus are still available. |
| 133 | @end deftypefun |
| 134 | |
| 135 | @deftypefun void new_objfile (struct objfile *@var{objfile}) |
| 136 | The symbol file specified by @var{objfile} has been loaded. |
| 137 | Called with @var{objfile} equal to @code{NULL} to indicate |
| 138 | previously loaded symbol table data has now been invalidated. |
| 139 | @end deftypefun |
| 140 | |
| 141 | @deftypefun void new_thread (struct thread_info *@var{t}) |
| 142 | The thread specified by @var{t} has been created. |
| 143 | @end deftypefun |
| 144 | |
| 145 | @deftypefun void thread_exit (struct thread_info *@var{t}, int @var{silent}) |
| 146 | The thread specified by @var{t} has exited. The @var{silent} argument |
| 147 | indicates that @value{GDBN} is removing the thread from its tables |
| 148 | without wanting to notify the user about it. |
| 149 | @end deftypefun |
| 150 | |
| 151 | @deftypefun void thread_stop_requested (ptid_t @var{ptid}) |
| 152 | An explicit stop request was issued to @var{ptid}. If @var{ptid} |
| 153 | equals @var{minus_one_ptid}, the request applied to all threads. If |
| 154 | @code{ptid_is_pid(ptid)} returns true, the request applied to all |
| 155 | threads of the process pointed at by @var{ptid}. Otherwise, the |
| 156 | request applied to the single thread pointed at by @var{ptid}. |
| 157 | @end deftypefun |
| 158 | |
| 159 | @deftypefun void target_resumed (ptid_t @var{ptid}) |
| 160 | The target was resumed. The @var{ptid} parameter specifies which |
| 161 | thread was resume, and may be RESUME_ALL if all threads are resumed. |
| 162 | @end deftypefun |
| 163 | |
| 164 | @deftypefun void about_to_proceed (void) |
| 165 | The target is about to be proceeded. |
| 166 | @end deftypefun |
| 167 | |
| 168 | @deftypefun void breakpoint_created (struct breakpoint *@var{b}) |
| 169 | A new breakpoint @var{b} has been created. |
| 170 | @end deftypefun |
| 171 | |
| 172 | @deftypefun void breakpoint_deleted (struct breakpoint *@var{b}) |
| 173 | A breakpoint has been destroyed. The argument @var{b} is the |
| 174 | pointer to the destroyed breakpoint. |
| 175 | @end deftypefun |
| 176 | |
| 177 | @deftypefun void breakpoint_modified (struct breakpoint *@var{b}) |
| 178 | A breakpoint has been modified in some way. The argument @var{b} |
| 179 | is the modified breakpoint. |
| 180 | @end deftypefun |
| 181 | |
| 182 | @deftypefun void tracepoint_created (int @var{tpnum}) |
| 183 | A new tracepoint has been created. The argument @var{tpnum} is the |
| 184 | number of the newly-created tracepoint. |
| 185 | @end deftypefun |
| 186 | |
| 187 | @deftypefun void tracepoint_deleted (int @var{tpnum}) |
| 188 | A tracepoint has been destroyed. The argument @var{tpnum} is the |
| 189 | number of the newly-destroyed tracepoint. |
| 190 | @end deftypefun |
| 191 | |
| 192 | @deftypefun void tracepoint_modified (int @var{tpnum}) |
| 193 | A tracepoint has been modified in some way. The argument @var{tpnum} |
| 194 | is the number of the modified tracepoint. |
| 195 | @end deftypefun |
| 196 | |
| 197 | @deftypefun void traceframe_changed (int @var{tfnum}, int @var{tpnum}) |
| 198 | The trace frame is changed to @var{tfnum} (e.g., by using the |
| 199 | @code{tfind} command). If @var{tfnum} is negative, it means |
| 200 | @value{GDBN} resumes live debugging. The number of the tracepoint |
| 201 | associated with this traceframe is @var{tpnum}. |
| 202 | @end deftypefun |
| 203 | |
| 204 | @deftypefun void architecture_changed (struct gdbarch *@var{newarch}) |
| 205 | The current architecture has changed. The argument @var{newarch} is |
| 206 | a pointer to the new architecture. |
| 207 | @end deftypefun |
| 208 | |
| 209 | @deftypefun void thread_ptid_changed (ptid_t @var{old_ptid}, ptid_t @var{new_ptid}) |
| 210 | The thread's ptid has changed. The @var{old_ptid} parameter specifies |
| 211 | the old value, and @var{new_ptid} specifies the new value. |
| 212 | @end deftypefun |
| 213 | |
| 214 | @deftypefun void inferior_added (struct inferior *@var{inf}) |
| 215 | The inferior @var{inf} has been added to the list of inferiors. At |
| 216 | this point, it might not be associated with any process. |
| 217 | @end deftypefun |
| 218 | |
| 219 | @deftypefun void inferior_appeared (struct inferior *@var{inf}) |
| 220 | The inferior identified by @var{inf} has been attached to a process. |
| 221 | @end deftypefun |
| 222 | |
| 223 | @deftypefun void inferior_exit (struct inferior *@var{inf}) |
| 224 | Either the inferior associated with @var{inf} has been detached from the |
| 225 | process, or the process has exited. |
| 226 | @end deftypefun |
| 227 | |
| 228 | @deftypefun void inferior_removed (struct inferior *@var{inf}) |
| 229 | The inferior @var{inf} has been removed from the list of inferiors. |
| 230 | This method is called immediately before freeing @var{inf}. |
| 231 | @end deftypefun |
| 232 | |
| 233 | @deftypefun void memory_changed (CORE_ADDR @var{addr}, ssize_t @var{len}, const bfd_byte *@var{data}) |
| 234 | Bytes from @var{data} to @var{data} + @var{len} have been written |
| 235 | to the current inferior at @var{addr}. |
| 236 | @end deftypefun |
| 237 | |
| 238 | @deftypefun void before_prompt (const char *@var{current_prompt}) |
| 239 | Called before a top-level prompt is displayed. @var{current_prompt} is |
| 240 | the current top-level prompt. |
| 241 | @end deftypefun |
| 242 | |
| 243 | @deftypefun void gdb_datadir_changed (void) |
| 244 | Variable gdb_datadir has been set. The value may not necessarily change. |
| 245 | @end deftypefun |
| 246 | |
| 247 | @deftypefun void command_param_changed (const char *@var{param}, const char *@var{value}) |
| 248 | The parameter of some @code{set} commands in console are changed. This |
| 249 | method is called after a command @code{set @var{param} @var{value}}. |
| 250 | @var{param} is the parameter of @code{set} command, and @var{value} |
| 251 | is the value of changed parameter. |
| 252 | @end deftypefun |
| 253 | |
| 254 | @deftypefun void tsv_created (const char *@var{name}, LONGEST @var{value}) |
| 255 | The new trace state variable @var{name} is created with value |
| 256 | @var{value}. |
| 257 | @end deftypefun |
| 258 | |
| 259 | @deftypefun void tsv_deleted (const char *@var{name}) |
| 260 | The trace state variable @var{name} is deleted. If @var{name} is |
| 261 | @code{NULL}, all trace state variables are deleted. |
| 262 | @end deftypefun |
| 263 | |
| 264 | @deftypefun void test_notification (int @var{somearg}) |
| 265 | This observer is used for internal testing. Do not use. |
| 266 | See testsuite/gdb.gdb/observer.exp. |
| 267 | @end deftypefun |
| 268 | |