gdb/observer.c - gdb

Global variables defined

Data types defined

Functions defined

Source code

  1. /* GDB Notifications to Observers.

  3.    Copyright (C) 2003-2015 Free Software Foundation, Inc.

  5.    This file is part of GDB.

  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.

  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.

  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/>.  */

  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.

  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.

  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.

  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.

  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.  */

  52. #include "defs.h"
  53. #include "observer.h"
  54. #include "command.h"
  55. #include "gdbcmd.h"

  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. }

  65. /* The internal generic observer.  */

  67. ‌typedef void (generic_observer_notification_ftype) (const void *data,
  68.                                                     const void *args);

  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. };

  77. /* A list of observers, maintained by the subject.  A subject is
  78.    actually represented by its list of observers.  */

  80. ‌struct observer_list
  81. {
  82.   struct observer_list *next;
  83.   struct observer *observer;
  84. };

  86. /* Allocate a struct observer_list, intended to be used as a node
  87.    in the list of observers maintained by a subject.  */

  89. static struct observer_list *
  90. ‌xalloc_observer_list_node (void)
  91. {
  92.   struct observer_list *node = XNEW (struct observer_list);

  94.   node->observer = XNEW (struct observer);
  95.   return node;
  96. }

  98. /* The opposite of xalloc_observer_list_node, frees the memory for
  99.    the given node.  */

  101. static void
  102. ‌xfree_observer_list_node (struct observer_list *node)
  103. {
  104.   xfree (node->observer);
  105.   xfree (node);
  106. }

  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.  */

  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 ();

  119.   observer_list->next = *subject;
  120.   observer_list->observer->notify = notify;
  121.   observer_list->observer->data = data;
  122.   *subject = observer_list;

  124.   return observer_list->observer;
  125. }

  127. /* Remove the given OBSERVER from the SUBJECT.  Once detached, OBSERVER
  128.    should no longer be used, as it is no longer valid.  */

  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;

  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.     }

  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. }

  157. /* Send a notification to all the observers of SUBJECT.  ARGS is passed to
  158.    all observers as an argument to the notification callback.  */

  160. static void
  161. ‌generic_observer_notify (struct observer_list *subject, const void *args)
  162. {
  163.   struct observer_list *current_node = subject;

  165.   while (current_node != NULL)
  166.     {
  167.       (*current_node->observer->notify) (current_node->observer->data, args);
  168.       current_node = current_node->next;
  169.     }
  170. }


  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)!  */

  177. /* If we define these variables and functions as `static', the
  178.    compiler will optimize them out.  */

  180. ‌int observer_test_first_observer = 0;
  181. ‌int observer_test_second_observer = 0;
  182. ‌int observer_test_third_observer = 0;

  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);

  189. void
  190. ‌observer_test_first_notification_function (int arg)
  191. {
  192.   observer_test_first_observer++;
  193. }

  195. void
  196. ‌observer_test_second_notification_function (int arg)
  197. {
  198.   observer_test_second_observer++;
  199. }

  201. void
  202. ‌observer_test_third_notification_function (int arg)
  203. {
  204.   observer_test_third_observer++;
  205. }

  207. extern initialize_file_ftype _initialize_observer; /* -Wmissing-prototypes */

  209. void
  210. ‌_initialize_observer (void)
  211. {
  212.   add_setshow_zuinteger_cmd ("observer", class_maintenance,
  213.                              &observer_debug, _("\
  214. Set observer debugging."), _("\
  215. Show observer debugging."), _("\
  216. When non-zero, observer debugging is enabled."),
  217.                              NULL,
  218.                              show_observer_debug,
  219.                              &setdebuglist, &showdebuglist);
  220. }

  222. #include "observer.inc"