gdb/registry.h

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