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