contrib/gdb/gdb/observer.c

   1 /* GDB Notifications to Observers.
   2    Copyright 2003 Free Software Foundation, Inc.
   3
   4    This file is part of GDB.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place - Suite 330,
  19    Boston, MA 02111-1307, USA.  */
  20
  21 /* An observer is an entity who is interested in being notified when GDB
  22    reaches certain states, or certain events occur in GDB. The entity being
  23    observed is called the Subject. To receive notifications, the observer
  24    attaches a callback to the subject. One subject can have several
  25    observers.
  26
  27    This file implements an internal generic low-level event notification
  28    mechanism based on the Observer paradigm described in the book "Design
  29    Patterns".  This generic event notification mechansim is then re-used
  30    to implement the exported high-level notification management routines
  31    for all possible notifications.
  32
  33    The current implementation of the generic observer provides support
  34    for contextual data. This contextual data is given to the subject
  35    when attaching the callback. In return, the subject will provide
  36    this contextual data back to the observer as a parameter of the
  37    callback.
  38
  39    FIXME: The current support for the contextual data is only partial,
  40    as it lacks a mechanism that would deallocate this data when the
  41    callback is detached. This is not a problem so far, as this contextual
  42    data is only used internally to hold a function pointer. Later on,
  43    if a certain observer needs to provide support for user-level
  44    contextual data, then the generic notification mechanism will need
  45    need to be enhanced to allow the observer to provide a routine to
  46    deallocate the data when attaching the callback.
  47
  48    This file is currently maintained by hand, but the long term plan
  49    if the number of different notifications starts growing is to create
  50    a new script (observer.sh) that would generate this file, and the
  51    associated documentation.  */
  52
  53 #include "defs.h"
  54 #include "observer.h"
  55
  56 /* The internal generic observer.  */
  57
  58 typedef void (generic_observer_notification_ftype) (const void *data,
  59                                                     const void *args);
  60
  61 struct observer
  62 {
  63   generic_observer_notification_ftype *notify;
  64   /* No memory management needed for the following field for now.  */
  65   void *data;
  66 };
  67
  68 /* A list of observers, maintained by the subject.  A subject is
  69    actually represented by its list of observers.  */
  70
  71 struct observer_list
  72 {
  73   struct observer_list *next;
  74   struct observer *observer;
  75 };
  76
  77 /* Allocate a struct observer_list, intended to be used as a node
  78    in the list of observers maintained by a subject.  */
  79
  80 static struct observer_list *
  81 xalloc_observer_list_node (void)
  82 {
  83   struct observer_list *node = XMALLOC (struct observer_list);
  84   node->observer = XMALLOC (struct observer);
  85   return node;
  86 }
  87
  88 /* The opposite of xalloc_observer_list_node, frees the memory for
  89    the given node.  */
  90
  91 static void
  92 xfree_observer_list_node (struct observer_list *node)
  93 {
  94   xfree (node->observer);
  95   xfree (node);
  96 }
  97
  98 /* Attach the callback NOTIFY to a SUBJECT.  The DATA is also stored,
  99    in order for the subject to provide it back to the observer during
 100    a notification.  */
 101
 102 static struct observer *
 103 generic_observer_attach (struct observer_list **subject,
 104                          generic_observer_notification_ftype * notify,
 105                          void *data)
 106 {
 107   struct observer_list *observer_list = xalloc_observer_list_node ();
 108
 109   observer_list->next = *subject;
 110   observer_list->observer->notify = notify;
 111   observer_list->observer->data = data;
 112   *subject = observer_list;
 113
 114   return observer_list->observer;
 115 }
 116
 117 /* Remove the given OBSERVER from the SUBJECT.  Once detached, OBSERVER
 118    should no longer be used, as it is no longer valid.  */
 119
 120 static void
 121 generic_observer_detach (struct observer_list **subject,
 122                          const struct observer *observer)
 123 {
 124   struct observer_list *previous_node = NULL;
 125   struct observer_list *current_node = *subject;
 126
 127   while (current_node != NULL)
 128     {
 129       if (current_node->observer == observer)
 130         {
 131           if (previous_node != NULL)
 132             previous_node->next = current_node->next;
 133           else
 134             *subject = current_node->next;
 135           xfree_observer_list_node (current_node);
 136           return;
 137         }
 138       previous_node = current_node;
 139       current_node = current_node->next;
 140     }
 141
 142   /* We should never reach this point.  However, this should not be
 143      a very serious error, so simply report a warning to the user.  */
 144   warning ("Failed to detach observer");
 145 }
 146
 147 /* Send a notification to all the observers of SUBJECT.  ARGS is passed to
 148    all observers as an argument to the notification callback.  */
 149
 150 static void
 151 generic_observer_notify (struct observer_list *subject, const void *args)
 152 {
 153   struct observer_list *current_node = subject;
 154
 155   while (current_node != NULL)
 156     {
 157       (*current_node->observer->notify) (current_node->observer->data, args);
 158       current_node = current_node->next;
 159     }
 160 }
 161
 162 /* normal_stop notifications.  */
 163
 164 static struct observer_list *normal_stop_subject = NULL;
 165
 166 static void
 167 observer_normal_stop_notification_stub (const void *data,
 168                                         const void *unused_args)
 169 {
 170   observer_normal_stop_ftype *notify = (observer_normal_stop_ftype *) data;
 171   (*notify) ();
 172 }
 173
 174 struct observer *
 175 observer_attach_normal_stop (observer_normal_stop_ftype *f)
 176 {
 177   return generic_observer_attach (&normal_stop_subject,
 178                                   &observer_normal_stop_notification_stub,
 179                                   (void *) f);
 180 }
 181
 182 void
 183 observer_detach_normal_stop (struct observer *observer)
 184 {
 185   generic_observer_detach (&normal_stop_subject, observer);
 186 }
 187
 188 void
 189 observer_notify_normal_stop (void)
 190 {
 191   generic_observer_notify (normal_stop_subject, NULL);
 192 }
 193
 194 /* The following code is only used to unit-test the observers from our
 195    testsuite.  DO NOT USE IT within observer.c (or anywhere else for
 196    that matter)!  */
 197
 198 /* If we define these variables and functions as `static', the
 199    compiler will optimize them out.  */
 200
 201 int observer_test_first_observer = 0;
 202 int observer_test_second_observer = 0;
 203 int observer_test_third_observer = 0;
 204
 205 void
 206 observer_test_first_notification_function (void)
 207 {
 208   observer_test_first_observer++;
 209 }
 210
 211 void
 212 observer_test_second_notification_function (void)
 213 {
 214   observer_test_second_observer++;
 215 }
 216
 217 void
 218 observer_test_third_notification_function (void)
 219 {
 220   observer_test_third_observer++;
 221 }
 222