Automatic date update in version.in
[external/binutils.git] / gdb / registry.h
1 /* Macros for general registry objects.
2
3    Copyright (C) 2011-2018 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 */