gdb/registry.h

   1 /* Macros for general registry objects.
   2
   3    Copyright (C) 2011-2017 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   struct registry_data_registration **curr;                             \
 162                                                                         \
 163   return (struct TAG ## _data *)                                        \
 164     register_data_with_cleanup (&TAG ## _data_registry,                 \
 165                                 (registry_data_callback) save,          \
 166                                 (registry_data_callback) free);         \
 167 }                                                                       \
 168                                                                         \
 169 const struct TAG ## _data *                                             \
 170 register_ ## TAG ## _data (void)                                        \
 171 {                                                                       \
 172   return register_ ## TAG ## _data_with_cleanup (NULL, NULL);           \
 173 }                                                                       \
 174                                                                         \
 175 static void                                                             \
 176 TAG ## _alloc_data (struct TAG *container)                              \
 177 {                                                                       \
 178   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 179                                                                         \
 180   registry_alloc_data (&TAG ## _data_registry, rdata);                  \
 181 }                                                                       \
 182                                                                         \
 183 static void                                                             \
 184 TAG ## registry_callback_adaptor (registry_data_callback func,          \
 185                                   struct registry_container *container, \
 186                                   void *data)                           \
 187 {                                                                       \
 188   struct TAG *tagged_container = (struct TAG *) container;              \
 189   struct registry_fields *rdata                                         \
 190     = &ACCESS (tagged_container)->registry_data;                        \
 191                                                                         \
 192   registry_ ## TAG ## _callback tagged_func                             \
 193     = (registry_ ## TAG ## _callback) func;                             \
 194                                                                         \
 195   tagged_func (tagged_container, data);                                 \
 196 }                                                                       \
 197                                                                         \
 198 void                                                                    \
 199 clear_ ## TAG ## _data (struct TAG *container)                          \
 200 {                                                                       \
 201   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 202                                                                         \
 203   registry_clear_data (&TAG ## _data_registry,                          \
 204                        TAG ## registry_callback_adaptor,                \
 205                        (struct registry_container *) container,         \
 206                        rdata);                                          \
 207 }                                                                       \
 208                                                                         \
 209 static void                                                             \
 210 TAG ## _free_data (struct TAG *container)                               \
 211 {                                                                       \
 212   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 213                                                                         \
 214   registry_container_free_data (&TAG ## _data_registry,                 \
 215                                 TAG ## registry_callback_adaptor,       \
 216                                 (struct registry_container *) container, \
 217                                 rdata);                                 \
 218 }                                                                       \
 219                                                                         \
 220 void                                                                    \
 221 set_ ## TAG ## _data (struct TAG *container,                            \
 222                       const struct TAG ## _data *data,                  \
 223                       void *value)                                      \
 224 {                                                                       \
 225   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 226                                                                         \
 227   registry_set_data (rdata,                                             \
 228                      (struct registry_data *) data,                     \
 229                      value);                                            \
 230 }                                                                       \
 231                                                                         \
 232 void *                                                                  \
 233 TAG ## _data (struct TAG *container, const struct TAG ## _data *data)   \
 234 {                                                                       \
 235   struct registry_fields *rdata = &ACCESS (container)->registry_data;   \
 236                                                                         \
 237   return registry_data (rdata,                                          \
 238                         (struct registry_data *) data);                 \
 239 }
 240
 241
 242 /* External declarations for the registry functions.  */
 243
 244 #define DECLARE_REGISTRY(TAG)                                           \
 245 struct TAG ## _data;                                                    \
 246 typedef void (*registry_ ## TAG ## _callback) (struct TAG *, void *);   \
 247 extern const struct TAG ## _data *register_ ## TAG ## _data (void);     \
 248 extern const struct TAG ## _data *register_ ## TAG ## _data_with_cleanup \
 249  (registry_ ## TAG ## _callback save, registry_ ## TAG ## _callback free); \
 250 extern void clear_ ## TAG ## _data (struct TAG *);              \
 251 extern void set_ ## TAG ## _data (struct TAG *,                 \
 252                                   const struct TAG ## _data *data, \
 253                                   void *value);                 \
 254 extern void *TAG ## _data (struct TAG *,                        \
 255                            const struct TAG ## _data *data);
 256
 257 #endif /* REGISTRY_H */