Re: [RFA/doco] Add documentation for observer.[hc] (2nd version)

[Joel Brobecker <brobecker@gnat.com>]

[-- Attachment #1: Type: text/plain, Size: 1118 bytes --]

Eli, thanks again for reviewing these doco changes.

> > An observer is an entity who is interested in being notified when GDB
> 
> When you introduce a new term, such as "observer" in the above text,
> it is best to put it into @dfn, like this:
> 
>  An @dfn{observer} is an entity who is interested in being notified when GDB

Makes sense, fixed.

> (btw, it should be "whcih", not "who").

Fixed.

> Same here:
> 
>   The entity being observed is called @dfn{the Subject}.
> 
> (Btw, is it really necessary to start "Subject" with a capital S?)

@dfn added, and capital S replaced.

I also realized that I forgot to mention that the current implementation
of the observer is not reentrant. So I added a paragraph to that
effect.

Here is the diff + ChangeLog again.

2003-03-10  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.

-- 
Joel

[-- Attachment #2: gdbint.texinfo.diff --]
[-- Type: text/plain, Size: 2004 bytes --]

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.128
diff -c -3 -r1.128 gdbint.texinfo
*** gdbint.texinfo	10 Mar 2003 15:28:41 -0000	1.128
--- gdbint.texinfo	17 Mar 2003 06:59:37 -0000
***************
*** 94,99 ****
--- 94,100 ----
  * Testsuite::
  * Hints::
  
+ * GDB Observers::  @value{GDBN} Currently available observers
  * GNU Free Documentation License::  The license for this documentation
  * Index::
  @end menu
***************
*** 696,701 ****
--- 697,725 ----
  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
***************
*** 6597,6602 ****
--- 6621,6627 ----
  
  @end table
  
+ @include observer.texi
  @include fdl.texi
  
  @node Index

[-- Attachment #3: observer.texi --]
[-- Type: application/x-texinfo, Size: 2799 bytes --]