| @c -*-texinfo-*- |
| @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} occures, 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: |
| |
| @c note: all events must take at least one parameter. |
| |
| @deftypefun void normal_stop (struct bpstats *@var{bs}) |
| The inferior has stopped for real. |
| @end deftypefun |
| |
| @deftypefun void target_changed (struct target_ops *@var{target}) |
| The target's register contents have changed. |
| @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 |