| 1 | @c -*-texinfo-*- |
| 2 | |
| 3 | @c This file is part of the GDB manual. |
| 4 | @c |
| 5 | @c Copyright (C) 2003, 2004, 2005, 2006 |
| 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 2 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 | |
| 23 | An @dfn{observer} is an entity which is interested in being notified |
| 24 | when GDB reaches certain states, or certain events occur in GDB. |
| 25 | The entity being observed is called the @dfn{subject}. To receive |
| 26 | notifications, the observer attaches a callback to the subject. |
| 27 | One subject can have several observers. |
| 28 | |
| 29 | @file{observer.c} implements an internal generic low-level event |
| 30 | notification mechanism. This generic event notification mechanism is |
| 31 | then re-used to implement the exported high-level notification |
| 32 | management routines for all possible notifications. |
| 33 | |
| 34 | The current implementation of the generic observer provides support |
| 35 | for contextual data. This contextual data is given to the subject |
| 36 | when attaching the callback. In return, the subject will provide |
| 37 | this contextual data back to the observer as a parameter of the |
| 38 | callback. |
| 39 | |
| 40 | Note that the current support for the contextual data is only partial, |
| 41 | as it lacks a mechanism that would deallocate this data when the |
| 42 | callback is detached. This is not a problem so far, as this contextual |
| 43 | data is only used internally to hold a function pointer. Later on, if |
| 44 | a certain observer needs to provide support for user-level contextual |
| 45 | data, then the generic notification mechanism will need to be |
| 46 | enhanced to allow the observer to provide a routine to deallocate the |
| 47 | data when attaching the callback. |
| 48 | |
| 49 | The observer implementation is also currently not reentrant. |
| 50 | In particular, it is therefore not possible to call the attach |
| 51 | or detach routines during a notification. |
| 52 | |
| 53 | @section Debugging |
| 54 | Observer notifications can be traced using the command @samp{set debug |
| 55 | observer 1} (@pxref{Debugging Output, , Optional messages about |
| 56 | internal 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 |
| 63 | inferior execution has just stopped, the associated messages and |
| 64 | annotations have been printed, and the control is about to be returned |
| 65 | to the user. |
| 66 | |
| 67 | Note that the @code{normal_stop} notification is not emitted when |
| 68 | the execution stops due to a breakpoint, and this breakpoint has |
| 69 | a condition that is not met. If the breakpoint has any associated |
| 70 | commands list, the commands are executed after the notification |
| 71 | is emitted. |
| 72 | |
| 73 | The following interfaces are available to manage observers: |
| 74 | |
| 75 | @deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f}) |
| 76 | Using the function @var{f}, create an observer that is notified when |
| 77 | ever @var{event} occurs, return the observer. |
| 78 | @end deftypefun |
| 79 | |
| 80 | @deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer}); |
| 81 | Remove @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); |
| 86 | Send a notification to all @var{event} observers. |
| 87 | @end deftypefun |
| 88 | |
| 89 | The following observable events are defined: |
| 90 | |
| 91 | @c note: all events must take at least one parameter. |
| 92 | |
| 93 | @deftypefun void normal_stop (struct bpstats *@var{bs}) |
| 94 | The inferior has stopped for real. |
| 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 *@var{unused_args}) |
| 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 solib_loaded (struct so_list *@var{solib}) |
| 117 | The shared library specified by @var{solib} has been loaded. Note that |
| 118 | when @value{GDBN} calls this observer, the library's symbols probably |
| 119 | haven't been loaded yet. |
| 120 | @end deftypefun |
| 121 | |
| 122 | @deftypefun void solib_unloaded (struct so_list *@var{solib}) |
| 123 | The shared library specified by @var{solib} has been unloaded. |
| 124 | @end deftypefun |
| 125 | |
| 126 | @deftypefun void new_objfile (struct objfile *@var{objfile}) |
| 127 | The symbol file specified by @var{objfile} has been loaded. |
| 128 | Called with @var{objfile} equal to @code{NULL} to indicate |
| 129 | previously loaded symbol table data has now been invalidated. |
| 130 | @end deftypefun |
| 131 | |
| 132 | @deftypefun void new_thread (struct thread_info *@var{t}) |
| 133 | The thread specified by @var{t} has been created. |
| 134 | @end deftypefun |
| 135 | |
| 136 | @deftypefun void thread_exit (struct thread_info *@var{t}) |
| 137 | The thread specified by @var{t} has exited. |
| 138 | @end deftypefun |
| 139 | |
| 140 | @deftypefun void target_resumed (ptid_t @var{ptid}) |
| 141 | The target was resumed. The @var{ptid} parameter specifies which |
| 142 | thread was resume, and may be RESUME_ALL if all threads are resumed. |
| 143 | @end deftypefun |
| 144 | |