GDB (xrefs)

/tmp/gdb-8.1/gdb/observer.c
Go to the documentation of this file.
1 /* GDB Notifications to Observers.
2
3 Copyright (C) 2003-2018 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"
generic_observer_detach
static void generic_observer_detach(struct observer_list **subject, const struct observer *observer)
Definition: observer.c:131
observer_test_second_notification_function
void observer_test_second_notification_function(int arg)
Definition: observer.c:191
command.h
xfree
void xfree(void *)
cmd_list_element
Definition: cli-decode.h:46
warning
void warning(const char *fmt,...)
Definition: errors.c:26
observer.inc
_
#define _(String)
Definition: gdb_locale.h:35
ui_file
Definition: ui-file.h:26
defs.h
observer_test_third_notification_function
void observer_test_third_notification_function(int arg)
Definition: observer.c:197
generic_observer_notification_ftype
void() generic_observer_notification_ftype(const void *data, const void *args)
Definition: observer.c:67
XNEW
#define XNEW(T)
Definition: poison.h:109
observer.h
observer_test_first_observer
int observer_test_first_observer
Definition: observer.c:180
add_setshow_zuinteger_cmd
void add_setshow_zuinteger_cmd(const char *name, enum command_class theclass, unsigned int *var, const char *set_doc, const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, show_value_ftype *show_func, struct cmd_list_element **set_list, struct cmd_list_element **show_list)
Definition: cli-decode.c:792
observer_test_second_observer
int observer_test_second_observer
Definition: observer.c:181
_initialize_observer
void _initialize_observer(void)
Definition: observer.c:203
observer_test_first_notification_function
void observer_test_first_notification_function(int arg)
Definition: observer.c:185
fprintf_filtered
void fprintf_filtered(struct ui_file *stream, const char *format,...)
Definition: utils.c:2008
notify
mach_port_t notify
Definition: gnu-nat.c:1811
observer_list::observer
struct observer * observer
Definition: observer.c:83
observer_test_third_observer
int observer_test_third_observer
Definition: observer.c:182
observer_debug
static unsigned int observer_debug
Definition: observer.c:57
setdebuglist
struct cmd_list_element * setdebuglist
Definition: cli-cmds.c:153
observer_list
Definition: observer.c:80
observer
Definition: observer.c:70
value
Definition: value.c:169
observer_list::next
struct observer_list * next
Definition: observer.c:82
observer::data
void * data
Definition: observer.c:74
generic_observer_notify
static void generic_observer_notify(struct observer_list *subject, const void *args)
Definition: observer.c:161
showdebuglist
struct cmd_list_element * showdebuglist
Definition: cli-cmds.c:155
class_maintenance
Definition: command.h:43
xalloc_observer_list_node
static struct observer_list * xalloc_observer_list_node(void)
Definition: observer.c:90
gdbcmd.h
xfree_observer_list_node
static void xfree_observer_list_node(struct observer_list *node)
Definition: observer.c:102
generic_observer_attach
static struct observer * generic_observer_attach(struct observer_list **subject, generic_observer_notification_ftype *notify, void *data)
Definition: observer.c:113
show_observer_debug
static void show_observer_debug(struct ui_file *file, int from_tty, struct cmd_list_element *c, const char *value)
Definition: observer.c:59
observer::notify
generic_observer_notification_ftype * notify
Definition: observer.c:72