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