diff options
Diffstat (limited to 'gdb/doc/observer.texi')
| -rw-r--r-- | gdb/doc/observer.texi | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/gdb/doc/observer.texi b/gdb/doc/observer.texi new file mode 100644 index 00000000000..a967f3200e8 --- /dev/null +++ b/gdb/doc/observer.texi @@ -0,0 +1,64 @@ +@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 mechansim 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 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 @code{normal_stop} Notifications +@cindex @code{normal_stop} observer +@cindex notification about inferior execution stop + +@value{GDBN} will notify all @code{normal_stop} observers when the +inferior execution has just stopped, and all the associated internal +processing (such as breakpoint commands, annotations, etc) is about to +be performed before the @value{GDBN} prompt is returned to the user. + +The following interface is available to manage @code{normal_stop} +observers: + +@deftypefun extern struct observer *observer_attach_normal_stop (observer_normal_stop_ftype *@var{f}) +Attach the given @code{normal_stop} callback function @var{f} and +return the associated observer. +@end deftypefun + +@deftypefun extern void observer_detach_normal_stop (struct observer *@var{observer}); +Remove @var{observer} from the list of observers to be notified when +a @code{normal_stop} event occurs. +@end deftypefun + +@deftypefun extern void observer_notify_normal_stop (void); +Send a notification to all @code{normal_stop} observers. +@end deftypefun + + |