1 /** Interface to ObjC runtime for GNUStep
2 Copyright (C) 1995, 1997, 2000, 2002, 2003 Free Software Foundation, Inc.
3
4 Written by: Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
5 Date: 1995
6 Written by: Richard Frith-Macdonald <rfm@gnu.org>
7 Date: 2002
8
9 This file is part of the GNUstep Base Library.
10
11 This library is free software; you can redistribute it and/or
12 modify it under the terms of the GNU Lesser General Public
13 License as published by the Free Software Foundation; either
14 version 2 of the License, or (at your option) any later version.
15
16 This library is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Library General Public License for more details.
20
21 You should have received a copy of the GNU Lesser General Public
22 License along with this library; if not, write to the Free
23 Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 Boston, MA 02111 USA.
25
26 AutogsdocSource: Additions/GSObjCRuntime.m
27
28 */
29
30 #ifndef __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE
31 #define __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE
32
33 #import "GSVersionMacros.h"
34 #import "GSConfig.h"
35
36 #include <stdio.h>
37
38 #if 1 || NeXT_RUNTIME
39 #include <objc/objc.h>
40 #include <objc/objc-class.h>
41 #include <objc/objc-runtime.h>
42 #ifndef _C_ATOM
43 #define _C_ATOM '%'
44 #endif
45 #define _F_CONST 0x01
46 #define _F_IN 0x01
47 #define _F_OUT 0x02
48 #define _F_INOUT 0x03
49 #define _F_BYCOPY 0x04
50 #define _F_ONEWAY 0x08
51 #define _C_CONST 'r'
52 #define _C_IN 'n'
53 #define _C_INOUT 'N'
54 #define _C_OUT 'o'
55 #define _C_BYCOPY 'O'
56 #define _C_ONEWAY 'V'
57 #else /* GNU Objective C Runtime */
58 #include <objc/objc.h>
59 #if defined (__GNU_LIBOBJC__)
60 #include <objc/runtime.h>
61 #else
62 #include <objc/objc-api.h>
63 #include <objc/encoding.h>
64 #endif
65 #endif
66
67 /*
68 * Hack for older compiler versions that don't have all defines
69 * needed in objc-api.h
70 */
71 #ifndef _C_LNG_LNG
72 #define _C_LNG_LNG 'q'
73 #endif
74 #ifndef _C_ULNG_LNG
75 #define _C_ULNG_LNG 'Q'
76 #endif
77
78 #if OBJC2RUNTIME
79 /* We have a real ObjC2 runtime.
80 */
81 #include <objc/runtime.h>
82 #else
83 /* We emulate an ObjC2 runtime.
84 */
85 #include <ObjectiveC2/objc/runtime.h>
86 #endif
87
88 #ifdef __cplusplus
89 extern "C" {
90 #endif
91
92 @class NSArray;
93 @class NSDictionary;
94 @class NSObject;
95 @class NSString;
96 @class NSValue;
97
98 #ifndef YES
99 #define YES 1
100 #endif
101 #ifndef NO
102 #define NO 0
103 #endif
104 #ifndef nil
105 #define nil 0
106 #endif
107
108 #if !defined(_C_CONST)
109 #define _C_CONST 'r'
110 #endif
111 #if !defined(_C_IN)
112 #define _C_IN 'n'
113 #endif
114 #if !defined(_C_INOUT)
115 #define _C_INOUT 'N'
116 #endif
117 #if !defined(_C_OUT)
118 #define _C_OUT 'o'
119 #endif
120 #if !defined(_C_BYCOPY)
121 #define _C_BYCOPY 'O'
122 #endif
123 #if !defined(_C_BYREF)
124 #define _C_BYREF 'R'
125 #endif
126 #if !defined(_C_ONEWAY)
127 #define _C_ONEWAY 'V'
128 #endif
129 #if !defined(_C_GCINVISIBLE)
130 #define _C_GCINVISIBLE '!'
131 #endif
132
133 /*
134 * Functions for accessing instance variables directly -
135 * We can copy an ivar into arbitrary data,
136 * Get the type encoding for a named ivar,
137 * and copy a value into an ivar.
138 */
139 GS_EXPORT BOOL
140 GSObjCFindVariable(id obj, const char *name,
141 const char **type, unsigned int *size, int *offset);
142
143 GS_EXPORT void
144 GSObjCGetVariable(id obj, int offset, unsigned int size, void *data);
145
146 GS_EXPORT void
147 GSObjCSetVariable(id obj, int offset, unsigned int size, const void *data);
148
149 GS_EXPORT NSArray *
150 GSObjCMethodNames(id obj, BOOL recurse);
151
152 GS_EXPORT NSArray *
153 GSObjCVariableNames(id obj, BOOL recurse);
154
155 /**
156 * <p>A Behavior can be seen as a "Protocol with an implementation" or a
157 * "Class without any instance variables". A key feature of behaviors
158 * is that they give a degree of multiple inheritance.
159 * </p>
160 * <p>Behavior methods, when added to a class, override the class's
161 * superclass methods, but not the class's methods.
162 * </p>
163 * <p>Whan a behavior class is added to a receiver class, not only are the
164 * methods defined in the behavior class added, but the methods from the
165 * behavior's class hierarchy are also added (unless already present).
166 * </p>
167 * <p>It's not the case that a class adding behaviors from another class
168 * must have "no instance vars". The receiver class just has to have the
169 * same layout as the behavior class (optionally with some additional
170 * ivars after those of the behavior class).
171 * </p>
172 * <p>This function provides Behaviors without adding any new syntax to
173 * the Objective C language. Simply define a class with the methods you
174 * want to add, then call this function with that class as the behavior
175 * argument.
176 * </p>
177 * <p>This function should be called in the +initialize method of the receiver.
178 * </p>
179 * <p>If you add several behaviors to a class, be aware that the order of
180 * the additions is significant.
181 * </p>
182 */
183 GS_EXPORT void
184 GSObjCAddClassBehavior(Class receiver, Class behavior);
185
186 /**
187 * <p>An Override can be seen as a "category implemented as a separate class
188 * and manually added to the receiver class under program control, rather
189 * than automatically added by the compiler/runtime.
190 * </p>
191 * <p>Override methods, when added to a receiver class, replace the class's
192 * class's methods of the same name (or are added if the class did not define
193 * methods with that name).
194 * </p>
195 * <p>It's not the case that a class adding overrides from another class
196 * must have "no instance vars". The receiver class just has to have the
197 * same layout as the override class (optionally with some additional
198 * ivars after those of the override class).
199 * </p>
200 * <p>This function provides overrides without adding any new syntax to
201 * the Objective C language. Simply define a class with the methods you
202 * want to add, then call this function with that class as the override
203 * argument.
204 * </p>
205 * <p>This function should usually be called in the +initialize method
206 * of the receiver.
207 * </p>
208 * <p>If you add several overrides to a class, be aware that the order of
209 * the additions is significant.
210 * </p>
211 */
212 GS_EXPORT void
213 GSObjCAddClassOverride(Class receiver, Class override);
214
215 /** Turn on (YES), off (NO) or test (-1) behavior debugging.
216 */
217 GS_EXPORT BOOL GSObjCBehaviorDebug(int setget);
218
219 GS_EXPORT NSValue *
220 GSObjCMakeClass(NSString *name, NSString *superName, NSDictionary *iVars);
221
222 GS_EXPORT void
223 GSObjCAddClasses(NSArray *classes);
224
225 /**
226 * Given a NULL terminated list of methods, add them to the class.<br />
227 * If the method already exists in a superclass, the new version overrides
228 * that one, but if the method already exists in the class itsself, the
229 * new one is quietly ignored (replace==NO) or replaced with the new
230 * version (if replace==YES).<br />
231 * To add class methods, cls should be the metaclass of the class to
232 * which the methods are being added.
233 */
234 GS_EXPORT void
235 GSObjCAddMethods(Class cls, Method *list, BOOL replace);
236
237 /*
238 * Functions for key-value encoding ... they access values in an object
239 * either by selector or directly, but do so using NSNumber for the
240 * scalar types of data.
241 */
242 GS_EXPORT id
243 GSObjCGetVal(NSObject *self, const char *key, SEL sel,
244 const char *type, unsigned size, int offset);
245
246 GS_EXPORT void
247 GSObjCSetVal(NSObject *self, const char *key, id val, SEL sel,
248 const char *type, unsigned size, int offset);
249
250 /*
251 * This section includes runtime functions
252 * to query and manipulate the ObjC runtime structures.
253 * These functions take care to not use ObjC code so
254 * that they can safely be used in +(void)load implementations
255 * where applicable.
256 */
257
258 /**
259 * Deprecated ... use objc_getClassList()
260 */
261 GS_EXPORT unsigned int
262 GSClassList(Class *buffer, unsigned int max, BOOL clearCache);
263
264 /**
265 * GSObjCClass() is deprecated ... use object_getClass()
266 */
267 GS_EXPORT Class GSObjCClass(id obj);
268
269 /**
270 * GSObjCSuper() is deprecated ... use class_getSuperclass()
271 */
272 GS_EXPORT Class GSObjCSuper(Class cls);
273
274 /**
275 * GSObjCIsInstance() is deprecated ... use object_getClass()
276 * in conjunction with class_isMetaClass()
277 */
278 GS_EXPORT BOOL GSObjCIsInstance(id obj);
279
280 /**
281 * GSObjCIsClass() is deprecated ... use object_getClass()
282 * in conjunction with class_isMetaClass()
283 */
284 GS_EXPORT BOOL GSObjCIsClass(Class cls);
285
286 /**
287 * Test to see if class inherits from another class
288 * The argument to this function must NOT be nil.
289 */
290 GS_EXPORT BOOL GSObjCIsKindOf(Class cls, Class other);
291
292 /**
293 * GSClassFromName() is deprecated ... use objc_lookUpClass()
294 */
295 GS_EXPORT Class GSClassFromName(const char *name);
296
297 /**
298 * GSNameFromClass() is deprecated ... use class_getName()
299 */
300 GS_EXPORT const char *GSNameFromClass(Class cls);
301
302 /**
303 * GSClassNameFromObject() is deprecated ... use object_getClass()
304 * in conjunction with class_getName()
305 */
306 GS_EXPORT const char *GSClassNameFromObject(id obj);
307
308 /**
309 * GSNameFromSelector() is deprecated ... use sel_getName()
310 */
311 GS_EXPORT const char *GSNameFromSelector(SEL sel);
312
313 /**
314 * GSSelectorFromName() is deprecated ... use sel_getUid()
315 */
316 GS_EXPORT SEL
317 GSSelectorFromName(const char *name);
318
319 /**
320 * Return the selector for the specified name and types.<br />
321 * Returns a nul pointer if the name is nul.<br />
322 * Creates a new selector if necessary.<br />
323 * Code must NOT rely on this providing a selector with type information.
324 */
325 GS_EXPORT SEL
326 GSSelectorFromNameAndTypes(const char *name, const char *types);
327
328 /**
329 * Return the type information from the specified selector.<br />
330 * May return a nul pointer if the selector was a nul pointer or if it
331 * was not typed (or if the runtime does not support typed selectors).<br />
332 * Code must NOT rely on this providing any type information.
333 */
334 GS_EXPORT const char *
335 GSTypesFromSelector(SEL sel);
336
337 /**
338 * Compare only the type information ignoring qualifiers, the frame layout
339 * and register markers. Unlike sel_types_match, this function also
340 * handles comparisons of types with and without any layout information.
341 */
342 GS_EXPORT BOOL
343 GSSelectorTypesMatch(const char *types1, const char *types2);
344
345 /** Takes full type information and skips forward to the actual type
346 * as specified in the _C_... constants.
347 */
348 GS_EXPORT const char *
349 GSSkipTypeQualifierAndLayoutInfo(const char *types);
350
351 /**
352 * Returns a protocol object with the corresponding name.
353 * This function searches the registered classes for any protocol
354 * with the supplied name. If one is found, it is cached in
355 * for future requests. If efficiency is a factor then use
356 * GSRegisterProtocol() to insert a protocol explicitly into the cache
357 * used by this function. If no protocol is found this function returns
358 * nil.
359 */
360 GS_EXPORT Protocol *
361 GSProtocolFromName(const char *name);
362
363 /**
364 * Registers proto in the cache used by GSProtocolFromName().
365 */
366 GS_EXPORT void
367 GSRegisterProtocol(Protocol *proto);
368
369 /**
370 * A variant of protocol_getMethodDescription which recursively searches
371 * parent protocols if the requested selector isn't found in the given
372 * protocol.
373 *
374 * Returns a {NULL, NULL} structure if the requested selector couldn't be
375 * found.
376 */
377 GS_EXPORT struct objc_method_description
378 GSProtocolGetMethodDescriptionRecursive(Protocol *aProtocol, SEL aSel, BOOL isRequired, BOOL isInstance);
379
380 /*
381 * Unfortunately the definition of the symbols
382 * 'Method(_t)', 'MethodList(_t)' and 'IVar(_t)'
383 * are incompatible between the GNU and NeXT/Apple runtimes.
384 * We introduce GSMethod, GSMethodList and GSIVar to allow portability.
385 */
386 typedef Method GSMethod;
387 typedef Ivar GSIVar;
388
389 /**
390 * Returns the pointer to the method structure
391 * for the selector in the specified class.
392 * Depending on searchInstanceMethods, this function searches
393 * either instance or class methods.
394 * Depending on searchSuperClassesm this function searches
395 * either the specified class only or also its superclasses.<br/>
396 * To obtain the implementation pointer IMP use returnValue->method_imp
397 * which should be safe across all runtimes.<br/>
398 * It should be safe to use this function in +load implementations.<br/>
399 * This function should currently (June 2004) be considered WIP.
400 * Please follow potential changes (Name, parameters, ...) closely until
401 * it stabilizes.
402 */
403 GS_EXPORT GSMethod
404 GSGetMethod(Class cls, SEL sel,
405 BOOL searchInstanceMethods,
406 BOOL searchSuperClasses);
407
408 /**
409 * Deprecated .. does nothing.
410 */
411 GS_EXPORT void
412 GSFlushMethodCacheForClass (Class cls);
413
414 /**
415 * Deprecated .. use class_getInstanceVariable()
416 */
417 GS_EXPORT GSIVar
418 GSCGetInstanceVariableDefinition(Class cls, const char *name);
419
420 /**
421 * Deprecated .. use class_getInstanceVariable()
422 */
423 GS_EXPORT GSIVar
424 GSObjCGetInstanceVariableDefinition(Class cls, NSString *name);
425
426 /**
427 * GSObjCVersion() is deprecated ... use class_getVersion()
428 */
429 GS_EXPORT int GSObjCVersion(Class cls);
430
431 /**
432 * Quickly return autoreleased data storage area.
433 */
434 GS_EXPORT void *
435 GSAutoreleasedBuffer(unsigned size);
436
437 /**
438 * <p>Prints a message to fptr using the format string provided and any
439 * additional arguments. The format string is interpreted as by
440 * the NSString formatted initialisers, and understands the '%@' syntax
441 * for printing an object.
442 * </p>
443 * <p>The data is written to the file pointer in the default CString
444 * encoding if possible, as a UTF8 string otherwise.
445 * </p>
446 * <p>This function is recommended for printing general log messages.
447 * For debug messages use NSDebugLog() and friends. For error logging
448 * use NSLog(), and for warnings you might consider NSWarnLog().
449 * </p>
450 */
451 GS_EXPORT BOOL
452 GSPrintf (FILE *fptr, NSString *format, ...);
453
454
455
456 GS_EXPORT NSArray *
457 GSObjCAllSubclassesOfClass(Class cls);
458
459 GS_EXPORT NSArray *
460 GSObjCDirectSubclassesOfClass(Class cls);
461
462 /** Function to change the class of the specified instance to newClass.
463 * This handles memory debugging issues in GNUstep-base and also
464 * deals with class finalisation issues in a garbage collecting
465 * environment, so you should use this function rather than attempting
466 * to swizzle class pointers directly.
467 */
468 GS_EXPORT void
469 GSClassSwizzle(id instance, Class newClass);
470
471 #if !defined(GS_GNUSTEP_V) || (GS_GNUSTEP_V >= GS_API_ANY && GS_GNUSTEP_V < 011500)
472 //GS_API_VERSION(GS_API_ANY,011500)
473
474 GS_EXPORT const char *
475 GSLastErrorStr(long error_id) GS_DEPRECATED_FUNC;
476
477 #endif
478
479
480
481 #ifndef GS_MAX_OBJECTS_FROM_STACK
482 /**
483 * The number of objects to try to get from varargs into an array on
484 * the stack ... if there are more than this, use the heap.
485 * NB. This MUST be a multiple of 2
486 */
487 #define GS_MAX_OBJECTS_FROM_STACK 128
488 #endif
489
490 /**
491 * <p>This is a macro designed to minimise the use of memory allocation and
492 * deallocation when you need to work with a vararg list of objects.<br />
493 * The objects are unpacked from the vararg list into two 'C' arrays and
494 * then a code fragment you specify is able to make use of them before
495 * that 'C' array is destroyed.
496 * </p>
497 * <p>The firstObject argument is the name of the formal parameter in your
498 * method or function which precedes the ', ...' denoting variable args.
499 * </p>
500 * <p>The code argument is a piece of objective-c code to be executed to
501 * make use of the objects stored in the 'C' arrays.<br />
502 * When this code is called the unsigned integer '__count' will contain the
503 * number of objects unpacked, the pointer '__objects' will point to
504 * the first object in each pair, and the pointer '__pairs' will point
505 * to an array containing the second halves of the pairs of objects
506 * whose first halves are in '__objects'.<br />
507 * This lets you pack a list of the form 'key, value, key, value, ...'
508 * into an array of keys and an array of values.
509 * </p>
510 */
511 #define GS_USEIDPAIRLIST(firstObject, code...) ({\
512 va_list __ap; \
513 unsigned int __max = GS_MAX_OBJECTS_FROM_STACK; \
514 unsigned int __count = 0; \
515 id __buf[__max]; \
516 id *__objects = __buf; \
517 id *__pairs = &__objects[__max/2]; \
518 id __obj = firstObject; \
519 va_start(__ap, firstObject); \
520 while (__obj != nil && __count < __max) \
521 { \
522 if ((__count % 2) == 0) \
523 { \
524 __objects[__count/2] = __obj; \
525 } \
526 else \
527 { \
528 __pairs[__count/2] = __obj; \
529 } \
530 __obj = va_arg(__ap, id); \
531 if (++__count == __max) \
532 { \
533 while (__obj != nil) \
534 { \
535 __count++; \
536 __obj = va_arg(__ap, id); \
537 } \
538 } \
539 } \
540 if ((__count % 2) == 1) \
541 { \
542 __pairs[__count/2] = nil; \
543 __count++; \
544 } \
545 va_end(__ap); \
546 if (__count > __max) \
547 { \
548 unsigned int __tmp; \
549 __objects = (id*)malloc(__count*sizeof(id)); \
550 __pairs = &__objects[__count/2]; \
551 __objects[0] = firstObject; \
552 va_start(__ap, firstObject); \
553 for (__tmp = 1; __tmp < __count; __tmp++) \
554 { \
555 if ((__tmp % 2) == 0) \
556 { \
557 __objects[__tmp/2] = va_arg(__ap, id); \
558 } \
559 else \
560 { \
561 __pairs[__tmp/2] = va_arg(__ap, id); \
562 } \
563 } \
564 va_end(__ap); \
565 } \
566 code; \
567 if (__objects != __buf) free(__objects); \
568 })
569
570 /**
571 * <p>This is a macro designed to minimise the use of memory allocation and
572 * deallocation when you need to work with a vararg list of objects.<br />
573 * The objects are unpacked from the vararg list into a 'C' array and
574 * then a code fragment you specify is able to make use of them before
575 * that 'C' array is destroyed.
576 * </p>
577 * <p>The firstObject argument is the name of the formal parameter in your
578 * method or function which precedes the ', ...' denoting variable args.
579 * </p>
580 * <p>The code argument is a piece of objective-c code to be executed to
581 * make use of the objects stored in the 'C' array.<br />
582 * When this code is called the unsigned integer '__count' will contain the
583 * number of objects unpacked, and the pointer '__objects' will point to
584 * the unpacked objects, ie. firstObject followed by the vararg arguments
585 * up to (but not including) the first nil.
586 * </p>
587 */
588 #define GS_USEIDLIST(firstObject, code...) ({\
589 va_list __ap; \
590 unsigned int __max = GS_MAX_OBJECTS_FROM_STACK; \
591 unsigned int __count = 0; \
592 id __buf[__max]; \
593 id *__objects = __buf; \
594 id __obj = firstObject; \
595 va_start(__ap, firstObject); \
596 while (__obj != nil && __count < __max) \
597 { \
598 __objects[__count] = __obj; \
599 __obj = va_arg(__ap, id); \
600 if (++__count == __max) \
601 { \
602 while (__obj != nil) \
603 { \
604 __count++; \
605 __obj = va_arg(__ap, id); \
606 } \
607 } \
608 } \
609 va_end(__ap); \
610 if (__count > __max) \
611 { \
612 unsigned int __tmp; \
613 __objects = (id*)NSZoneMalloc(NSDefaultMallocZone(),__count*sizeof(id)); \
614 va_start(__ap, firstObject); \
615 __objects[0] = firstObject; \
616 for (__tmp = 1; __tmp < __count; __tmp++) \
617 { \
618 __objects[__tmp] = va_arg(__ap, id); \
619 } \
620 va_end(__ap); \
621 } \
622 code; \
623 if (__objects != __buf) NSZoneFree (NSDefaultMallocZone(),__objects); \
624 })
625
626
627 #ifdef __cplusplus
628 }
629 #endif
630
631 #endif /* __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE */