GDB (xrefs)
/tmp/gdb-7.10/gdb/observer.c
Go to the documentation of this file.
1 /* GDB Notifications to Observers.
2 
3  Copyright (C) 2003-2015 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 {
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 
81 {
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 *
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
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 *
115  void *data)
116 {
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
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 
183 
184 /* Provide prototypes to silence -Wmissing-prototypes. */
185 extern void observer_test_first_notification_function (int arg);
186 extern void observer_test_second_notification_function (int arg);
187 extern void observer_test_third_notification_function (int arg);
188 
189 void
191 {
193 }
194 
195 void
197 {
199 }
200 
201 void
203 {
205 }
206 
207 extern initialize_file_ftype _initialize_observer; /* -Wmissing-prototypes */
208 
209 void
211 {
213  &observer_debug, _("\
214 Set observer debugging."), _("\
215 Show observer debugging."), _("\
216 When non-zero, observer debugging is enabled."),
217  NULL,
220 }
221 
222 #include "observer.inc"
static void generic_observer_detach(struct observer_list **subject, const struct observer *observer)
Definition: observer.c:131
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_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:763
void observer_test_second_notification_function(int arg)
Definition: observer.c:196
void xfree(void *)
Definition: common-utils.c:97
void warning(const char *fmt,...)
Definition: errors.c:26
initialize_file_ftype _initialize_observer
#define _(String)
Definition: gdb_locale.h:40
void observer_test_third_notification_function(int arg)
Definition: observer.c:202
int observer_test_first_observer
Definition: observer.c:180
int observer_test_second_observer
Definition: observer.c:181
void initialize_file_ftype(void)
Definition: defs.h:281
void observer_test_first_notification_function(int arg)
Definition: observer.c:190
void fprintf_filtered(struct ui_file *stream, const char *format,...)
Definition: utils.c:2351
mach_port_t notify
Definition: gnu-nat.c:1805
struct observer * observer
Definition: observer.c:83
int observer_test_third_observer
Definition: observer.c:182
static unsigned int observer_debug
Definition: observer.c:57
struct cmd_list_element * setdebuglist
Definition: cli-cmds.c:173
Definition: value.c:172
struct observer_list * next
Definition: observer.c:82
void( generic_observer_notification_ftype)(const void *data, const void *args)
Definition: observer.c:67
void * data
Definition: observer.c:74
static void generic_observer_notify(struct observer_list *subject, const void *args)
Definition: observer.c:161
struct cmd_list_element * showdebuglist
Definition: cli-cmds.c:175
static struct observer_list * xalloc_observer_list_node(void)
Definition: observer.c:90
static void xfree_observer_list_node(struct observer_list *node)
Definition: observer.c:102
static struct observer * generic_observer_attach(struct observer_list **subject, generic_observer_notification_ftype *notify, void *data)
Definition: observer.c:113
static void show_observer_debug(struct ui_file *file, int from_tty, struct cmd_list_element *c, const char *value)
Definition: observer.c:59
generic_observer_notification_ftype * notify
Definition: observer.c:72