1
/** Interface to ObjC runtime for GNUStep
2
Copyright (C) 1995, 1997, 2000, 2002, 2003 Free Software Foundation, Inc.
4
Written by: Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
6
Written by: Richard Frith-Macdonald <rfm@gnu.org>
9
This file is part of the GNUstep Base Library.
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.
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.
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,
26
AutogsdocSource: Additions/GSObjCRuntime.m
30
#ifndef __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE
31
#define __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE
33
#import <GNUstepBase/GSVersionMacros.h>
34
#import <GNUstepBase/GSConfig.h>
37
#include <objc/objc.h>
40
/* We have a real ObjC2 runtime.
42
#include <objc/runtime.h>
44
/* We emulate an ObjC2 runtime.
46
#include <objc/objc-api.h>
47
#include <ObjectiveC2/runtime.h>
72
#if !defined(_C_CONST)
78
#if !defined(_C_INOUT)
84
#if !defined(_C_BYCOPY)
87
#if !defined(_C_BYREF)
90
#if !defined(_C_ONEWAY)
93
#if !defined(_C_GCINVISIBLE)
94
#define _C_GCINVISIBLE '!'
98
* Functions for accessing instance variables directly -
99
* We can copy an ivar into arbitrary data,
100
* Get the type encoding for a named ivar,
101
* and copy a value into an ivar.
104
GSObjCFindVariable(id obj, const char *name,
105
const char **type, unsigned int *size, int *offset);
108
GSObjCGetVariable(id obj, int offset, unsigned int size, void *data);
111
GSObjCSetVariable(id obj, int offset, unsigned int size, const void *data);
114
GSObjCMethodNames(id obj, BOOL recurse);
117
GSObjCVariableNames(id obj, BOOL recurse);
120
* <p>A Behavior can be seen as a "Protocol with an implementation" or a
121
* "Class without any instance variables". A key feature of behaviors
122
* is that they give a degree of multiple inheritance.
124
* <p>Behavior methods, when added to a class, override the class's
125
* superclass methods, but not the class's methods.
127
* <p>Whan a behavior class is added to a receiver class, not only are the
128
* methods defined in the behavior class added, but the methods from the
129
* behavior's class hierarchy are also added (unless already present).
131
* <p>It's not the case that a class adding behaviors from another class
132
* must have "no instance vars". The receiver class just has to have the
133
* same layout as the behavior class (optionally with some additional
134
* ivars after those of the behavior class).
136
* <p>This function provides Behaviors without adding any new syntax to
137
* the Objective C language. Simply define a class with the methods you
138
* want to add, then call this function with that class as the behavior
141
* <p>This function should be called in the +initialize method of the receiver.
143
* <p>If you add several behaviors to a class, be aware that the order of
144
* the additions is significant.
148
GSObjCAddClassBehavior(Class receiver, Class behavior);
151
* <p>An Override can be seen as a "category implemented as a separate class
152
* and manually added to the receiver class under program control, rather
153
* than automatically added by the compiler/runtime.
155
* <p>Override methods, when added to a receiver class, replace the class's
156
* class's methods of the same name (or are added if the class did not define
157
* methods with that name).
159
* <p>It's not the case that a class adding overrides from another class
160
* must have "no instance vars". The receiver class just has to have the
161
* same layout as the override class (optionally with some additional
162
* ivars after those of the override class).
164
* <p>This function provides overrides without adding any new syntax to
165
* the Objective C language. Simply define a class with the methods you
166
* want to add, then call this function with that class as the override
169
* <p>This function should usually be called in the +initialize method
172
* <p>If you add several overrides to a class, be aware that the order of
173
* the additions is significant.
177
GSObjCAddClassOverride(Class receiver, Class override);
179
/** Turn on (YES), off (NO) or test (-1) behavior debugging.
181
GS_EXPORT BOOL GSObjCBehaviorDebug(int setget);
184
GSObjCMakeClass(NSString *name, NSString *superName, NSDictionary *iVars);
187
GSObjCAddClasses(NSArray *classes);
190
* Given a NULL terminated list of methods, add them to the class.<br />
191
* If the method already exists in a superclass, the new version overrides
192
* that one, but if the method already exists in the class itsself, the
193
* new one is quietly ignored (replace==NO) or replaced with the new
194
* version (if replace==YES).<br />
195
* To add class methods, cls should be the metaclass of the class to
196
* which the methods are being added.
199
GSObjCAddMethods(Class cls, Method *list, BOOL replace);
202
* Functions for key-value encoding ... they access values in an object
203
* either by selector or directly, but do so using NSNumber for the
204
* scalar types of data.
207
GSObjCGetVal(NSObject *self, const char *key, SEL sel,
208
const char *type, unsigned size, int offset);
211
GSObjCSetVal(NSObject *self, const char *key, id val, SEL sel,
212
const char *type, unsigned size, int offset);
215
* This section includes runtime functions
216
* to query and manipulate the ObjC runtime structures.
217
* These functions take care to not use ObjC code so
218
* that they can safely be used in +(void)load implementations
223
* Deprecated ... use objc_getClassList()
225
GS_EXPORT unsigned int
226
GSClassList(Class *buffer, unsigned int max, BOOL clearCache);
229
* GSObjCClass() is deprecated ... use object_getClass()
231
GS_EXPORT Class GSObjCClass(id obj);
234
* GSObjCSuper() is deprecated ... use class_getSuperclass()
236
GS_EXPORT Class GSObjCSuper(Class cls);
239
* GSObjCIsInstance() is deprecated ... use object_getClass()
240
* in conjunction with class_isMetaClass()
242
GS_EXPORT BOOL GSObjCIsInstance(id obj);
245
* GSObjCIsClass() is deprecated ... use object_getClass()
246
* in conjunction with class_isMetaClass()
248
GS_EXPORT BOOL GSObjCIsClass(Class cls);
251
* Test to see if class inherits from another class
252
* The argument to this function must NOT be nil.
254
GS_EXPORT BOOL GSObjCIsKindOf(Class cls, Class other);
257
* GSClassFromName() is deprecated ... use objc_lookUpClass()
259
GS_EXPORT Class GSClassFromName(const char *name);
262
* GSNameFromClass() is deprecated ... use class_getName()
264
GS_EXPORT const char *GSNameFromClass(Class cls);
267
* GSClassNameFromObject() is deprecated ... use object_getClass()
268
* in conjunction with class_getName()
270
GS_EXPORT const char *GSClassNameFromObject(id obj);
273
* GSNameFromSelector() is deprecated ... use sel_getName()
275
GS_EXPORT const char *GSNameFromSelector(SEL sel);
278
* GSSelectorFromName() is deprecated ... use sel_getUid()
281
GSSelectorFromName(const char *name);
284
* Return the selector for the specified name and types.<br />
285
* Returns a nul pointer if the name is nul.<br />
286
* Creates a new selector if necessary.<br />
287
* Code must NOT rely on this providing a selector with type information.
290
GSSelectorFromNameAndTypes(const char *name, const char *types);
293
* Return the type information from the specified selector.<br />
294
* May return a nul pointer if the selector was a nul pointer or if it
295
* was not typed (or if the runtime does not support typed selectors).<br />
296
* Code must NOT rely on this providing any type information.
298
GS_EXPORT const char *
299
GSTypesFromSelector(SEL sel);
302
* Compare only the type information ignoring qualifiers, the frame layout
303
* and register markers. Unlike sel_types_match, this function also
304
* handles comparisons of types with and without any layout information.
307
GSSelectorTypesMatch(const char *types1, const char *types2);
310
* Returns a protocol object with the corresponding name.
311
* This function searches the registered classes for any protocol
312
* with the supplied name. If one is found, it is cached in
313
* for future requests. If efficiency is a factor then use
314
* GSRegisterProtocol() to insert a protocol explicitly into the cache
315
* used by this function. If no protocol is found this function returns
319
GSProtocolFromName(const char *name);
322
* Registers proto in the cache used by GSProtocolFromName().
325
GSRegisterProtocol(Protocol *proto);
328
* A variant of protocol_getMethodDescription which recursively searches
329
* parent protocols if the requested selector isn't found in the given
332
* Returns a {NULL, NULL} structure if the requested selector couldn't be
335
GS_EXPORT struct objc_method_description
336
GSProtocolGetMethodDescriptionRecursive(Protocol *aProtocol, SEL aSel, BOOL isRequired, BOOL isInstance);
339
* Unfortunately the definition of the symbols
340
* 'Method(_t)', 'MethodList(_t)' and 'IVar(_t)'
341
* are incompatible between the GNU and NeXT/Apple runtimes.
342
* We introduce GSMethod, GSMethodList and GSIVar to allow portability.
344
typedef Method GSMethod;
348
* Returns the pointer to the method structure
349
* for the selector in the specified class.
350
* Depending on searchInstanceMethods, this function searches
351
* either instance or class methods.
352
* Depending on searchSuperClassesm this function searches
353
* either the specified class only or also its superclasses.<br/>
354
* To obtain the implementation pointer IMP use returnValue->method_imp
355
* which should be safe across all runtimes.<br/>
356
* It should be safe to use this function in +load implementations.<br/>
357
* This function should currently (June 2004) be considered WIP.
358
* Please follow potential changes (Name, parameters, ...) closely until
362
GSGetMethod(Class cls, SEL sel,
363
BOOL searchInstanceMethods,
364
BOOL searchSuperClasses);
367
* Deprecated .. does nothing.
370
GSFlushMethodCacheForClass (Class cls);
373
* Deprecated .. use class_getInstanceVariable()
376
GSCGetInstanceVariableDefinition(Class cls, const char *name);
379
* Deprecated .. use class_getInstanceVariable()
382
GSObjCGetInstanceVariableDefinition(Class cls, NSString *name);
385
* GSObjCVersion() is deprecated ... use class_getVersion()
387
GS_EXPORT int GSObjCVersion(Class cls);
390
* Quickly return autoreleased data storage area.
393
GSAutoreleasedBuffer(unsigned size);
396
* <p>Prints a message to fptr using the format string provided and any
397
* additional arguments. The format string is interpreted as by
398
* the NSString formatted initialisers, and understands the '%@' syntax
399
* for printing an object.
401
* <p>The data is written to the file pointer in the default CString
402
* encoding if possible, as a UTF8 string otherwise.
404
* <p>This function is recommended for printing general log messages.
405
* For debug messages use NSDebugLog() and friends. For error logging
406
* use NSLog(), and for warnings you might consider NSWarnLog().
410
GSPrintf (FILE *fptr, NSString *format, ...);
415
GSObjCAllSubclassesOfClass(Class cls);
418
GSObjCDirectSubclassesOfClass(Class cls);
420
/** Function to change the class of the specified instance to newClass.
421
* This handles memory debugging issues in GNUstep-base and also
422
* deals with class finalisation issues in a garbage collecting
423
* environment, so you should use this function rather than attempting
424
* to swizzle class pointers directly.
427
GSClassSwizzle(id instance, Class newClass);
429
#if GS_API_VERSION(GS_API_ANY,011500)
431
GS_EXPORT const char *
432
GSLastErrorStr(long error_id) GS_DEPRECATED_FUNC;
438
#ifndef GS_MAX_OBJECTS_FROM_STACK
440
* The number of objects to try to get from varargs into an array on
441
* the stack ... if there are more than this, use the heap.
442
* NB. This MUST be a multiple of 2
444
#define GS_MAX_OBJECTS_FROM_STACK 128
448
* <p>This is a macro designed to minimise the use of memory allocation and
449
* deallocation when you need to work with a vararg list of objects.<br />
450
* The objects are unpacked from the vararg list into two 'C' arrays and
451
* then a code fragment you specify is able to make use of them before
452
* that 'C' array is destroyed.
454
* <p>The firstObject argument is the name of the formal parameter in your
455
* method or function which precedes the ', ...' denoting variable args.
457
* <p>The code argument is a piece of objective-c code to be executed to
458
* make use of the objects stored in the 'C' arrays.<br />
459
* When this code is called the unsigned integer '__count' will contain the
460
* number of objects unpacked, the pointer '__objects' will point to
461
* the first object in each pair, and the pointer '__pairs' will point
462
* to an array containing the second halves of the pairs of objects
463
* whose first halves are in '__objects'.<br />
464
* This lets you pack a list of the form 'key, value, key, value, ...'
465
* into an array of keys and an array of values.
468
#define GS_USEIDPAIRLIST(firstObject, code...) ({\
470
unsigned int __max = GS_MAX_OBJECTS_FROM_STACK; \
471
unsigned int __count = 0; \
473
id *__objects = __buf; \
474
id *__pairs = &__objects[__max/2]; \
475
id __obj = firstObject; \
476
va_start(__ap, firstObject); \
477
while (__obj != nil && __count < __max) \
479
if ((__count % 2) == 0) \
481
__objects[__count/2] = __obj; \
485
__pairs[__count/2] = __obj; \
487
__obj = va_arg(__ap, id); \
488
if (++__count == __max) \
490
while (__obj != nil) \
493
__obj = va_arg(__ap, id); \
497
if ((__count % 2) == 1) \
499
__pairs[__count/2] = nil; \
503
if (__count > __max) \
505
unsigned int __tmp; \
506
__objects = (id*)malloc(__count*sizeof(id)); \
507
__pairs = &__objects[__count/2]; \
508
__objects[0] = firstObject; \
509
va_start(__ap, firstObject); \
510
for (__tmp = 1; __tmp < __count; __tmp++) \
512
if ((__tmp % 2) == 0) \
514
__objects[__tmp/2] = va_arg(__ap, id); \
518
__pairs[__tmp/2] = va_arg(__ap, id); \
524
if (__objects != __buf) free(__objects); \
528
* <p>This is a macro designed to minimise the use of memory allocation and
529
* deallocation when you need to work with a vararg list of objects.<br />
530
* The objects are unpacked from the vararg list into a 'C' array and
531
* then a code fragment you specify is able to make use of them before
532
* that 'C' array is destroyed.
534
* <p>The firstObject argument is the name of the formal parameter in your
535
* method or function which precedes the ', ...' denoting variable args.
537
* <p>The code argument is a piece of objective-c code to be executed to
538
* make use of the objects stored in the 'C' array.<br />
539
* When this code is called the unsigned integer '__count' will contain the
540
* number of objects unpacked, and the pointer '__objects' will point to
541
* the unpacked objects, ie. firstObject followed by the vararg arguments
542
* up to (but not including) the first nil.
545
#define GS_USEIDLIST(firstObject, code...) ({\
547
unsigned int __max = GS_MAX_OBJECTS_FROM_STACK; \
548
unsigned int __count = 0; \
550
id *__objects = __buf; \
551
id __obj = firstObject; \
552
va_start(__ap, firstObject); \
553
while (__obj != nil && __count < __max) \
555
__objects[__count] = __obj; \
556
__obj = va_arg(__ap, id); \
557
if (++__count == __max) \
559
while (__obj != nil) \
562
__obj = va_arg(__ap, id); \
567
if (__count > __max) \
569
unsigned int __tmp; \
570
__objects = (id*)NSZoneMalloc(NSDefaultMallocZone(),__count*sizeof(id)); \
571
va_start(__ap, firstObject); \
572
__objects[0] = firstObject; \
573
for (__tmp = 1; __tmp < __count; __tmp++) \
575
__objects[__tmp] = va_arg(__ap, id); \
580
if (__objects != __buf) NSZoneFree (NSDefaultMallocZone(),__objects); \
588
#endif /* __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE */
added
removed
Headers/GNUstepBase/GSObjCRuntime.h
