]>
Commit | Line | Data |
---|---|---|
f05b9d93 NP |
1 | /* GNU Objective-C Runtime API. |
2 | Copyright (C) 2010 Free Software Foundation, Inc. | |
3 | Contributed by Nicola Pero <nicola.pero@meta-innovation.com> | |
4 | ||
5 | This file is part of GCC. | |
6 | ||
7 | GCC is free software; you can redistribute it and/or modify it | |
8 | under the terms of the GNU General Public License as published by the | |
9 | Free Software Foundation; either version 3, or (at your option) any | |
10 | later version. | |
11 | ||
12 | GCC is distributed in the hope that it will be useful, but WITHOUT | |
13 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
14 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public | |
15 | License for more details. | |
16 | ||
17 | Under Section 7 of GPL version 3, you are granted additional | |
18 | permissions described in the GCC Runtime Library Exception, version | |
19 | 3.1, as published by the Free Software Foundation. | |
20 | ||
21 | You should have received a copy of the GNU General Public License and | |
22 | a copy of the GCC Runtime Library Exception along with this program; | |
23 | see the files COPYING3 and COPYING.RUNTIME respectively. If not, see | |
24 | <http://www.gnu.org/licenses/>. */ | |
25 | ||
26 | #ifndef __objc_runtime_INCLUDE_GNU | |
27 | #define __objc_runtime_INCLUDE_GNU | |
28 | ||
2461ab4b NP |
29 | /* |
30 | This file declares the "modern" GNU Objective-C Runtime API. | |
31 | Include this file to use it. | |
32 | ||
33 | This API is replacing the "traditional" GNU Objective-C Runtime API | |
34 | (declared in objc/objc-api.h) which is the one supported by older | |
35 | versions of the GNU Objective-C Runtime. The "modern" API is very | |
36 | similar to the API used by the modern Apple/NeXT runtime. | |
37 | ||
38 | Because the two APIs have some conflicting definitions (in | |
39 | particular, Method and Category are defined differently) you should | |
40 | include either objc/objc-api.h (to use the traditional GNU | |
41 | Objective-C Runtime API) or objc/runtime.h (to use the modern GNU | |
42 | Objective-C Runtime API), but not both. | |
43 | */ | |
2461ab4b NP |
44 | #ifdef __objc_api_INCLUDE_GNU |
45 | # error You can not include both objc/objc-api.h and objc/runtime.h. Include objc/objc-api.h for the traditional GNU Objective-C Runtime API and objc/runtime.h for the modern one. | |
46 | #endif | |
f05b9d93 | 47 | |
2461ab4b NP |
48 | /* TODO: This file is incomplete. */ |
49 | ||
50 | #include "objc.h" | |
f05b9d93 | 51 | |
e4d50866 NP |
52 | /* An 'Ivar' represents an instance variable. It holds information |
53 | about the name, type and offset of the instance variable. */ | |
54 | typedef struct objc_ivar *Ivar; | |
55 | ||
56 | /* A 'Property' represents a property. It holds information about the | |
57 | name of the property, and its attributes. | |
58 | ||
59 | Compatibility Note: the Apple/NeXT runtime defines this as | |
60 | objc_property_t, so we define it that way as well, but obviously | |
61 | Property is the right name. */ | |
62 | typedef struct objc_property *Property; | |
63 | typedef struct objc_property *objc_property_t; | |
64 | ||
65 | /* A 'Method' represents a method. It holds information about the | |
66 | name, types and the IMP of the method. */ | |
67 | typedef struct objc_method *Method; | |
68 | ||
69 | /* A 'Category' represents a category. It holds information about the | |
70 | name of the category, the class it belongs to, and the methods, | |
71 | protocols and such like provided by the category. */ | |
72 | typedef struct objc_category *Category; | |
73 | ||
74 | /* 'Protocol' is defined in objc/objc.h (which is included by this | |
75 | file). */ | |
76 | ||
77 | /* Method descriptor returned by introspective Object methods. At the | |
78 | moment, this is really just the first part of the more complete | |
79 | objc_method structure used internally by the runtime. (PS: In the | |
80 | GNU Objective-C Runtime, selectors already include a type, so an | |
81 | objc_method_description does not add much to a SEL. But in other | |
82 | runtimes, that is not the case, which is why | |
83 | objc_method_description exists). */ | |
84 | struct objc_method_description | |
85 | { | |
86 | SEL name; /* Selector (name and signature) */ | |
87 | char *types; /* Type encoding */ | |
88 | }; | |
89 | ||
90 | /* The following are used in encode strings to describe the type of | |
91 | Ivars and Methods. */ | |
92 | #define _C_ID '@' | |
93 | #define _C_CLASS '#' | |
94 | #define _C_SEL ':' | |
95 | #define _C_CHR 'c' | |
96 | #define _C_UCHR 'C' | |
97 | #define _C_SHT 's' | |
98 | #define _C_USHT 'S' | |
99 | #define _C_INT 'i' | |
100 | #define _C_UINT 'I' | |
101 | #define _C_LNG 'l' | |
102 | #define _C_ULNG 'L' | |
103 | #define _C_LNG_LNG 'q' | |
104 | #define _C_ULNG_LNG 'Q' | |
105 | #define _C_FLT 'f' | |
106 | #define _C_DBL 'd' | |
107 | #define _C_LNG_DBL 'D' | |
108 | #define _C_BFLD 'b' | |
109 | #define _C_BOOL 'B' | |
110 | #define _C_VOID 'v' | |
111 | #define _C_UNDEF '?' | |
112 | #define _C_PTR '^' | |
113 | #define _C_CHARPTR '*' | |
114 | #define _C_ARY_B '[' | |
115 | #define _C_ARY_E ']' | |
116 | #define _C_UNION_B '(' | |
117 | #define _C_UNION_E ')' | |
118 | #define _C_STRUCT_B '{' | |
119 | #define _C_STRUCT_E '}' | |
120 | #define _C_VECTOR '!' | |
121 | #define _C_COMPLEX 'j' | |
122 | ||
123 | /* _C_ATOM is never generated by the compiler. You can treat it as | |
124 | equivalent to "*". */ | |
125 | #define _C_ATOM '%' | |
126 | ||
127 | /* The following are used in encode strings to describe some | |
128 | qualifiers of method and ivar types. */ | |
129 | #define _C_CONST 'r' | |
130 | #define _C_IN 'n' | |
131 | #define _C_INOUT 'N' | |
132 | #define _C_OUT 'o' | |
133 | #define _C_BYCOPY 'O' | |
134 | #define _C_BYREF 'R' | |
135 | #define _C_ONEWAY 'V' | |
136 | #define _C_GCINVISIBLE '|' | |
137 | ||
138 | /* The same when used as flags. */ | |
139 | #define _F_CONST 0x01 | |
140 | #define _F_IN 0x01 | |
141 | #define _F_OUT 0x02 | |
142 | #define _F_INOUT 0x03 | |
143 | #define _F_BYCOPY 0x04 | |
144 | #define _F_BYREF 0x08 | |
145 | #define _F_ONEWAY 0x10 | |
146 | #define _F_GCINVISIBLE 0x20 | |
147 | ||
bc18535a NP |
148 | |
149 | /** Internals: the following functions are in selector.c. */ | |
150 | ||
151 | /* Return the name of a given selector. */ | |
152 | objc_EXPORT const char *sel_getName (SEL selector); | |
153 | ||
154 | /* Return the type of a given selector. | |
155 | ||
156 | Compatibility Note: the Apple/NeXT runtime has untyped selectors, | |
157 | so it does not have this function, which is specific to the GNU | |
158 | Runtime. */ | |
159 | objc_EXPORT const char *sel_getType (SEL selector); | |
160 | ||
161 | /* This is the same as sel_registerName (). Please use | |
162 | sel_registerName () instead. */ | |
163 | objc_EXPORT SEL sel_getUid (const char *name); | |
164 | ||
165 | /* Register a selector with a given name (but unspecified types). If | |
166 | you know the types, it is better to call sel_registerTypedName(). | |
167 | If a selector with this name already exists, it is returned. */ | |
168 | objc_EXPORT SEL sel_registerName (const char *name); | |
169 | ||
170 | /* Register a selector with a given name and types. If a selector | |
171 | with this name and types already exists, it is returned. | |
172 | ||
173 | Compatibility Note: the Apple/NeXT runtime has untyped selectors, | |
174 | so it does not have this function, which is specific to the GNU | |
175 | Runtime. */ | |
176 | objc_EXPORT SEL set_registerTypedName (const char *name, const char *type); | |
177 | ||
178 | /* Return YES if first_selector is the same as second_selector, and NO | |
179 | if not. */ | |
180 | objc_EXPORT BOOL sel_isEqual (SEL first_selector, SEL second_selector); | |
181 | ||
182 | ||
183 | /** Internals: the following functions are in objects.c. */ | |
184 | ||
185 | /* Create an instance of class 'class', adding extraBytes to the size | |
186 | of the returned object. This method allocates the appropriate | |
187 | amount of memory for the instance, initializes it to zero, then | |
188 | calls all the C++ constructors on appropriate C++ instance | |
189 | variables of the instance (if any) (TODO: This is not implemented | |
190 | yet). */ | |
191 | objc_EXPORT id class_createInstance (Class class, size_t extraBytes); | |
192 | ||
193 | /* Copy an object and return the copy. extraBytes should be identical | |
194 | to the extraBytes parameter that was passed when creating the | |
195 | original object. */ | |
196 | objc_EXPORT id object_copy (id object, size_t extraBytes); | |
197 | ||
198 | /* Dispose of an object. This method calls the appropriate C++ | |
199 | destructors on appropriate C++ instance variables of the instance | |
200 | (if any) (TODO: This is not implemented yet), then frees the memory | |
201 | for the instance. */ | |
202 | objc_EXPORT id object_dispose (id object); | |
203 | ||
204 | ||
205 | /* TODO: Add all the other functions in the API. */ | |
206 | ||
207 | ||
208 | /** Internals: the following functions are in objc-foreach.c. */ | |
e4d50866 | 209 | |
f05b9d93 NP |
210 | /* 'objc_enumerationMutation()' is called when a collection is |
211 | mutated while being "fast enumerated". That is a hard error, and | |
212 | objc_enumerationMutation is called to deal with it. 'collection' | |
213 | is the collection object that was mutated during an enumeration. | |
214 | ||
215 | objc_enumerationMutation() will invoke the mutation handler if any | |
216 | is set. Then, it will abort the program. | |
217 | ||
218 | Compatibility note: the Apple runtime will not abort the program | |
219 | after calling the mutation handler. | |
220 | */ | |
221 | objc_EXPORT void objc_enumerationMutation (id collection); | |
222 | ||
223 | /* 'objc_set_enumeration_mutation_handler' can be used to set a | |
224 | function that will be called (instead of aborting) when a fast | |
225 | enumeration is mutated during enumeration. The handler will be | |
226 | called with the 'collection' being mutated as the only argument and | |
227 | it should not return; it should either exit the program, or could | |
228 | throw an exception. The recommended implementation is to throw an | |
229 | exception - the user can then use exception handlers to deal with | |
230 | it. | |
231 | ||
232 | This function is not thread safe (other threads may be trying to | |
233 | invoke the enumeration mutation handler while you are changing it!) | |
234 | and should be called during during the program initialization | |
235 | before threads are started. It is mostly reserved for "Foundation" | |
236 | libraries; in the case of GNUstep, GNUstep Base may be using this | |
237 | function to improve the standard enumeration mutation handling. | |
238 | You probably shouldn't use this function unless you are writing | |
239 | your own Foundation library. | |
240 | */ | |
2461ab4b | 241 | objc_EXPORT void objc_setEnumerationMutationHandler (void (*handler)(id)); |
f05b9d93 NP |
242 | |
243 | /* This structure (used during fast enumeration) is automatically | |
244 | defined by the compiler (it is as if this definition was always | |
245 | included in all Objective-C files). Note that it is usually | |
246 | defined again with the name of NSFastEnumeration by "Foundation" | |
247 | libraries such as GNUstep Base. And if NSFastEnumeration is | |
248 | defined, the compiler will use it instead of | |
249 | __objcFastEnumerationState when doing fast enumeration. | |
250 | */ | |
251 | /* | |
252 | struct __objcFastEnumerationState | |
253 | { | |
254 | unsigned long state; | |
255 | id *itemsPtr; | |
256 | unsigned long *mutationsPtr; | |
257 | unsigned long extra[5]; | |
258 | }; | |
259 | */ | |
f05b9d93 | 260 | |
e4d50866 | 261 | |
bc18535a NP |
262 | /** Internals: the following functions are implemented in encoding.c. */ |
263 | ||
e4d50866 NP |
264 | /* Traditional GNU Objective-C Runtime functions that are currently |
265 | used to implement method forwarding. | |
266 | */ | |
267 | ||
268 | /* Return the size of a variable which has the specified 'type' | |
269 | encoding. */ | |
270 | int objc_sizeof_type (const char *type); | |
271 | ||
272 | /* Return the align of a variable which has the specified 'type' | |
273 | encoding. */ | |
274 | int objc_alignof_type (const char *type); | |
275 | ||
276 | /* Return the aligned size of a variable which has the specified | |
277 | 'type' encoding. The aligned size is the size rounded up to the | |
278 | nearest alignment. */ | |
279 | int objc_aligned_size (const char *type); | |
280 | ||
281 | /* Return the promoted size of a variable which has the specified | |
282 | 'type' encoding. This is the size rounded up to the nearest | |
283 | integral of the wordsize, taken to be the size of a void *. */ | |
284 | int objc_promoted_size (const char *type); | |
285 | ||
286 | ||
287 | /* The following functions are used when parsing the type encoding of | |
288 | methods, to skip over parts that are ignored. They take as | |
289 | argument a pointer to a location inside the type encoding of a | |
290 | method (which is a string) and return a new pointer, pointing to a | |
291 | new location inside the string after having skipped the unwanted | |
292 | information. */ | |
293 | ||
294 | /* Skip some type qualifiers (_C_CONST, _C_IN, etc). These may | |
295 | eventually precede typespecs occurring in method prototype | |
296 | encodings. */ | |
297 | const char *objc_skip_type_qualifiers (const char *type); | |
298 | ||
299 | /* Skip one typespec element (_C_CLASS, _C_SEL, etc). If the typespec | |
300 | is prepended by type qualifiers, these are skipped as well. */ | |
301 | const char *objc_skip_typespec (const char *type); | |
302 | ||
303 | /* Skip an offset. */ | |
304 | const char *objc_skip_offset (const char *type); | |
305 | ||
306 | /* Skip an argument specification (ie, skipping a typespec, which may | |
307 | include qualifiers, and an offset too). */ | |
308 | const char *objc_skip_argspec (const char *type); | |
309 | ||
310 | /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type' | |
311 | (stopping at the first non-type qualifier found) and return an | |
312 | unsigned int which is the logical OR of all the corresponding flags | |
313 | (_F_CONST, _F_IN etc). */ | |
314 | unsigned objc_get_type_qualifiers (const char *type); | |
315 | ||
316 | ||
317 | /* Note that the following functions work for very simple structures, | |
318 | but get easily confused by more complicated ones (for example, | |
319 | containing vectors). A better solution is required. | |
320 | */ | |
321 | ||
322 | /* The following three functions can be used to determine how a | |
323 | structure is laid out by the compiler. For example: | |
324 | ||
325 | struct objc_struct_layout layout; | |
326 | int i; | |
327 | ||
328 | objc_layout_structure (type, &layout); | |
329 | while (objc_layout_structure_next_member (&layout)) | |
330 | { | |
331 | int position, align; | |
332 | const char *type; | |
333 | ||
334 | objc_layout_structure_get_info (&layout, &position, &align, &type); | |
335 | printf ("element %d has offset %d, alignment %d\n", | |
336 | i++, position, align); | |
337 | } | |
338 | ||
339 | These functions are used by objc_sizeof_type and objc_alignof_type | |
340 | functions to compute the size and alignment of structures. The | |
341 | previous method of computing the size and alignment of a structure | |
342 | was not working on some architectures, particulary on AIX, and in | |
343 | the presence of bitfields inside the structure. */ | |
344 | struct objc_struct_layout | |
345 | { | |
346 | const char *original_type; | |
347 | const char *type; | |
348 | const char *prev_type; | |
349 | unsigned int record_size; | |
350 | unsigned int record_align; | |
351 | }; | |
352 | ||
353 | void objc_layout_structure (const char *type, | |
354 | struct objc_struct_layout *layout); | |
355 | BOOL objc_layout_structure_next_member (struct objc_struct_layout *layout); | |
356 | void objc_layout_finish_structure (struct objc_struct_layout *layout, | |
357 | unsigned int *size, | |
358 | unsigned int *align); | |
359 | void objc_layout_structure_get_info (struct objc_struct_layout *layout, | |
360 | unsigned int *offset, | |
361 | unsigned int *align, | |
362 | const char **type); | |
363 | ||
f05b9d93 | 364 | #endif |