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" 219