gdb/registry.h

   1 /* Macros for general registry objects.
   2
   3    Copyright (C) 2011-2013 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 #ifndef REGISTRY_H
  21 #define REGISTRY_H
  22
  23 /* The macros here implement a template type and functions for
  24    associating some user data with a container object.
  25
  26    A registry is associated with a struct tag name.  To attach a
  27    registry to a structure, use DEFINE_REGISTRY.  This takes the
  28    structure tag and an access method as arguments.  In the usual
  29    case, where the registry fields appear directly in the struct, you
  30    can use the 'REGISTRY_FIELDS' macro to declare the fields in the
  31    struct definition, and you can pass 'REGISTRY_ACCESS_FIELD' as the
  32    access argument to DEFINE_REGISTRY.  In other cases, use
  33    REGISTRY_FIELDS to define the fields in the appropriate spot, and
  34    then define your own accessor to find the registry field structure
  35    given an instance of your type.
  36
  37    The API user requests a key from a registry during gdb
  38    initialization.  Later this key can be used to associate some
  39    module-specific data with a specific container object.
  40
  41    The exported API is best used via the wrapper macros:
  42
  43    - register_TAG_data(TAG)
  44    Get a new key for the container type TAG.
  45
  46    - register_TAG_data_with_cleanup(TAG, SAVE, FREE)
  47    Get a new key for the container type TAG.
  48    SAVE and FREE are defined as void (*) (struct TAG *, void *)
  49    When the container is destroyed, first all registered SAVE
  50    functions are called.
  51    Then all FREE functions are called.
  52    Either or both may be NULL.
  53
  54    - clear_TAG_data(TAG, OBJECT)
  55    Clear all the data associated with OBJECT.  Should be called by the
  56    container implementation when a container object is destroyed.
  57
  58    - set_TAG_data(TAG, OBJECT, KEY, DATA)
  59    Set the data on an object.
  60
  61    - TAG_data(TAG, OBJECT, KEY)
  62    Fetch the data for an object; returns NULL if it has not been set.
  63 */
  64
  65 /* This structure is used in a container to hold the data that the
  66    registry uses.  */
  67
  68 struct registry_fields
  69 {
  70   void **data;
  71   unsigned num_data;
  72 };
  73
  74 /* This macro is used in a container struct definition to define the
  75    fields used by the registry code.  */
  76
  77 #define REGISTRY_FIELDS                         \
  78   struct registry_fields registry_data
  79
  80 /* A convenience macro for the typical case where the registry data is
  81    kept as fields of the object.  This can be passed as the ACCESS
  82    method to DEFINE_REGISTRY.  */
  83
  84 #define REGISTRY_ACCESS_FIELD(CONTAINER) \
  85   (CONTAINER)
  86
  87 /* Opaque type representing a container type with a registry.  This
  88    type is never defined.  This is used to factor out common
  89    functionality of all struct tag names into common code.  IOW,
  90    "struct tag name" pointers are cast to and from "struct
  91    registry_container" pointers when calling the common registry
  92    "backend" functions.  */
  93 struct registry_container;
  94
  95 /* Registry callbacks have this type.  */
  96 typedef void (*registry_data_callback) (struct registry_container *, void *);
  97
  98 struct registry_data
  99 {
 100   unsigned index;
 101   registry_data_callback save;
 102   registry_data_callback free;
 103 };
 104
 105 struct registry_data_registration
 106 {
 107   struct registry_data *data;
 108   struct registry_data_registration *next;
 109 };
 110
 111 struct registry_data_registry
 112 {
 113   struct registry_data_registration *registrations;
 114   unsigned num_registrations;
 115 };
 116
 117 /* Registry backend functions.  Client code uses the frontend
 118    functions defined by DEFINE_REGISTRY below instead.  */
 119
 120 const struct registry_data *register_data_with_cleanup
 121   (struct registry_data_registry *registry,
 122    registry_data_callback save,
 123    registry_data_callback free);
 124
 125 void registry_alloc_data (struct registry_data_registry *registry,
 126                           struct registry_fields *registry_fields);
 127
 128 /* Cast FUNC and CONTAINER to the real types, and call FUNC, also
 129    passing DATA.  */
 130 typedef void (*registry_callback_adaptor) (registry_data_callback func,
 131                                            struct registry_container *container,
 132                                            void *data);
 133
 134 void registry_clear_data (struct registry_data_registry *data_registry,
 135                           registry_callback_adaptor adaptor,
 136                           struct registry_container *container,
 137                           struct registry_fields *fields);
 138
 139 void registry_container_free_data (struct registry_data_registry *data_registry,
 140                                    registry_callback_adaptor adaptor,
 141                                    struct registry_container *container,
 142                                    struct registry_fields *fields);
 143
 144 void registry_set_data (struct registry_fields *fields,
 145                         const struct registry_data *data,
 146                         void *value);
 147
 148 void *registry_data (struct registry_fields *fields,
 149                      const struct registry_data *data);
 150
 151 /* Define a new registry implementation.  */
 152
 153 #define DEFINE_REGISTRY(TAG, ACCESS)                                    \
 154 struct registry_data_registry TAG ## _data_registry = { NULL, 0 };      \
 155                                                                         \
 156 const struct TAG ## _data *                                             \
 157 register_ ## TAG ## _data_with_cleanup (void (*save) (struct TAG *, void *), \
 158                                         void (*free) (struct TAG *, void *)) \
 159 {                                                                       \
 160   struct registry_data_registration **curr;                             \
 161                                                                         \
 162   return (struct TAG ## _data *)                                        \
 163     register_data_with_cleanup (&TAG ## _data_registry,                 \
 164                                 (registry_data_callback) save,          \
 165                                 (registry_data_callback) free);         \
 166 }                                                                       \
 167                                                                         \
 168 const struct TAG ## _data *                                             \
 169 register_ ## TAG ## _data (void)                                        \
 170 {                                                                       \
 171   return register_ ## TAG ## _data_with_cleanup (NULL, NULL);           \
 172 }                                                                       \
 173                                                                         \
 174 static void                                                             \
 175 TAG ## _alloc_data (struct TAG *container)                              \
 176 {                                                                       \
 177   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 178                                                                         \
 179   registry_alloc_data (&TAG ## _data_registry, rdata);                  \
 180 }                                                                       \
 181                                                                         \
 182 static void                                                             \
 183 TAG ## registry_callback_adaptor (registry_data_callback func,          \
 184                                   struct registry_container *container, \
 185                                   void *data)                           \
 186 {                                                                       \
 187   struct TAG *tagged_container = (struct TAG *) container;              \
 188   struct registry_fields *rdata                                         \
 189     = &ACCESS (tagged_container)->registry_data;                        \
 190                                                                         \
 191   registry_ ## TAG ## _callback tagged_func                             \
 192     = (registry_ ## TAG ## _callback) func;                             \
 193                                                                         \
 194   tagged_func (tagged_container, data);                                 \
 195 }                                                                       \
 196                                                                         \
 197 void                                                                    \
 198 clear_ ## TAG ## _data (struct TAG *container)                          \
 199 {                                                                       \
 200   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 201                                                                         \
 202   registry_clear_data (&TAG ## _data_registry,                          \
 203                        TAG ## registry_callback_adaptor,                \
 204                        (struct registry_container *) container,         \
 205                        rdata);                                          \
 206 }                                                                       \
 207                                                                         \
 208 static void                                                             \
 209 TAG ## _free_data (struct TAG *container)                               \
 210 {                                                                       \
 211   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 212                                                                         \
 213   registry_container_free_data (&TAG ## _data_registry,                 \
 214                                 TAG ## registry_callback_adaptor,       \
 215                                 (struct registry_container *) container, \
 216                                 rdata);                                 \
 217 }                                                                       \
 218                                                                         \
 219 void                                                                    \
 220 set_ ## TAG ## _data (struct TAG *container,                            \
 221                       const struct TAG ## _data *data,                  \
 222                       void *value)                                      \
 223 {                                                                       \
 224   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 225                                                                         \
 226   registry_set_data (rdata,                                             \
 227                      (struct registry_data *) data,                     \
 228                      value);                                            \
 229 }                                                                       \
 230                                                                         \
 231 void *                                                                  \
 232 TAG ## _data (struct TAG *container, const struct TAG ## _data *data)   \
 233 {                                                                       \
 234   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 235                                                                         \
 236   return registry_data (rdata,                                          \
 237                         (struct registry_data *) data);                 \
 238 }
 239
 240
 241 /* External declarations for the registry functions.  */
 242
 243 #define DECLARE_REGISTRY(TAG)                                           \
 244 struct TAG ## _data;                                                    \
 245 typedef void (*registry_ ## TAG ## _callback) (struct TAG *, void *);   \
 246 extern const struct TAG ## _data *register_ ## TAG ## _data (void);     \
 247 extern const struct TAG ## _data *register_ ## TAG ## _data_with_cleanup \
 248  (registry_ ## TAG ## _callback save, registry_ ## TAG ## _callback free); \
 249 extern void clear_ ## TAG ## _data (struct TAG *);              \
 250 extern void set_ ## TAG ## _data (struct TAG *,                 \
 251                                   const struct TAG ## _data *data, \
 252                                   void *value);                 \
 253 extern void *TAG ## _data (struct TAG *,                        \
 254                            const struct TAG ## _data *data);
 255
 256 #endif /* REGISTRY_H */