1 /* GDB Notifications to Observers. 2 3 Copyright (C) 2003-2004, 2007-2012 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 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 = XMALLOC (struct observer_list); 93 94 node->observer = XMALLOC (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 extern initialize_file_ftype _initialize_observer; /* -Wmissing-prototypes */ 203 204 void 205 _initialize_observer (void) 206 { 207 add_setshow_zinteger_cmd ("observer", class_maintenance, 208 &observer_debug, _("\ 209 Set observer debugging."), _("\ 210 Show observer debugging."), _("\ 211 When non-zero, observer debugging is enabled."), 212 NULL, 213 show_observer_debug, 214 &setdebuglist, &showdebuglist); 215 } 216 217 #include "observer.inc" 218