From: Joel Brobecker Date: Tue, 18 Mar 2003 17:44:23 +0000 (+0000) Subject: * gdbint.texinfo (Algorithms): Add new section describing the X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=bcd7e15f07189331ac97875099d78409917ec8f4;p=binutils-gdb.git * gdbint.texinfo (Algorithms): Add new section describing the Observer paradigm. (Top): Add menu entry to new observer appendix. * observer.texi: New file. * Makefile.in (GDBINT_DOC_SOURCE_INCLUDES): Add dependency on new observer.texi file. --- diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 90399ac88f1..9ae3d3a8bbe 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,12 @@ +2003-03-18 J. Brobecker + + * gdbint.texinfo (Algorithms): Add new section describing the + Observer paradigm. + (Top): Add menu entry to new observer appendix. + * observer.texi: New file. + * Makefile.in (GDBINT_DOC_SOURCE_INCLUDES): Add dependency on + new observer.texi file. + 2003-03-17 Andrew Cagney * gdb.texinfo (DATE): Delete. Remove date from titles. Mention diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index 1d5ad3e271c..db74889328c 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -114,7 +114,8 @@ GDB_DOC_FILES = \ # Internals Manual GDBINT_DOC_SOURCE_INCLUDES = \ - $(srcdir)/fdl.texi + $(srcdir)/fdl.texi \ + $(srcdir)/observer.texi GDBINT_DOC_BUILD_INCLUDES = \ gdb-cfg.texi \ GDBvn.texi diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 186d9e7308c..2abfe34a013 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -94,6 +94,7 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets. * Testsuite:: * Hints:: +* GDB Observers:: @value{GDBN} Currently available observers * GNU Free Documentation License:: The license for this documentation * Index:: @end menu @@ -696,6 +697,29 @@ watchpoints might interfere with the underlying OS and are probably unavailable in many platforms. @end enumerate +@section Observing changes in @value{GDBN} internals +@cindex observer pattern interface +@cindex notifications about changes in internals + +In order to function properly, several modules need to be notified when +some changes occur in the @value{GDBN} internals. Traditionally, these +modules have relied on several paradigms, the most common ones being +hooks and gdb-events. Unfortunately, none of these paradigms was +versatile enough to become the standard notification mechanism in +@value{GDBN}. The fact that they only supported one ``client'' was also +a strong limitation. + +A new paradigm, based on the Observer pattern of the @cite{Design +Patterns} book, has therefore been implemented. The goal was to provide +a new interface overcoming the issues with the notification mechanisms +previously available. This new interface needed to be strongly typed, +easy to extend, and versatile enough to be used as the standard +interface when adding new notifications. + +See @ref{GDB Observers} for a brief description of the observers +currently implemented in GDB. The rationale for the current +implementation is also briefly discussed. + @node User Interface @chapter User Interface @@ -6595,6 +6619,7 @@ is so old that it has never been converted to use BFD. Now that's old! @end table +@include observer.texi @include fdl.texi @node Index 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 + +