]>
Commit | Line | Data |
---|---|---|
90a2689f | 1 | /* GNU Objective-C Runtime API - Modern API |
cbe34bb5 | 2 | Copyright (C) 2010-2017 Free Software Foundation, Inc. |
f05b9d93 NP |
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. | |
2461ab4b | 31 | |
80e4b9e5 NP |
32 | This API replaced the "traditional" GNU Objective-C Runtime API |
33 | (which used to be declared in objc/objc-api.h) which is the one | |
34 | supported by older versions of the GNU Objective-C Runtime. The | |
35 | "modern" API is very similar to the API used by the modern | |
36 | Apple/NeXT runtime. | |
2461ab4b | 37 | */ |
2461ab4b | 38 | #include "objc.h" |
718a8e53 | 39 | #include "objc-decls.h" |
f05b9d93 | 40 | |
5b8b526e NP |
41 | #ifdef __cplusplus |
42 | extern "C" { | |
43 | #endif /* __cplusplus */ | |
44 | ||
e4d50866 NP |
45 | /* An 'Ivar' represents an instance variable. It holds information |
46 | about the name, type and offset of the instance variable. */ | |
47 | typedef struct objc_ivar *Ivar; | |
48 | ||
49 | /* A 'Property' represents a property. It holds information about the | |
50 | name of the property, and its attributes. | |
51 | ||
52 | Compatibility Note: the Apple/NeXT runtime defines this as | |
53 | objc_property_t, so we define it that way as well, but obviously | |
54 | Property is the right name. */ | |
55 | typedef struct objc_property *Property; | |
56 | typedef struct objc_property *objc_property_t; | |
57 | ||
58 | /* A 'Method' represents a method. It holds information about the | |
59 | name, types and the IMP of the method. */ | |
60 | typedef struct objc_method *Method; | |
61 | ||
62 | /* A 'Category' represents a category. It holds information about the | |
63 | name of the category, the class it belongs to, and the methods, | |
64 | protocols and such like provided by the category. */ | |
65 | typedef struct objc_category *Category; | |
66 | ||
67 | /* 'Protocol' is defined in objc/objc.h (which is included by this | |
68 | file). */ | |
69 | ||
70 | /* Method descriptor returned by introspective Object methods. At the | |
71 | moment, this is really just the first part of the more complete | |
72 | objc_method structure used internally by the runtime. (PS: In the | |
73 | GNU Objective-C Runtime, selectors already include a type, so an | |
74 | objc_method_description does not add much to a SEL. But in other | |
75 | runtimes, that is not the case, which is why | |
76 | objc_method_description exists). */ | |
77 | struct objc_method_description | |
78 | { | |
79 | SEL name; /* Selector (name and signature) */ | |
80 | char *types; /* Type encoding */ | |
81 | }; | |
82 | ||
83 | /* The following are used in encode strings to describe the type of | |
84 | Ivars and Methods. */ | |
85 | #define _C_ID '@' | |
86 | #define _C_CLASS '#' | |
87 | #define _C_SEL ':' | |
88 | #define _C_CHR 'c' | |
89 | #define _C_UCHR 'C' | |
90 | #define _C_SHT 's' | |
91 | #define _C_USHT 'S' | |
92 | #define _C_INT 'i' | |
93 | #define _C_UINT 'I' | |
94 | #define _C_LNG 'l' | |
95 | #define _C_ULNG 'L' | |
96 | #define _C_LNG_LNG 'q' | |
97 | #define _C_ULNG_LNG 'Q' | |
98 | #define _C_FLT 'f' | |
99 | #define _C_DBL 'd' | |
100 | #define _C_LNG_DBL 'D' | |
101 | #define _C_BFLD 'b' | |
102 | #define _C_BOOL 'B' | |
103 | #define _C_VOID 'v' | |
104 | #define _C_UNDEF '?' | |
105 | #define _C_PTR '^' | |
106 | #define _C_CHARPTR '*' | |
107 | #define _C_ARY_B '[' | |
108 | #define _C_ARY_E ']' | |
109 | #define _C_UNION_B '(' | |
110 | #define _C_UNION_E ')' | |
111 | #define _C_STRUCT_B '{' | |
112 | #define _C_STRUCT_E '}' | |
113 | #define _C_VECTOR '!' | |
114 | #define _C_COMPLEX 'j' | |
115 | ||
116 | /* _C_ATOM is never generated by the compiler. You can treat it as | |
117 | equivalent to "*". */ | |
118 | #define _C_ATOM '%' | |
119 | ||
120 | /* The following are used in encode strings to describe some | |
121 | qualifiers of method and ivar types. */ | |
122 | #define _C_CONST 'r' | |
123 | #define _C_IN 'n' | |
124 | #define _C_INOUT 'N' | |
125 | #define _C_OUT 'o' | |
126 | #define _C_BYCOPY 'O' | |
127 | #define _C_BYREF 'R' | |
128 | #define _C_ONEWAY 'V' | |
129 | #define _C_GCINVISIBLE '|' | |
130 | ||
131 | /* The same when used as flags. */ | |
132 | #define _F_CONST 0x01 | |
133 | #define _F_IN 0x01 | |
134 | #define _F_OUT 0x02 | |
135 | #define _F_INOUT 0x03 | |
136 | #define _F_BYCOPY 0x04 | |
137 | #define _F_BYREF 0x08 | |
138 | #define _F_ONEWAY 0x10 | |
139 | #define _F_GCINVISIBLE 0x20 | |
140 | ||
bc18535a | 141 | |
90a2689f | 142 | /** Implementation: the following functions are defined inline. */ |
fdcbbfe7 NP |
143 | |
144 | /* Return the class of 'object', or Nil if the object is nil. If | |
145 | 'object' is a class, the meta class is returned; if 'object' is a | |
146 | meta class, the root meta class is returned (note that this is | |
147 | different from the traditional GNU Objective-C Runtime API function | |
148 | object_get_class(), which for a meta class would return the meta | |
90a2689f NP |
149 | class itself). This function is inline, so it is really fast and |
150 | should be used instead of accessing object->class_pointer | |
151 | directly. */ | |
fdcbbfe7 NP |
152 | static inline Class |
153 | object_getClass (id object) | |
154 | { | |
155 | if (object != nil) | |
156 | return object->class_pointer; | |
157 | else | |
158 | return Nil; | |
159 | } | |
160 | ||
161 | ||
90a2689f | 162 | /** Implementation: the following functions are in selector.c. */ |
bc18535a | 163 | |
524660d2 NP |
164 | /* Return the name of a given selector. If 'selector' is NULL, return |
165 | "<null selector>". */ | |
bc18535a NP |
166 | objc_EXPORT const char *sel_getName (SEL selector); |
167 | ||
5750872c NP |
168 | /* Return the type of a given selector. Return NULL if selector is |
169 | NULL. | |
bc18535a NP |
170 | |
171 | Compatibility Note: the Apple/NeXT runtime has untyped selectors, | |
172 | so it does not have this function, which is specific to the GNU | |
173 | Runtime. */ | |
5750872c | 174 | objc_EXPORT const char *sel_getTypeEncoding (SEL selector); |
bc18535a NP |
175 | |
176 | /* This is the same as sel_registerName (). Please use | |
177 | sel_registerName () instead. */ | |
178 | objc_EXPORT SEL sel_getUid (const char *name); | |
179 | ||
180 | /* Register a selector with a given name (but unspecified types). If | |
181 | you know the types, it is better to call sel_registerTypedName(). | |
5750872c NP |
182 | If a selector with this name and no types already exists, it is |
183 | returned. Note that this function should really be called | |
9cacfc3e | 184 | 'objc_registerSelector'. Return NULL if 'name' is NULL. */ |
bc18535a NP |
185 | objc_EXPORT SEL sel_registerName (const char *name); |
186 | ||
187 | /* Register a selector with a given name and types. If a selector | |
5750872c NP |
188 | with this name and types already exists, it is returned. Note that |
189 | this function should really be called 'objc_registerTypedSelector', | |
190 | and it's called 'sel_registerTypedName' only for consistency with | |
9cacfc3e | 191 | 'sel_registerName'. Return NULL if 'name' is NULL. |
bc18535a NP |
192 | |
193 | Compatibility Note: the Apple/NeXT runtime has untyped selectors, | |
194 | so it does not have this function, which is specific to the GNU | |
195 | Runtime. */ | |
f7185d47 | 196 | objc_EXPORT SEL sel_registerTypedName (const char *name, const char *type); |
bc18535a NP |
197 | |
198 | /* Return YES if first_selector is the same as second_selector, and NO | |
199 | if not. */ | |
200 | objc_EXPORT BOOL sel_isEqual (SEL first_selector, SEL second_selector); | |
201 | ||
5750872c NP |
202 | /* Return all the selectors with the supplied name. In the GNU |
203 | runtime, selectors are typed and there may be multiple selectors | |
204 | with the same name but a different type. The return value of the | |
205 | function is a pointer to an area, allocated with malloc(), that | |
206 | contains all the selectors with the supplier name known to the | |
207 | runtime. The list is terminated by NULL. Optionally, if you pass | |
208 | a non-NULL 'numberOfReturnedSelectors' pointer, the unsigned int | |
209 | that it points to will be filled with the number of selectors | |
210 | returned. | |
211 | ||
212 | Compatibility Note: the Apple/NeXT runtime has untyped selectors, | |
213 | so it does not have this function, which is specific to the GNU | |
214 | Runtime. */ | |
215 | objc_EXPORT SEL * sel_copyTypedSelectorList (const char *name, | |
216 | unsigned int *numberOfReturnedSelectors); | |
217 | ||
218 | /* Return a selector with name 'name' and a non-zero type encoding, if | |
68ade9e4 NP |
219 | there is a single selector with a type, and with that name, |
220 | registered with the runtime. If there is no such selector, or if | |
221 | there are multiple selectors with the same name but conflicting | |
222 | types, NULL is returned. Return NULL if 'name' is NULL. | |
5750872c NP |
223 | |
224 | This is useful if you have the name of the selector, and would | |
225 | really like to get a selector for it that includes the type | |
226 | encoding. Unfortunately, if the program contains multiple selector | |
68ade9e4 NP |
227 | with the same name but different types, sel_getTypedSelector can |
228 | not possibly know which one you need, and so will return NULL. | |
5750872c NP |
229 | |
230 | Compatibility Note: the Apple/NeXT runtime has untyped selectors, | |
231 | so it does not have this function, which is specific to the GNU | |
232 | Runtime. */ | |
233 | objc_EXPORT SEL sel_getTypedSelector (const char *name); | |
234 | ||
bc18535a | 235 | |
90a2689f | 236 | /** Implementation: the following functions are in objects.c. */ |
bc18535a | 237 | |
fdcbbfe7 | 238 | /* Create an instance of class 'class_', adding extraBytes to the size |
bc18535a NP |
239 | of the returned object. This method allocates the appropriate |
240 | amount of memory for the instance, initializes it to zero, then | |
241 | calls all the C++ constructors on appropriate C++ instance | |
fdcbbfe7 NP |
242 | variables of the instance (if any) (TODO: The C++ constructors bit |
243 | is not implemented yet). */ | |
244 | objc_EXPORT id class_createInstance (Class class_, size_t extraBytes); | |
bc18535a NP |
245 | |
246 | /* Copy an object and return the copy. extraBytes should be identical | |
247 | to the extraBytes parameter that was passed when creating the | |
248 | original object. */ | |
249 | objc_EXPORT id object_copy (id object, size_t extraBytes); | |
250 | ||
251 | /* Dispose of an object. This method calls the appropriate C++ | |
252 | destructors on appropriate C++ instance variables of the instance | |
253 | (if any) (TODO: This is not implemented yet), then frees the memory | |
254 | for the instance. */ | |
255 | objc_EXPORT id object_dispose (id object); | |
256 | ||
fdcbbfe7 NP |
257 | /* Return the name of the class of 'object'. If 'object' is 'nil', |
258 | returns "Nil". */ | |
259 | objc_EXPORT const char * object_getClassName (id object); | |
260 | ||
261 | /* Change the class of object to be class_. Return the previous class | |
262 | of object. This is currently not really thread-safe. */ | |
263 | objc_EXPORT Class object_setClass (id object, Class class_); | |
264 | ||
265 | ||
90a2689f | 266 | /** Implementation: the following functions are in ivars.c. */ |
fdcbbfe7 NP |
267 | |
268 | /* Return an instance variable given the class and the instance | |
269 | variable name. This is an expensive function to call, so try to | |
270 | reuse the returned Ivar if you can. */ | |
271 | objc_EXPORT Ivar class_getInstanceVariable (Class class_, const char *name); | |
272 | ||
be05b0f5 NP |
273 | /* Return a class variable given the class and the class variable |
274 | name. This is an expensive function to call, so try to reuse the | |
275 | returned Ivar if you can. | |
276 | ||
277 | This function always returns NULL since class variables are | |
278 | currently unavailable in Objective-C. */ | |
279 | objc_EXPORT Ivar class_getClassVariable (Class class_, const char *name); | |
280 | ||
fdcbbfe7 NP |
281 | /* If the object was created in class_createInstance() with some |
282 | extraBytes, returns a pointer to them. If it was not, then the | |
283 | returned pointer may make no sense. */ | |
284 | objc_EXPORT void * object_getIndexedIvars (id object); | |
285 | ||
286 | /* Get the value of an instance variable of type 'id'. The function | |
287 | returns the instance variable. To get the value of the instance | |
288 | variable, you should pass as 'returnValue' a pointer to an 'id'; | |
289 | the value will be copied there. Note that 'returnValue' is really | |
290 | a 'void *', not a 'void **'. This function really works only with | |
291 | instance variables of type 'id'; for other types of instance | |
292 | variables, access directly the data at (char *)object + | |
293 | ivar_getOffset (ivar). */ | |
294 | objc_EXPORT Ivar object_getInstanceVariable (id object, const char *name, void **returnValue); | |
295 | ||
296 | /* Set the value of an instance variable. The value to set is passed | |
297 | in 'newValue' (which really is an 'id', not a 'void *'). The | |
298 | function returns the instance variable. This function really works | |
299 | only with instance variables of type 'id'; for other types of | |
300 | instance variables, access directly the data at (char *)object + | |
301 | ivar_getOffset (ivar). */ | |
302 | objc_EXPORT Ivar object_setInstanceVariable (id object, const char *name, void *newValue); | |
303 | ||
304 | /* Get the value of an instance variable of type 'id' of the object | |
305 | 'object'. This is faster than object_getInstanceVariable if you | |
306 | already have the instance variable because it avoids the expensive | |
307 | call to class_getInstanceVariable that is done by | |
308 | object_getInstanceVariable. */ | |
309 | objc_EXPORT id object_getIvar (id object, Ivar variable); | |
310 | ||
311 | /* Set the value of an instance variable of type 'id' of the object | |
312 | 'object'. This is faster than object_setInstanceVariable if you | |
313 | already have the instance variable because it avoids the expensive | |
314 | call to class_getInstanceVariable that is done by | |
315 | object_setInstanceVariable. */ | |
316 | objc_EXPORT void object_setIvar (id object, Ivar variable, id value); | |
317 | ||
ad9eef11 NP |
318 | /* Return the name of the instance variable. Return NULL if |
319 | 'variable' is NULL. */ | |
fdcbbfe7 NP |
320 | objc_EXPORT const char * ivar_getName (Ivar variable); |
321 | ||
322 | /* Return the offset of the instance variable from the start of the | |
ad9eef11 | 323 | object data. Return 0 if 'variable' is NULL. */ |
fdcbbfe7 NP |
324 | objc_EXPORT ptrdiff_t ivar_getOffset (Ivar variable); |
325 | ||
ad9eef11 NP |
326 | /* Return the type encoding of the variable. Return NULL if |
327 | 'variable' is NULL. */ | |
fdcbbfe7 NP |
328 | objc_EXPORT const char * ivar_getTypeEncoding (Ivar variable); |
329 | ||
ad9eef11 NP |
330 | /* Return all the instance variables of the class. The return value |
331 | of the function is a pointer to an area, allocated with malloc(), | |
332 | that contains all the instance variables of the class. It does not | |
333 | include instance variables of superclasses. The list is terminated | |
334 | by NULL. Optionally, if you pass a non-NULL | |
335 | 'numberOfReturnedIvars' pointer, the unsigned int that it points to | |
6c5c7efd NP |
336 | will be filled with the number of instance variables returned. |
337 | Return NULL for classes still in construction (ie, allocated using | |
338 | objc_allocatedClassPair() but not yet registered with the runtime | |
339 | using objc_registerClassPair()). */ | |
ad9eef11 NP |
340 | objc_EXPORT Ivar * class_copyIvarList (Class class_, unsigned int *numberOfReturnedIvars); |
341 | ||
6c5c7efd NP |
342 | /* Add an instance variable with name 'ivar_name' to class 'class_', |
343 | where 'class_' is a class in construction that has been created | |
344 | using objc_allocateClassPair() and has not been registered with the | |
345 | runtime using objc_registerClassPair() yet. You can not add | |
346 | instance variables to classes already registered with the runtime. | |
410644c4 NP |
347 | 'size' is the size of the instance variable, 'log_2_of_alignment' |
348 | the alignment as a power of 2 (so 0 means alignment to a 1 byte | |
349 | boundary, 1 means alignment to a 2 byte boundary, 2 means alignment | |
350 | to a 4 byte boundary, etc), and 'type' the type encoding of the | |
351 | variable type. You can use sizeof(), log2(__alignof__()) and | |
352 | @encode() to determine the right 'size', 'alignment' and 'type' for | |
353 | your instance variable. For example, to add an instance variable | |
354 | name "my_variable" and of type 'id', you can use: | |
355 | ||
356 | class_addIvar (class, "my_variable", sizeof (id), log2 ( __alignof__ (id)), | |
6c5c7efd NP |
357 | @encode (id)); |
358 | ||
359 | Return YES if the variable was added, and NO if not. In | |
360 | particular, return NO if 'class_' is Nil, or a meta-class or a | |
361 | class not in construction. Return Nil also if 'ivar_name' or | |
362 | 'type' is NULL, or 'size' is 0. | |
363 | */ | |
364 | objc_EXPORT BOOL class_addIvar (Class class_, const char * ivar_name, size_t size, | |
410644c4 | 365 | unsigned char log_2_of_alignment, const char *type); |
6c5c7efd | 366 | |
8437e063 NP |
367 | /* Return the name of the property. Return NULL if 'property' is |
368 | NULL. */ | |
369 | objc_EXPORT const char * property_getName (Property property); | |
370 | ||
371 | /* Return the attributes of the property as a string. Return NULL if | |
372 | 'property' is NULL. */ | |
373 | objc_EXPORT const char * property_getAttributes (Property property); | |
374 | ||
375 | /* Return the property with name 'propertyName' of the class 'class_'. | |
376 | This function returns NULL if the required property can not be | |
377 | found. Return NULL if 'class_' or 'propertyName' is NULL. | |
378 | ||
379 | Note that the traditional ABI does not store the list of properties | |
380 | of a class in a compiled module, so the traditional ABI will always | |
381 | return NULL. */ | |
382 | objc_EXPORT Property class_getProperty (Class class_, const char *propertyName); | |
383 | ||
384 | /* Return all the properties of the class. The return value | |
385 | of the function is a pointer to an area, allocated with malloc(), | |
386 | that contains all the properties of the class. It does not | |
387 | include properties of superclasses. The list is terminated | |
388 | by NULL. Optionally, if you pass a non-NULL | |
389 | 'numberOfReturnedIvars' pointer, the unsigned int that it points to | |
390 | will be filled with the number of properties returned. | |
391 | ||
392 | Note that the traditional ABI does not store the list of properties | |
393 | of a class in a compiled module, so the traditional ABI will always | |
394 | return an empty list. */ | |
395 | objc_EXPORT Property * class_copyPropertyList | |
396 | (Class class_, unsigned int *numberOfReturnedProperties); | |
397 | ||
3c44c190 NP |
398 | /* Return the ivar layout for class 'class_'. |
399 | ||
400 | At the moment this function always returns NULL. */ | |
401 | objc_EXPORT const char * class_getIvarLayout (Class class_); | |
402 | ||
403 | /* Return the weak ivar layout for class 'class_'. | |
404 | ||
405 | At the moment this function always returns NULL. */ | |
406 | objc_EXPORT const char * class_getWeakIvarLayout (Class class_); | |
407 | ||
408 | /* Set the ivar layout for class 'class_'. | |
409 | ||
410 | At the moment, this function does nothing. */ | |
411 | objc_EXPORT void class_setIvarLayout (Class class_, const char *layout); | |
412 | ||
413 | /* Set the weak ivar layout for class 'class_'. | |
414 | ||
415 | At the moment, this function does nothing. With the GNU runtime, | |
416 | you should use class_ivar_set_gcinvisible () to hide variables from | |
417 | the Garbage Collector. */ | |
418 | objc_EXPORT void class_setWeakIvarLayout (Class class_, const char *layout); | |
419 | ||
bc18535a | 420 | |
90a2689f NP |
421 | /** Implementation: the following functions are in class.c. */ |
422 | ||
423 | /* Compatibility Note: The Apple/NeXT runtime does not have | |
424 | objc_get_unknown_class_handler and | |
425 | objc_setGetUnknownClassHandler(). They provide functionality that | |
426 | the traditional GNU Objective-C Runtime API used to provide via the | |
427 | _objc_lookup_class hook. */ | |
428 | ||
429 | /* An 'objc_get_unknown_class_handler' function is used by | |
430 | objc_getClass() to get a class that is currently unknown to the | |
431 | compiler. You could use it for example to have the class loaded by | |
432 | dynamically loading a library. 'class_name' is the name of the | |
433 | class. The function should return the Class object if it manages to | |
434 | load the class, and Nil if not. */ | |
435 | typedef Class (*objc_get_unknown_class_handler)(const char *class_name); | |
436 | ||
437 | /* Sets a new handler function for getting unknown classes (to be used | |
438 | by objc_getClass () and related), and returns the previous one. | |
439 | This function is not safe to call in a multi-threaded environment | |
440 | because other threads may be trying to use the get unknown class | |
441 | handler while you change it! */ | |
2899534b | 442 | objc_EXPORT |
90a2689f NP |
443 | objc_get_unknown_class_handler |
444 | objc_setGetUnknownClassHandler (objc_get_unknown_class_handler new_handler); | |
445 | ||
90a2689f NP |
446 | /* Return the class with name 'name', if it is already registered with |
447 | the runtime. If it is not registered, and | |
448 | objc_setGetUnknownClassHandler() has been called to set a handler | |
449 | for unknown classes, the handler is called to give it a chance to | |
450 | load the class in some other way. If the class is not known to the | |
451 | runtime and the handler is not set or returns Nil, objc_getClass() | |
452 | returns Nil. */ | |
453 | objc_EXPORT Class objc_getClass (const char *name); | |
454 | ||
455 | /* Return the class with name 'name', if it is already registered with | |
456 | the runtime. Return Nil if not. This function does not call the | |
457 | objc_get_unknown_class_handler function if the class is not | |
458 | found. */ | |
6e45b376 | 459 | objc_EXPORT Class objc_lookUpClass (const char *name); |
90a2689f NP |
460 | |
461 | /* Return the meta class associated to the class with name 'name', if | |
462 | it is already registered with the runtime. First, it finds the | |
463 | class using objc_getClass(). Then, it returns the associated meta | |
464 | class. If the class could not be found using objc_getClass(), | |
465 | returns Nil. */ | |
466 | objc_EXPORT Class objc_getMetaClass (const char *name); | |
467 | ||
468 | /* This is identical to objc_getClass(), but if the class is not found, | |
469 | it aborts the process instead of returning Nil. */ | |
470 | objc_EXPORT Class objc_getRequiredClass (const char *name); | |
471 | ||
472 | /* If 'returnValue' is NULL, 'objc_getClassList' returns the number of | |
473 | classes currently registered with the runtime. If 'returnValue' is | |
474 | not NULL, it should be a (Class *) pointer to an area of memory | |
475 | which can contain up to 'maxNumberOfClassesToReturn' Class records. | |
476 | 'objc_getClassList' will fill the area pointed to by 'returnValue' | |
477 | with all the Classes registered with the runtime (or up to | |
478 | maxNumberOfClassesToReturn if there are more than | |
479 | maxNumberOfClassesToReturn). The function return value is the | |
480 | number of classes actually returned in 'returnValue'. */ | |
481 | objc_EXPORT int objc_getClassList (Class *returnValue, int maxNumberOfClassesToReturn); | |
482 | ||
483 | /* Compatibility Note: The Apple/NeXT runtime also has | |
484 | ||
485 | Class objc_getFutureClass (const char *name); | |
486 | void objc_setFutureClass (Class class_, const char *name); | |
487 | ||
488 | the documentation is unclear on what they are supposed to do, and | |
489 | the GNU Objective-C Runtime currently does not provide them. */ | |
490 | ||
debfbfee NP |
491 | /* Return the name of the class 'class_', or the string "nil" if the |
492 | class_ is Nil. */ | |
493 | objc_EXPORT const char * class_getName (Class class_); | |
494 | ||
be05b0f5 NP |
495 | /* Return YES if 'class_' is a meta class, and NO if not. If 'class_' |
496 | is Nil, return NO. */ | |
497 | objc_EXPORT BOOL class_isMetaClass (Class class_); | |
498 | ||
6c5c7efd | 499 | /* Return the superclass of 'class_'. If 'class_' is Nil, or it is a |
3f542037 NP |
500 | root class, return Nil. This function also works if 'class_' is a |
501 | class being constructed, that is, a class returned by | |
502 | objc_allocateClassPair() but before it has been registered with the | |
503 | runtime using objc_registerClassPair(). */ | |
be05b0f5 NP |
504 | objc_EXPORT Class class_getSuperclass (Class class_); |
505 | ||
506 | /* Return the 'version' number of the class, which is an integer that | |
507 | can be used to track changes in the class API, methods and | |
508 | variables. If class_ is Nil, return 0. If class_ is not Nil, the | |
509 | version is 0 unless class_setVersion() has been called to set a | |
510 | different one. | |
511 | ||
512 | Please note that internally the version is a long, but the API only | |
513 | allows you to set and retrieve int values. */ | |
514 | objc_EXPORT int class_getVersion (Class class_); | |
515 | ||
516 | /* Set the 'version' number of the class, which is an integer that can | |
517 | be used to track changes in the class API, methods and variables. | |
518 | If 'class_' is Nil, does nothing. | |
519 | ||
520 | This is typically used internally by "Foundation" libraries such as | |
521 | GNUstep Base to support serialization / deserialization of objects | |
522 | that work across changes in the classes. If you are using such a | |
523 | library, you probably want to use their versioning API, which may | |
524 | be based on this one, but is integrated with the rest of the | |
525 | library. | |
526 | ||
527 | Please note that internally the version is a long, but the API only | |
528 | allows you to set and retrieve int values. */ | |
529 | objc_EXPORT void class_setVersion (Class class_, int version); | |
530 | ||
531 | /* Return the size in bytes (a byte is the size of a char) of an | |
532 | instance of the class. If class_ is Nil, return 0; else it return | |
533 | a non-zero number (since the 'isa' instance variable is required | |
534 | for all classes). */ | |
535 | objc_EXPORT size_t class_getInstanceSize (Class class_); | |
536 | ||
8437e063 NP |
537 | /* Change the implementation of the method. It also searches all |
538 | classes for any class implementing the method, and replaces the | |
539 | existing implementation with the new one. For that to work, | |
540 | 'method' must be a method returned by class_getInstanceMethod() or | |
541 | class_getClassMethod() as the matching is done by comparing the | |
542 | pointers; in that case, only the implementation in the class is | |
543 | modified. Return the previous implementation that has been | |
544 | replaced. If method or implementation is NULL, do nothing and | |
545 | return NULL. */ | |
546 | objc_EXPORT IMP | |
547 | method_setImplementation (Method method, IMP implementation); | |
548 | ||
549 | /* Swap the implementation of two methods in a single, atomic | |
550 | operation. This is equivalent to getting the implementation of | |
551 | each method and then calling method_setImplementation() on the | |
552 | other one. For this to work, the two methods must have been | |
553 | returned by class_getInstanceMethod() or class_getClassMethod(). | |
554 | If 'method_a' or 'method_b' is NULL, do nothing. */ | |
555 | objc_EXPORT void | |
556 | method_exchangeImplementations (Method method_a, Method method_b); | |
557 | ||
6c5c7efd NP |
558 | /* Create a new class/meta-class pair. This function is called to |
559 | create a new class at runtime. The class is created with | |
560 | superclass 'superclass' (use 'Nil' to create a new root class) and | |
561 | name 'class_name'. 'extraBytes' can be used to specify some extra | |
562 | space for indexed variables to be added at the end of the class and | |
563 | meta-class objects (it is recommended that you set extraBytes to | |
564 | 0). Once you have created the class, it is not usable yet. You | |
565 | need to add any instance variables (by using class_addIvar()), any | |
566 | instance methods (by using class_addMethod()) and any class methods | |
567 | (by using class_addMethod() on the meta-class, as in | |
568 | class_addMethod (object_getClass (class), method)) that are | |
569 | required, and then you need to call objc_registerClassPair() to | |
570 | activate the class. If you need to create a hierarchy of classes, | |
571 | you need to create and register them one at a time. You can not | |
572 | create a new class using another class in construction as | |
573 | superclass. Return Nil if 'class-name' is NULL or if a class with | |
574 | that name already exists or 'superclass' is a class still in | |
575 | construction. | |
576 | ||
577 | Implementation Note: in the GNU runtime, allocating a class pair | |
578 | only creates the structures for the class pair, but does not | |
579 | register anything with the runtime. The class is registered with | |
580 | the runtime only when objc_registerClassPair() is called. In | |
581 | particular, if a class is in construction, objc_getClass() will not | |
582 | find it, the superclass will not know about it, | |
583 | class_getSuperclass() will return Nil and another thread may | |
584 | allocate a class pair with the same name; the conflict will only be | |
585 | detected when the classes are registered with the runtime. | |
586 | */ | |
587 | objc_EXPORT Class | |
588 | objc_allocateClassPair (Class super_class, const char *class_name, | |
589 | size_t extraBytes); | |
590 | ||
591 | /* Register a class pair that was created with | |
592 | objc_allocateClassPair(). After you register a class, you can no | |
593 | longer make changes to its instance variables, but you can start | |
594 | creating instances of it. Do nothing if 'class_' is NULL or if it | |
595 | is not a class allocated by objc_allocateClassPair() and still in | |
596 | construction. */ | |
597 | objc_EXPORT void | |
598 | objc_registerClassPair (Class class_); | |
599 | ||
600 | /* Dispose of a class pair created using objc_allocateClassPair(). | |
601 | Call this function if you started creating a new class with | |
602 | objc_allocateClassPair() but then want to abort the process. You | |
603 | should not access 'class_' after calling this method. Note that if | |
604 | 'class_' has already been registered with the runtime via | |
605 | objc_registerClassPair(), this function does nothing; you can only | |
606 | dispose of class pairs that are still being constructed. Do | |
607 | nothing if class is 'Nil' or if 'class_' is not a class being | |
608 | constructed. */ | |
609 | objc_EXPORT void | |
610 | objc_disposeClassPair (Class class_); | |
611 | ||
612 | /* Compatibility Note: The Apple/NeXT runtime has the function | |
613 | objc_duplicateClass () but it's undocumented. The GNU runtime does | |
614 | not have it. */ | |
615 | ||
debfbfee | 616 | |
ad9eef11 NP |
617 | /** Implementation: the following functions are in sendmsg.c. */ |
618 | ||
619 | /* Return the instance method with selector 'selector' of class | |
620 | 'class_', or NULL if the class (or one of its superclasses) does | |
621 | not implement the method. Return NULL if class_ is Nil or selector | |
e97cfd97 NP |
622 | is NULL. Calling this function may trigger a call to |
623 | +resolveInstanceMethod:, but does not return a forwarding | |
624 | function. */ | |
ad9eef11 NP |
625 | objc_EXPORT Method class_getInstanceMethod (Class class_, SEL selector); |
626 | ||
627 | /* Return the class method with selector 'selector' of class 'class_', | |
628 | or NULL if the class (or one of its superclasses) does not | |
629 | implement the method. Return NULL if class_ is Nil or selector is | |
e97cfd97 NP |
630 | NULL. Calling this function may trigger a call to |
631 | +resolveClassMethod:, but does not return a forwarding | |
632 | function. */ | |
ad9eef11 NP |
633 | objc_EXPORT Method class_getClassMethod (Class class_, SEL selector); |
634 | ||
635 | /* Return the IMP (pointer to the function implementing a method) for | |
636 | the instance method with selector 'selector' in class 'class_'. | |
637 | This is the same routine that is used while messaging, and should | |
638 | be very fast. Note that you most likely would need to cast the | |
639 | return function pointer to a function pointer with the appropriate | |
640 | arguments and return type before calling it. To get a class | |
641 | method, you can pass the meta-class as the class_ argument (ie, use | |
642 | class_getMethodImplementation (object_getClass (class_), | |
e97cfd97 NP |
643 | selector)). Return NULL if class_ is Nil or selector is NULL. |
644 | This function first looks for an existing method; if it is not | |
645 | found, it calls +resolveClassMethod: or +resolveInstanceMethod: | |
646 | (depending on whether a class or instance method is being looked | |
647 | up) if it is implemented. If the method returns YES, then it tries | |
648 | the look up again (the assumption being that +resolveClassMethod: | |
649 | or resolveInstanceMethod: will add the method using | |
650 | class_addMethod()). If it is still not found, it returns a | |
651 | forwarding function. */ | |
ad9eef11 NP |
652 | objc_EXPORT IMP class_getMethodImplementation (Class class_, SEL selector); |
653 | ||
654 | /* Compatibility Note: the Apple/NeXT runtime has the function | |
655 | class_getMethodImplementation_stret () which currently does not | |
656 | exist on the GNU runtime because the messaging implementation is | |
657 | different. */ | |
658 | ||
659 | /* Return YES if class 'class_' has an instance method implementing | |
660 | selector 'selector', and NO if not. Return NO if class_ is Nil or | |
661 | selector is NULL. If you need to check a class method, use the | |
662 | meta-class as the class_ argument (ie, use class_respondsToSelector | |
663 | (object_getClass (class_), selector)). */ | |
664 | objc_EXPORT BOOL class_respondsToSelector (Class class_, SEL selector); | |
665 | ||
6c5c7efd NP |
666 | /* Add a method to a class. Use this function to add a new method to |
667 | a class (potentially overriding a method with the same selector in | |
668 | the superclass); if you want to modify an existing method, use | |
669 | method_setImplementation() instead (or class_replaceMethod ()). | |
670 | This method adds an instance method to 'class_'; to add a class | |
671 | method, get the meta class first, then add the method to the meta | |
672 | class, that is, use | |
673 | ||
674 | class_addMethod (object_getClass (class_), selector, | |
675 | implementation, type); | |
676 | ||
677 | Return YES if the method was added, and NO if not. Do nothing if | |
678 | one of the arguments is NULL. */ | |
679 | objc_EXPORT BOOL class_addMethod (Class class_, SEL selector, IMP implementation, | |
680 | const char *method_types); | |
681 | ||
682 | /* Replace a method in a class. If the class already have a method | |
683 | with this 'selector', find it and use method_setImplementation() to | |
684 | replace the implementation with 'implementation' (method_types is | |
685 | ignored in that case). If the class does not already have a method | |
686 | with this 'selector', call 'class_addMethod() to add it. | |
687 | ||
688 | Return the previous implementation of the method, or NULL if none | |
689 | was found. Return NULL if any of the arguments is NULL. */ | |
690 | objc_EXPORT IMP class_replaceMethod (Class class_, SEL selector, IMP implementation, | |
691 | const char *method_types); | |
692 | ||
ad9eef11 NP |
693 | |
694 | /** Implementation: the following functions are in methods.c. */ | |
695 | ||
696 | /* Return the selector for method 'method'. Return NULL if 'method' | |
697 | is NULL. | |
698 | ||
699 | This function is misnamed; it should be called | |
700 | 'method_getSelector'. To get the actual name, get the selector, | |
701 | then the name from the selector (ie, use sel_getName | |
702 | (method_getName (method))). */ | |
703 | objc_EXPORT SEL method_getName (Method method); | |
704 | ||
705 | /* Return the IMP of the method. Return NULL if 'method' is NULL. */ | |
706 | objc_EXPORT IMP method_getImplementation (Method method); | |
707 | ||
708 | /* Return the type encoding of the method. Return NULL if 'method' is | |
709 | NULL. */ | |
710 | objc_EXPORT const char * method_getTypeEncoding (Method method); | |
711 | ||
ad49efbd NP |
712 | /* Return a method description for the method. Return NULL if |
713 | 'method' is NULL. */ | |
714 | objc_EXPORT struct objc_method_description * method_getDescription (Method method); | |
715 | ||
ad9eef11 NP |
716 | /* Return all the instance methods of the class. The return value of |
717 | the function is a pointer to an area, allocated with malloc(), that | |
718 | contains all the instance methods of the class. It does not | |
719 | include instance methods of superclasses. The list is terminated | |
720 | by NULL. Optionally, if you pass a non-NULL | |
721 | 'numberOfReturnedMethods' pointer, the unsigned int that it points | |
722 | to will be filled with the number of instance methods returned. To | |
723 | get the list of class methods, pass the meta-class in the 'class_' | |
724 | argument, (ie, use class_copyMethodList (object_getClass (class_), | |
725 | &numberOfReturnedMethods)). */ | |
726 | objc_EXPORT Method * class_copyMethodList (Class class_, unsigned int *numberOfReturnedMethods); | |
727 | ||
728 | ||
729 | /** Implementation: the following functions are in encoding.c. */ | |
730 | ||
731 | /* Return the number of arguments that the method 'method' expects. | |
732 | Note that all methods need two implicit arguments ('self' for the | |
733 | receiver, and '_cmd' for the selector). Return 0 if 'method' is | |
734 | NULL. */ | |
735 | objc_EXPORT unsigned int method_getNumberOfArguments (Method method); | |
736 | ||
ad49efbd | 737 | /* Return the string encoding for the return type of method 'method'. |
f7185d47 | 738 | The string is a standard zero-terminated string in an area of |
ad49efbd NP |
739 | memory allocated with malloc(); you should free it with free() when |
740 | you finish using it. Return an empty string if method is NULL. */ | |
741 | objc_EXPORT char * method_copyReturnType (Method method); | |
742 | ||
743 | /* Return the string encoding for the argument type of method | |
744 | 'method', argument number 'argumentNumber' ('argumentNumber' is 0 | |
745 | for self, 1 for _cmd, and 2 or more for the additional arguments if | |
f7185d47 | 746 | any). The string is a standard zero-terminated string in an area |
ad49efbd NP |
747 | of memory allocated with malloc(); you should free it with free() |
748 | when you finish using it. Return an empty string if method is NULL | |
749 | or if 'argumentNumber' refers to a non-existing argument. */ | |
750 | objc_EXPORT char * method_copyArgumentType (Method method, unsigned int argumentNumber); | |
751 | ||
752 | /* Return the string encoding for the return type of method 'method'. | |
753 | The string is returned by copying it into the supplied | |
754 | 'returnValue' string, which is of size 'returnValueSize'. No more | |
755 | than 'returnValueSize' characters are copied; if the encoding is | |
756 | smaller than 'returnValueSize', the rest of 'returnValue' is filled | |
f7185d47 NP |
757 | with zeros. If it is bigger, it is truncated (and would not be |
758 | zero-terminated). You should supply a big enough | |
ad49efbd | 759 | 'returnValueSize'. If the method is NULL, returnValue is set to a |
f7185d47 | 760 | string of zeros. */ |
ad49efbd NP |
761 | objc_EXPORT void method_getReturnType (Method method, char *returnValue, |
762 | size_t returnValueSize); | |
763 | ||
764 | /* Return the string encoding for the argument type of method | |
765 | 'method', argument number 'argumentNumber' ('argumentNumber' is 0 | |
766 | for self, 1 for _cmd, and 2 or more for the additional arguments if | |
767 | any). The string is returned by copying it into the supplied | |
768 | 'returnValue' string, which is of size 'returnValueSize'. No more | |
769 | than 'returnValueSize' characters are copied; if the encoding is | |
770 | smaller than 'returnValueSize', the rest of 'returnValue' is filled | |
f7185d47 NP |
771 | with zeros. If it is bigger, it is truncated (and would not be |
772 | zero-terminated). You should supply a big enough | |
ad49efbd | 773 | 'returnValueSize'. If the method is NULL, returnValue is set to a |
f7185d47 | 774 | string of zeros. */ |
ad49efbd NP |
775 | objc_EXPORT void method_getArgumentType (Method method, unsigned int argumentNumber, |
776 | char *returnValue, size_t returnValueSize); | |
777 | ||
ad9eef11 | 778 | |
debfbfee NP |
779 | /** Implementation: the following functions are in protocols.c. */ |
780 | ||
781 | /* Return the protocol with name 'name', or nil if it the protocol is | |
782 | not known to the runtime. */ | |
783 | objc_EXPORT Protocol *objc_getProtocol (const char *name); | |
784 | ||
785 | /* Return all the protocols known to the runtime. The return value of | |
786 | the function is a pointer to an area, allocated with malloc(), that | |
787 | contains all the protocols known to the runtime; the list is | |
788 | terminated by NULL. You should free this area using free() once | |
789 | you no longer need it. Optionally, if you pass a non-NULL | |
790 | 'numberOfReturnedProtocols' pointer, the unsigned int that it | |
791 | points to will be filled with the number of protocols returned. If | |
792 | there are no protocols known to the runtime, NULL is returned. */ | |
793 | objc_EXPORT Protocol **objc_copyProtocolList (unsigned int *numberOfReturnedProtocols); | |
794 | ||
795 | /* Add a protocol to a class, and return YES if it was done | |
cad10e05 | 796 | successfully, and NO if not. At the moment, NO should only happen |
debfbfee NP |
797 | if class_ or protocol are nil, if the protocol is not a Protocol |
798 | object or if the class already conforms to the protocol. */ | |
799 | objc_EXPORT BOOL class_addProtocol (Class class_, Protocol *protocol); | |
800 | ||
801 | /* Return YES if the class 'class_' conforms to Protocol 'protocol', | |
877bf195 NP |
802 | and NO if not. This function does not check superclasses; if you |
803 | want to check for superclasses (in the way that [NSObject | |
804 | +conformsToProtocol:] does) you need to iterate over the class | |
805 | hierarchy using class_getSuperclass(), and call | |
806 | class_conformsToProtocol() for each of them. */ | |
debfbfee NP |
807 | objc_EXPORT BOOL class_conformsToProtocol (Class class_, Protocol *protocol); |
808 | ||
809 | /* Return all the protocols that the class conforms to. The return | |
810 | value of the function is a pointer to an area, allocated with | |
811 | malloc(), that contains all the protocols formally adopted by the | |
812 | class. It does not include protocols adopted by superclasses. The | |
813 | list is terminated by NULL. Optionally, if you pass a non-NULL | |
814 | 'numberOfReturnedProtocols' pointer, the unsigned int that it | |
877bf195 NP |
815 | points to will be filled with the number of protocols returned. |
816 | This function does not return protocols that superclasses conform | |
817 | to. */ | |
debfbfee NP |
818 | objc_EXPORT Protocol **class_copyProtocolList (Class class_, unsigned int *numberOfReturnedProtocols); |
819 | ||
820 | /* Return YES if protocol 'protocol' conforms to protocol | |
821 | 'anotherProtocol', and NO if not. Note that if one of the two | |
822 | protocols is nil, it returns NO. */ | |
823 | objc_EXPORT BOOL protocol_conformsToProtocol (Protocol *protocol, Protocol *anotherProtocol); | |
824 | ||
825 | /* Return YES if protocol 'protocol' is the same as protocol | |
826 | 'anotherProtocol', and 'NO' if not. Note that it returns YES if | |
827 | the two protocols are both nil. */ | |
828 | objc_EXPORT BOOL protocol_isEqual (Protocol *protocol, Protocol *anotherProtocol); | |
829 | ||
830 | /* Return the name of protocol 'protocol'. If 'protocol' is nil or is | |
831 | not a Protocol, return NULL. */ | |
832 | objc_EXPORT const char *protocol_getName (Protocol *protocol); | |
833 | ||
834 | /* Return the method description for the method with selector | |
835 | 'selector' in protocol 'protocol'; if 'requiredMethod' is YES, the | |
836 | function searches the list of required methods; if NO, the list of | |
837 | optional methods. If 'instanceMethod' is YES, the function search | |
838 | for an instance method; if NO, for a class method. If there is no | |
839 | matching method, an objc_method_description structure with both | |
840 | name and types set to NULL is returned. This function will only | |
841 | find methods that are directly declared in the protocol itself, not | |
842 | in other protocols that this protocol adopts. | |
843 | ||
844 | Note that the traditional ABI does not store the list of optional | |
845 | methods of a protocol in a compiled module, so the traditional ABI | |
846 | will always return (NULL, NULL) when requiredMethod == NO. */ | |
847 | objc_EXPORT struct objc_method_description protocol_getMethodDescription (Protocol *protocol, | |
848 | SEL selector, | |
849 | BOOL requiredMethod, | |
850 | BOOL instanceMethod); | |
851 | ||
852 | /* Return the method descriptions of all the methods of the protocol. | |
853 | The return value of the function is a pointer to an area, allocated | |
854 | with malloc(), that contains all the method descriptions of the | |
855 | methods of the protocol. It does not recursively include methods | |
856 | of the protocols adopted by this protocol. The list is terminated | |
857 | by a NULL objc_method_description (one with both fields set to | |
858 | NULL). Optionally, if you pass a non-NULL | |
859 | 'numberOfReturnedMethods' pointer, the unsigned int that it points | |
860 | to will be filled with the number of properties returned. | |
861 | ||
862 | Note that the traditional ABI does not store the list of optional | |
863 | methods of a protocol in a compiled module, so the traditional ABI | |
864 | will always return an empty list if requiredMethod is set to | |
865 | NO. */ | |
866 | objc_EXPORT struct objc_method_description *protocol_copyMethodDescriptionList (Protocol *protocol, | |
867 | BOOL requiredMethod, | |
868 | BOOL instanceMethod, | |
869 | unsigned int *numberOfReturnedMethods); | |
870 | ||
871 | /* Return the property with name 'propertyName' of the protocol | |
872 | 'protocol'. If 'requiredProperty' is YES, the function searches | |
873 | the list of required properties; if NO, the list of optional | |
874 | properties. If 'instanceProperty' is YES, the function searches | |
875 | the list of instance properties; if NO, the list of class | |
876 | properties. At the moment, optional properties and class | |
877 | properties are not part of the Objective-C language, so both | |
878 | 'requiredProperty' and 'instanceProperty' should be set to YES. | |
879 | This function returns NULL if the required property can not be | |
880 | found. | |
881 | ||
882 | Note that the traditional ABI does not store the list of properties | |
883 | of a protocol in a compiled module, so the traditional ABI will | |
884 | always return NULL. */ | |
885 | objc_EXPORT Property protocol_getProperty (Protocol *protocol, const char *propertyName, | |
886 | BOOL requiredProperty, BOOL instanceProperty); | |
887 | ||
888 | /* Return all the properties of the protocol. The return value of the | |
889 | function is a pointer to an area, allocated with malloc(), that | |
890 | contains all the properties of the protocol. It does not | |
891 | recursively include properties of the protocols adopted by this | |
892 | protocol. The list is terminated by NULL. Optionally, if you pass | |
893 | a non-NULL 'numberOfReturnedProperties' pointer, the unsigned int | |
894 | that it points to will be filled with the number of properties | |
895 | returned. | |
896 | ||
897 | Note that the traditional ABI does not store the list of properties | |
898 | of a protocol in a compiled module, so the traditional ABI will | |
899 | always return NULL and store 0 in numberOfReturnedProperties. */ | |
900 | objc_EXPORT Property *protocol_copyPropertyList (Protocol *protocol, unsigned int *numberOfReturnedProperties); | |
901 | ||
902 | /* Return all the protocols that the protocol conforms to. The return | |
903 | value of the function is a pointer to an area, allocated with | |
904 | malloc(), that contains all the protocols formally adopted by the | |
905 | protocol. It does not recursively include protocols adopted by the | |
906 | protocols adopted by this protocol. The list is terminated by | |
907 | NULL. Optionally, if you pass a non-NULL | |
908 | 'numberOfReturnedProtocols' pointer, the unsigned int that it | |
909 | points to will be filled with the number of protocols returned. */ | |
910 | objc_EXPORT Protocol **protocol_copyProtocolList (Protocol *protocol, unsigned int *numberOfReturnedProtocols); | |
911 | ||
90a2689f | 912 | |
120d5f8e NP |
913 | /** Implementation: the following hook is in init.c. */ |
914 | ||
915 | /* This is a hook which is called by __objc_exec_class every time a | |
916 | class or a category is loaded into the runtime. This may e.g. help | |
917 | a dynamic loader determine the classes that have been loaded when | |
918 | an object file is dynamically linked in. */ | |
919 | objc_EXPORT void (*_objc_load_callback)(Class _class, struct objc_category *category); | |
920 | ||
bc18535a | 921 | |
90a2689f | 922 | /** Implementation: the following functions are in objc-foreach.c. */ |
e4d50866 | 923 | |
f05b9d93 NP |
924 | /* 'objc_enumerationMutation()' is called when a collection is |
925 | mutated while being "fast enumerated". That is a hard error, and | |
926 | objc_enumerationMutation is called to deal with it. 'collection' | |
927 | is the collection object that was mutated during an enumeration. | |
928 | ||
929 | objc_enumerationMutation() will invoke the mutation handler if any | |
930 | is set. Then, it will abort the program. | |
931 | ||
932 | Compatibility note: the Apple runtime will not abort the program | |
fdcbbfe7 | 933 | after calling the mutation handler. */ |
f05b9d93 NP |
934 | objc_EXPORT void objc_enumerationMutation (id collection); |
935 | ||
936 | /* 'objc_set_enumeration_mutation_handler' can be used to set a | |
937 | function that will be called (instead of aborting) when a fast | |
938 | enumeration is mutated during enumeration. The handler will be | |
939 | called with the 'collection' being mutated as the only argument and | |
940 | it should not return; it should either exit the program, or could | |
941 | throw an exception. The recommended implementation is to throw an | |
942 | exception - the user can then use exception handlers to deal with | |
943 | it. | |
944 | ||
945 | This function is not thread safe (other threads may be trying to | |
946 | invoke the enumeration mutation handler while you are changing it!) | |
947 | and should be called during during the program initialization | |
948 | before threads are started. It is mostly reserved for "Foundation" | |
949 | libraries; in the case of GNUstep, GNUstep Base may be using this | |
950 | function to improve the standard enumeration mutation handling. | |
951 | You probably shouldn't use this function unless you are writing | |
fdcbbfe7 | 952 | your own Foundation library. */ |
2461ab4b | 953 | objc_EXPORT void objc_setEnumerationMutationHandler (void (*handler)(id)); |
f05b9d93 NP |
954 | |
955 | /* This structure (used during fast enumeration) is automatically | |
956 | defined by the compiler (it is as if this definition was always | |
957 | included in all Objective-C files). Note that it is usually | |
958 | defined again with the name of NSFastEnumeration by "Foundation" | |
959 | libraries such as GNUstep Base. And if NSFastEnumeration is | |
960 | defined, the compiler will use it instead of | |
fdcbbfe7 | 961 | __objcFastEnumerationState when doing fast enumeration. */ |
f05b9d93 NP |
962 | /* |
963 | struct __objcFastEnumerationState | |
964 | { | |
965 | unsigned long state; | |
966 | id *itemsPtr; | |
967 | unsigned long *mutationsPtr; | |
968 | unsigned long extra[5]; | |
969 | }; | |
970 | */ | |
f05b9d93 | 971 | |
e4d50866 | 972 | |
ecfc2705 NP |
973 | /* Compatibility Note: The Apple/NeXT runtime has the functions |
974 | objc_copyImageNames (), class_getImageName () and | |
975 | objc_copyClassNamesForImage () but they are undocumented. The GNU | |
976 | runtime does not have them at the moment. */ | |
977 | ||
978 | /* Compatibility Note: The Apple/NeXT runtime has the functions | |
979 | objc_setAssociatedObject (), objc_getAssociatedObject (), | |
980 | objc_removeAssociatedObjects () and the objc_AssociationPolicy type | |
981 | and related enum. The GNU runtime does not have them yet. | |
982 | TODO: Implement them. */ | |
983 | ||
984 | /* Compatibility Note: The Apple/NeXT runtime has the function | |
985 | objc_setForwardHandler (). The GNU runtime does not have it | |
986 | because messaging (and, in particular, forwarding) works in a | |
987 | different (incompatible) way with the GNU runtime. If you need to | |
988 | customize message forwarding at the Objective-C runtime level (that | |
989 | is, if you are implementing your own "Foundation" library such as | |
990 | GNUstep Base on top of the Objective-C runtime), in objc/message.h | |
991 | there are hooks (that work in the framework of the GNU runtime) to | |
992 | do so. */ | |
993 | ||
994 | ||
718a8e53 NP |
995 | /** Implementation: the following functions are in memory.c. */ |
996 | ||
997 | /* Traditional GNU Objective-C Runtime functions that are used for | |
998 | memory allocation and disposal. These functions are used in the | |
999 | same way as you use malloc, realloc, calloc and free and make sure | |
1000 | that memory allocation works properly with the garbage | |
1001 | collector. | |
1002 | ||
1003 | Compatibility Note: these functions are not available with the | |
1004 | Apple/NeXT runtime. */ | |
1005 | ||
1006 | objc_EXPORT void *objc_malloc(size_t size); | |
1007 | ||
1008 | /* FIXME: Shouldn't the following be called objc_malloc_atomic ? The | |
1009 | GC function is GC_malloc_atomic() which makes sense. | |
1010 | */ | |
1011 | objc_EXPORT void *objc_atomic_malloc(size_t size); | |
1012 | ||
1013 | objc_EXPORT void *objc_realloc(void *mem, size_t size); | |
1014 | ||
1015 | objc_EXPORT void *objc_calloc(size_t nelem, size_t size); | |
1016 | ||
1017 | objc_EXPORT void objc_free(void *mem); | |
1018 | ||
1019 | ||
fea78205 NP |
1020 | /** Implementation: the following functions are in gc.c. */ |
1021 | ||
ecfc2705 NP |
1022 | /* The GNU Objective-C Runtime has a different implementation of |
1023 | garbage collection. | |
1024 | ||
1025 | Compatibility Note: these functions are not available with the | |
1026 | Apple/NeXT runtime. */ | |
1027 | ||
fea78205 NP |
1028 | /* Mark the instance variable as inaccessible to the garbage |
1029 | collector. */ | |
1030 | objc_EXPORT void class_ivar_set_gcinvisible (Class _class, | |
1031 | const char* ivarname, | |
1032 | BOOL gcInvisible); | |
1033 | ||
1034 | ||
90a2689f | 1035 | /** Implementation: the following functions are in encoding.c. */ |
bc18535a | 1036 | |
e4d50866 NP |
1037 | /* Traditional GNU Objective-C Runtime functions that are currently |
1038 | used to implement method forwarding. | |
718a8e53 NP |
1039 | |
1040 | Compatibility Note: these functions are not available with the | |
1041 | Apple/NeXT runtime. */ | |
e4d50866 NP |
1042 | |
1043 | /* Return the size of a variable which has the specified 'type' | |
1044 | encoding. */ | |
2899534b | 1045 | objc_EXPORT int objc_sizeof_type (const char *type); |
e4d50866 NP |
1046 | |
1047 | /* Return the align of a variable which has the specified 'type' | |
1048 | encoding. */ | |
2899534b | 1049 | objc_EXPORT int objc_alignof_type (const char *type); |
e4d50866 NP |
1050 | |
1051 | /* Return the aligned size of a variable which has the specified | |
1052 | 'type' encoding. The aligned size is the size rounded up to the | |
1053 | nearest alignment. */ | |
2899534b | 1054 | objc_EXPORT int objc_aligned_size (const char *type); |
e4d50866 NP |
1055 | |
1056 | /* Return the promoted size of a variable which has the specified | |
1057 | 'type' encoding. This is the size rounded up to the nearest | |
1058 | integral of the wordsize, taken to be the size of a void *. */ | |
2899534b | 1059 | objc_EXPORT int objc_promoted_size (const char *type); |
e4d50866 NP |
1060 | |
1061 | ||
1062 | /* The following functions are used when parsing the type encoding of | |
1063 | methods, to skip over parts that are ignored. They take as | |
1064 | argument a pointer to a location inside the type encoding of a | |
1065 | method (which is a string) and return a new pointer, pointing to a | |
1066 | new location inside the string after having skipped the unwanted | |
1067 | information. */ | |
1068 | ||
1069 | /* Skip some type qualifiers (_C_CONST, _C_IN, etc). These may | |
1070 | eventually precede typespecs occurring in method prototype | |
1071 | encodings. */ | |
2899534b | 1072 | objc_EXPORT const char *objc_skip_type_qualifiers (const char *type); |
e4d50866 NP |
1073 | |
1074 | /* Skip one typespec element (_C_CLASS, _C_SEL, etc). If the typespec | |
1075 | is prepended by type qualifiers, these are skipped as well. */ | |
2899534b | 1076 | objc_EXPORT const char *objc_skip_typespec (const char *type); |
e4d50866 NP |
1077 | |
1078 | /* Skip an offset. */ | |
2899534b | 1079 | objc_EXPORT const char *objc_skip_offset (const char *type); |
e4d50866 NP |
1080 | |
1081 | /* Skip an argument specification (ie, skipping a typespec, which may | |
1082 | include qualifiers, and an offset too). */ | |
2899534b | 1083 | objc_EXPORT const char *objc_skip_argspec (const char *type); |
e4d50866 NP |
1084 | |
1085 | /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type' | |
1086 | (stopping at the first non-type qualifier found) and return an | |
1087 | unsigned int which is the logical OR of all the corresponding flags | |
1088 | (_F_CONST, _F_IN etc). */ | |
2899534b | 1089 | objc_EXPORT unsigned objc_get_type_qualifiers (const char *type); |
e4d50866 NP |
1090 | |
1091 | ||
1092 | /* Note that the following functions work for very simple structures, | |
1093 | but get easily confused by more complicated ones (for example, | |
2899534b NP |
1094 | containing vectors). A better solution is required. These |
1095 | functions are likely to change in the next GCC release. */ | |
e4d50866 NP |
1096 | |
1097 | /* The following three functions can be used to determine how a | |
1098 | structure is laid out by the compiler. For example: | |
1099 | ||
1100 | struct objc_struct_layout layout; | |
1101 | int i; | |
1102 | ||
1103 | objc_layout_structure (type, &layout); | |
1104 | while (objc_layout_structure_next_member (&layout)) | |
1105 | { | |
1106 | int position, align; | |
1107 | const char *type; | |
1108 | ||
1109 | objc_layout_structure_get_info (&layout, &position, &align, &type); | |
1110 | printf ("element %d has offset %d, alignment %d\n", | |
1111 | i++, position, align); | |
1112 | } | |
1113 | ||
1114 | These functions are used by objc_sizeof_type and objc_alignof_type | |
1115 | functions to compute the size and alignment of structures. The | |
1116 | previous method of computing the size and alignment of a structure | |
cad10e05 | 1117 | was not working on some architectures, particularly on AIX, and in |
e4d50866 NP |
1118 | the presence of bitfields inside the structure. */ |
1119 | struct objc_struct_layout | |
1120 | { | |
1121 | const char *original_type; | |
1122 | const char *type; | |
1123 | const char *prev_type; | |
1124 | unsigned int record_size; | |
1125 | unsigned int record_align; | |
1126 | }; | |
1127 | ||
2899534b | 1128 | objc_EXPORT void objc_layout_structure (const char *type, |
e4d50866 | 1129 | struct objc_struct_layout *layout); |
2899534b NP |
1130 | objc_EXPORT BOOL objc_layout_structure_next_member (struct objc_struct_layout *layout); |
1131 | objc_EXPORT void objc_layout_finish_structure (struct objc_struct_layout *layout, | |
1132 | unsigned int *size, | |
1133 | unsigned int *align); | |
1134 | objc_EXPORT void objc_layout_structure_get_info (struct objc_struct_layout *layout, | |
1135 | unsigned int *offset, | |
1136 | unsigned int *align, | |
1137 | const char **type); | |
e4d50866 | 1138 | |
5b8b526e NP |
1139 | #ifdef __cplusplus |
1140 | } | |
1141 | #endif /* __cplusplus */ | |
1142 | ||
f05b9d93 | 1143 | #endif |