gdb/observer.c

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