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