gdb/observer.c

   1 /* GDB Notifications to Observers.
   2
   3    Copyright (C) 2003, 2004, 2007, 2008, 2009, 2010, 2011
   4    Free Software Foundation, Inc.
   5
   6    This file is part of GDB.
   7
   8    This program is free software; you can redistribute it and/or modify
   9    it under the terms of the GNU General Public License as published by
  10    the Free Software Foundation; either version 3 of the License, or
  11    (at your option) any later version.
  12
  13    This program is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16    GNU General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  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 #include "command.h"
  56 #include "gdbcmd.h"
  57
  58 static int observer_debug;
  59 static void
  60 show_observer_debug (struct ui_file *file, int from_tty,
  61                      struct cmd_list_element *c, const char *value)
  62 {
  63   fprintf_filtered (file, _("Observer debugging is %s.\n"), value);
  64 }
  65
  66 /* The internal generic observer.  */
  67
  68 typedef void (generic_observer_notification_ftype) (const void *data,
  69                                                     const void *args);
  70
  71 struct observer
  72 {
  73   generic_observer_notification_ftype *notify;
  74   /* No memory management needed for the following field for now.  */
  75   void *data;
  76 };
  77
  78 /* A list of observers, maintained by the subject.  A subject is
  79    actually represented by its list of observers.  */
  80
  81 struct observer_list
  82 {
  83   struct observer_list *next;
  84   struct observer *observer;
  85 };
  86
  87 /* Allocate a struct observer_list, intended to be used as a node
  88    in the list of observers maintained by a subject.  */
  89
  90 static struct observer_list *
  91 xalloc_observer_list_node (void)
  92 {
  93   struct observer_list *node = XMALLOC (struct observer_list);
  94
  95   node->observer = XMALLOC (struct observer);
  96   return node;
  97 }
  98
  99 /* The opposite of xalloc_observer_list_node, frees the memory for
 100    the given node.  */
 101
 102 static void
 103 xfree_observer_list_node (struct observer_list *node)
 104 {
 105   xfree (node->observer);
 106   xfree (node);
 107 }
 108
 109 /* Attach the callback NOTIFY to a SUBJECT.  The DATA is also stored,
 110    in order for the subject to provide it back to the observer during
 111    a notification.  */
 112
 113 static struct observer *
 114 generic_observer_attach (struct observer_list **subject,
 115                          generic_observer_notification_ftype * notify,
 116                          void *data)
 117 {
 118   struct observer_list *observer_list = xalloc_observer_list_node ();
 119
 120   observer_list->next = *subject;
 121   observer_list->observer->notify = notify;
 122   observer_list->observer->data = data;
 123   *subject = observer_list;
 124
 125   return observer_list->observer;
 126 }
 127
 128 /* Remove the given OBSERVER from the SUBJECT.  Once detached, OBSERVER
 129    should no longer be used, as it is no longer valid.  */
 130
 131 static void
 132 generic_observer_detach (struct observer_list **subject,
 133                          const struct observer *observer)
 134 {
 135   struct observer_list *previous_node = NULL;
 136   struct observer_list *current_node = *subject;
 137
 138   while (current_node != NULL)
 139     {
 140       if (current_node->observer == observer)
 141         {
 142           if (previous_node != NULL)
 143             previous_node->next = current_node->next;
 144           else
 145             *subject = current_node->next;
 146           xfree_observer_list_node (current_node);
 147           return;
 148         }
 149       previous_node = current_node;
 150       current_node = current_node->next;
 151     }
 152
 153   /* We should never reach this point.  However, this should not be
 154      a very serious error, so simply report a warning to the user.  */
 155   warning (_("Failed to detach observer"));
 156 }
 157
 158 /* Send a notification to all the observers of SUBJECT.  ARGS is passed to
 159    all observers as an argument to the notification callback.  */
 160
 161 static void
 162 generic_observer_notify (struct observer_list *subject, const void *args)
 163 {
 164   struct observer_list *current_node = subject;
 165
 166   while (current_node != NULL)
 167     {
 168       (*current_node->observer->notify) (current_node->observer->data, args);
 169       current_node = current_node->next;
 170     }
 171 }
 172
 173
 174 /* The following code is only used to unit-test the observers from our
 175    testsuite.  DO NOT USE IT within observer.c (or anywhere else for
 176    that matter)!  */
 177
 178 /* If we define these variables and functions as `static', the
 179    compiler will optimize them out.  */
 180
 181 int observer_test_first_observer = 0;
 182 int observer_test_second_observer = 0;
 183 int observer_test_third_observer = 0;
 184
 185 void
 186 observer_test_first_notification_function (int arg)
 187 {
 188   observer_test_first_observer++;
 189 }
 190
 191 void
 192 observer_test_second_notification_function (int arg)
 193 {
 194   observer_test_second_observer++;
 195 }
 196
 197 void
 198 observer_test_third_notification_function (int arg)
 199 {
 200   observer_test_third_observer++;
 201 }
 202
 203 extern initialize_file_ftype _initialize_observer; /* -Wmissing-prototypes */
 204
 205 void
 206 _initialize_observer (void)
 207 {
 208   add_setshow_zinteger_cmd ("observer", class_maintenance,
 209                             &observer_debug, _("\
 210 Set observer debugging."), _("\
 211 Show observer debugging."), _("\
 212 When non-zero, observer debugging is enabled."),
 213                             NULL,
 214                             show_observer_debug,
 215                             &setdebuglist, &showdebuglist);
 216 }
 217
 218 #include "observer.inc"