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