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