| 1 | /* Macros for general registry objects. |
| 2 | |
| 3 | Copyright (C) 2011-2016 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 */ |