| @c -*-texinfo-*- |
| |
| @c This file is part of the GDB manual. |
| @c |
| @c Copyright (C) 2003, 2004, 2005, 2006, 2008 |
| @c Free Software Foundation, Inc. |
| @c |
| @c See the file gdbint.texinfo for copying conditions. |
| @c |
| @c Also, the @deftypefun lines from this file are processed into a |
| @c header file during the GDB build process. Permission is granted |
| @c to redistribute and/or modify those lines under the terms of the |
| @c GNU General Public License as published by the Free Software |
| @c Foundation; either version 2 of the License, or (at your option) |
| @c any later version. |
| |
| @node GDB Observers |
| @appendix @value{GDBN} Currently available observers |
| |
| @section Implementation rationale |
| @cindex observers implementation rationale |
| |
| An @dfn{observer} is an entity which is interested in being notified |
| when GDB reaches certain states, or certain events occur in GDB. |
| The entity being observed is called the @dfn{subject}. To receive |
| notifications, the observer attaches a callback to the subject. |
| One subject can have several observers. |
| |
| @file{observer.c} implements an internal generic low-level event |
| notification mechanism. This generic event notification mechanism is |
| then re-used to implement the exported high-level notification |
| management routines for all possible notifications. |
| |
| The current implementation of the generic observer provides support |
| for contextual data. This contextual data is given to the subject |
| when attaching the callback. In return, the subject will provide |
| this contextual data back to the observer as a parameter of the |
| callback. |
| |
| Note that the current support for the contextual data is only partial, |
| as it lacks a mechanism that would deallocate this data when the |
| callback is detached. This is not a problem so far, as this contextual |
| data is only used internally to hold a function pointer. Later on, if |
| a certain observer needs to provide support for user-level contextual |
| data, then the generic notification mechanism will need to be |
| enhanced to allow the observer to provide a routine to deallocate the |
| data when attaching the callback. |
| |
| The observer implementation is also currently not reentrant. |
| In particular, it is therefore not possible to call the attach |
| or detach routines during a notification. |
| |
| @section Debugging |
| Observer notifications can be traced using the command @samp{set debug |
| observer 1} (@pxref{Debugging Output, , Optional messages about |
| internal happenings, gdb, Debugging with @var{GDBN}}). |
| |
| @section @code{normal_stop} Notifications |
| @cindex @code{normal_stop} observer |
| @cindex notification about inferior execution stop |
| |
| @value{GDBN} notifies all @code{normal_stop} observers when the |
| inferior execution has just stopped, the associated messages and |
| annotations have been printed, and the control is about to be returned |
| to the user. |
| |
| Note that the @code{normal_stop} notification is not emitted when |
| the execution stops due to a breakpoint, and this breakpoint has |
| a condition that is not met. If the breakpoint has any associated |
| commands list, the commands are executed after the notification |
| is emitted. |
| |
| The following interfaces are available to manage observers: |
| |
| @deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f}) |
| Using the function @var{f}, create an observer that is notified when |
| ever @var{event} occurs, return the observer. |
| @end deftypefun |
| |
| @deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer}); |
| Remove @var{observer} from the list of observers to be notified when |
| @var{event} occurs. |
| @end deftypefun |
| |
| @deftypefun extern void observer_notify_@var{event} (void); |
| Send a notification to all @var{event} observers. |
| @end deftypefun |
| |
| The following observable events are defined: |
| |
| @deftypefun void normal_stop (struct bpstats *@var{bs}, int @var{print_frame}) |
| The inferior has stopped for real. The @var{bs} argument describes |
| the breakpoints were are stopped at, if any. Second argument |
| @var{print_frame} non-zero means display the location where the |
| inferior has stopped. |
| @end deftypefun |
| |
| @deftypefun void target_changed (struct target_ops *@var{target}) |
| The target's register contents have changed. |
| @end deftypefun |
| |
| @deftypefun void executable_changed (void) |
| The executable being debugged by GDB has changed: The user decided |
| to debug a different program, or the program he was debugging has |
| been modified since being loaded by the debugger (by being recompiled, |
| for instance). |
| @end deftypefun |
| |
| @deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty}) |
| @value{GDBN} has just connected to an inferior. For @samp{run}, |
| @value{GDBN} calls this observer while the inferior is still stopped |
| at the entry-point instruction. For @samp{attach} and @samp{core}, |
| @value{GDBN} calls this observer immediately after connecting to the |
| inferior, and before any information on the inferior has been printed. |
| @end deftypefun |
| |
| @deftypefun void solib_loaded (struct so_list *@var{solib}) |
| The shared library specified by @var{solib} has been loaded. Note that |
| when @value{GDBN} calls this observer, the library's symbols probably |
| haven't been loaded yet. |
| @end deftypefun |
| |
| @deftypefun void solib_unloaded (struct so_list *@var{solib}) |
| The shared library specified by @var{solib} has been unloaded. |
| @end deftypefun |
| |
| @deftypefun void new_objfile (struct objfile *@var{objfile}) |
| The symbol file specified by @var{objfile} has been loaded. |
| Called with @var{objfile} equal to @code{NULL} to indicate |
| previously loaded symbol table data has now been invalidated. |
| @end deftypefun |
| |
| @deftypefun void new_thread (struct thread_info *@var{t}) |
| The thread specified by @var{t} has been created. |
| @end deftypefun |
| |
| @deftypefun void thread_exit (struct thread_info *@var{t}, int @var{silent}) |
| The thread specified by @var{t} has exited. The @var{silent} argument |
| indicates that @value{GDBN} is removing the thread from its tables |
| without wanting to notify the user about it. |
| @end deftypefun |
| |
| @deftypefun void thread_stop_requested (ptid_t @var{ptid}) |
| An explicit stop request was issued to @var{ptid}. If @var{ptid} |
| equals @var{minus_one_ptid}, the request applied to all threads. If |
| @code{ptid_is_pid(ptid)} returns true, the request applied to all |
| threads of the process pointed at by @var{ptid}. Otherwise, the |
| request applied to the single thread pointed at by @var{ptid}. |
| @end deftypefun |
| |
| @deftypefun void target_resumed (ptid_t @var{ptid}) |
| The target was resumed. The @var{ptid} parameter specifies which |
| thread was resume, and may be RESUME_ALL if all threads are resumed. |
| @end deftypefun |
| |
| @deftypefun void about_to_proceed (void) |
| The target is about to be proceeded. |
| @end deftypefun |
| |
| @deftypefun void breakpoint_created (int @var{bpnum}) |
| A new breakpoint has been created. The argument @var{bpnum} is the |
| number of the newly-created breakpoint. |
| @end deftypefun |
| |
| @deftypefun void breakpoint_deleted (int @var{bpnum}) |
| A breakpoint has been destroyed. The argument @var{bpnum} is the |
| number of the newly-destroyed breakpoint. |
| @end deftypefun |
| |
| @deftypefun void breakpoint_modified (int @var{bpnum}) |
| A breakpoint has been modified in some way. The argument @var{bpnum} |
| is the number of the modified breakpoint. |
| @end deftypefun |
| |
| @deftypefun void tracepoint_created (int @var{tpnum}) |
| A new tracepoint has been created. The argument @var{tpnum} is the |
| number of the newly-created tracepoint. |
| @end deftypefun |
| |
| @deftypefun void tracepoint_deleted (int @var{tpnum}) |
| A tracepoint has been destroyed. The argument @var{tpnum} is the |
| number of the newly-destroyed tracepoint. |
| @end deftypefun |
| |
| @deftypefun void tracepoint_modified (int @var{tpnum}) |
| A tracepoint has been modified in some way. The argument @var{tpnum} |
| is the number of the modified tracepoint. |
| @end deftypefun |
| |
| @deftypefun void architecture_changed (struct gdbarch *@var{newarch}) |
| The current architecture has changed. The argument @var{newarch} is |
| a pointer to the new architecture. |
| @end deftypefun |
| |
| @deftypefun void thread_ptid_changed (ptid_t @var{old_ptid}, ptid_t @var{new_ptid}) |
| The thread's ptid has changed. The @var{old_ptid} parameter specifies |
| the old value, and @var{new_ptid} specifies the new value. |
| @end deftypefun |
| |
| @deftypefun void new_inferior (int @var{pid}) |
| @value{GDBN} has attached to a new inferior identified by @var{pid}. |
| @end deftypefun |
| |
| @deftypefun void inferior_exit (int @var{pid}) |
| Either @value{GDBN} detached from the inferior, or the inferior |
| exited. The argument @var{pid} identifies the inferior. |
| @end deftypefun |
| |
| @deftypefun void test_notification (int @var{somearg}) |
| This observer is used for internal testing. Do not use. |
| See testsuite/gdb.gdb/observer.exp. |
| @end deftypefun |
| |