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