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