* 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.

4 files changed, 101 insertions, 2 deletions

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  <brobecker@gnat.com>
+
+	* 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  <cagney@redhat.com>
 
 	* 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 3366e1710e9..135278c2a95 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -41,7 +41,7 @@ Software Foundation raise funds for GNU development.''
 @page
 @tex
 \def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
-\xdef\manvers{\$Revision: 1.131 $}  % For use in headers, footers too
+\xdef\manvers{\$Revision: 1.132 $}  % For use in headers, footers too
 {\parskip=0pt
 \hfill Cygnus Solutions\par
 \hfill \manvers\par
@@ -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
+
+