gdb/observer.c

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