From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 21765 invoked by alias); 17 Mar 2003 07:04:59 -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 21336 invoked from network); 17 Mar 2003 07:04:54 -0000 Received: from unknown (HELO takamaka.act-europe.fr) (142.179.108.108) by sources.redhat.com with SMTP; 17 Mar 2003 07:04:54 -0000 Received: by takamaka.act-europe.fr (Postfix, from userid 507) id E61D8D34B8; Sun, 16 Mar 2003 23:04:56 -0800 (PST) Date: Mon, 17 Mar 2003 07:04:00 -0000 From: Joel Brobecker To: Eli Zaretskii Cc: gdb-patches@sources.redhat.com Subject: Re: [RFA/doco] Add documentation for observer.[hc] (2nd version) Message-ID: <20030317070456.GD16507@gnat.com> References: <20030310195959.GE972@gnat.com> <2593-Sun16Mar2003195803+0200-eliz@elta.co.il> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="OXfL5xGRrasGEqWY" Content-Disposition: inline In-Reply-To: <2593-Sun16Mar2003195803+0200-eliz@elta.co.il> User-Agent: Mutt/1.4i X-SW-Source: 2003-03/txt/msg00355.txt.bz2 --OXfL5xGRrasGEqWY Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-length: 1118 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 * 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 --OXfL5xGRrasGEqWY Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="gdbint.texinfo.diff" Content-length: 2004 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 --OXfL5xGRrasGEqWY Content-Type: application/x-texinfo Content-Disposition: attachment; filename="observer.texi" Content-Transfer-Encoding: quoted-printable Content-length: 2995 @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 @dfn{observer} is an entity which is interested in being notified=0A= when GDB reaches certain states, or certain events occur in GDB.=0A= The entity being observed is called the @dfn{subject}. To receive=0A= notifications, the observer attaches a callback to the subject.=0A= One subject can have several 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=0A= a 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= The observer implementation is also currently not reentrant.=0A= In particular, it is therefore not possible to call the attach=0A= or detach routines during a notification.=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= --OXfL5xGRrasGEqWY--