From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16015 invoked by alias); 10 Mar 2003 19:59:58 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 16003 invoked from network); 10 Mar 2003 19:59:57 -0000 Received: from unknown (HELO takamaka.act-europe.fr) (209.53.16.215) by 172.16.49.205 with SMTP; 10 Mar 2003 19:59:57 -0000 Received: by takamaka.act-europe.fr (Postfix, from userid 507) id 42866D34B6; Mon, 10 Mar 2003 11:59:59 -0800 (PST) Date: Mon, 10 Mar 2003 19:59:00 -0000 From: Joel Brobecker To: gdb-patches@sources.redhat.com Subject: [RFA/doco] Add documentation for observer.[hc] (2nd version) Message-ID: <20030310195959.GE972@gnat.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="J2SCkAp4GZ/dPZZf" Content-Disposition: inline User-Agent: Mutt/1.4i X-SW-Source: 2003-03/txt/msg00232.txt.bz2 --J2SCkAp4GZ/dPZZf Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-length: 445 Here is a second shot at the observer documentation. Hopefully, I addressed all issues. 2003-03-10 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. Thanks, -- Joel --J2SCkAp4GZ/dPZZf Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="gdbint.texinfo.diff" Content-length: 2645 Index: gdbint.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v retrieving revision 1.127 diff -c -3 -r1.127 gdbint.texinfo *** gdbint.texinfo 5 Mar 2003 23:14:18 -0000 1.127 --- gdbint.texinfo 10 Mar 2003 19:54:09 -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 *************** *** 6577,6582 **** --- 6601,6607 ---- @end table + @include observer.texi @include fdl.texi @node Index Index: Makefile.in =================================================================== RCS file: /cvs/src/src/gdb/doc/Makefile.in,v retrieving revision 1.26 diff -c -3 -r1.26 Makefile.in *** Makefile.in 3 Mar 2003 03:59:16 -0000 1.26 --- Makefile.in 10 Mar 2003 19:54:01 -0000 *************** *** 114,120 **** # Internals Manual GDBINT_DOC_SOURCE_INCLUDES = \ ! $(srcdir)/fdl.texi GDBINT_DOC_BUILD_INCLUDES = \ gdb-cfg.texi \ GDBvn.texi --- 114,121 ---- # Internals Manual GDBINT_DOC_SOURCE_INCLUDES = \ ! $(srcdir)/fdl.texi \ ! $(srcdir)/observer.texi GDBINT_DOC_BUILD_INCLUDES = \ gdb-cfg.texi \ GDBvn.texi --J2SCkAp4GZ/dPZZf Content-Type: application/x-texinfo Content-Disposition: attachment; filename="observer.texi" Content-Transfer-Encoding: quoted-printable Content-length: 2793 @c -*-texinfo-*-=0A= @node GDB Observers=0A= @appendix @value{GDBN} Currently available observers=0A= =0A= @section Implementation rationale=0A= @cindex observers implementation rationale=0A= =0A= An observer is an entity who is interested in being notified when GDB=0A= reaches certain states, or certain events occur in GDB. The entity being=0A= observed is called the Subject. To receive notifications, the observer=0A= attaches a callback to the subject. One subject can have several=0A= observers.=0A= =0A= @file{observer.c} implements an internal generic low-level event=0A= notification mechanism. This generic event notification mechansim is=0A= then re-used to implement the exported high-level notification=0A= management routines for all possible notifications.=0A= =0A= The current implementation of the generic observer provides support=0A= for contextual data. This contextual data is given to the subject=0A= when attaching the callback. In return, the subject will provide=0A= this contextual data back to the observer as a parameter of the=0A= callback.=0A= =0A= Note that the current support for the contextual data is only partial,=0A= as it lacks a mechanism that would deallocate this data when the=0A= callback is detached. This is not a problem so far, as this contextual=0A= data is only used internally to hold a function pointer. Later on, if a=0A= certain observer needs to provide support for user-level contextual=0A= data, then the generic notification mechanism will need need to be=0A= enhanced to allow the observer to provide a routine to deallocate the=0A= data when attaching the callback.=0A= =0A= @section @code{normal_stop} Notifications=0A= @cindex @code{normal_stop} observer=0A= @cindex notification about inferior execution stop=0A= =0A= @value{GDBN} will notify all @code{normal_stop} observers when the=0A= inferior execution has just stopped, and all the associated internal=0A= processing (such as breakpoint commands, annotations, etc) is about to=0A= be performed before the @value{GDBN} prompt is returned to the user.=0A= =0A= The following interface is available to manage @code{normal_stop}=0A= observers:=0A= =0A= @deftypefun extern struct observer *observer_attach_normal_stop (observer_n= ormal_stop_ftype *@var{f})=0A= Attach the given @code{normal_stop} callback function @var{f} and=0A= return the associated observer.=0A= @end deftypefun=0A= =0A= @deftypefun extern void observer_detach_normal_stop (struct observer *@var{= observer});=0A= Remove @var{observer} from the list of observers to be notified when=0A= a @code{normal_stop} event occurs.=0A= @end deftypefun=0A= =0A= @deftypefun extern void observer_notify_normal_stop (void);=0A= Send a notification to all @code{normal_stop} observers.=0A= @end deftypefun=0A= =0A= =0A= --J2SCkAp4GZ/dPZZf--