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