runtime/objc-runtime.h

   1 /*
   2  * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26  *      objc-runtime.h
  27  *      Copyright 1988-1996, NeXT Software, Inc.
  28  */
  29
  30 #ifndef _OBJC_RUNTIME_H_
  31 #define _OBJC_RUNTIME_H_
  32
  33 #import <stdarg.h>
  34 #import <AvailabilityMacros.h>
  35 #import <objc/objc.h>
  36 #import <objc/objc-class.h>
  37
  38 #if !defined(AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER)
  39     /* For 10.2 compatibility */
  40 #   define AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER
  41 #endif
  42
  43 typedef struct objc_symtab *Symtab;
  44
  45 struct objc_symtab {
  46         unsigned long   sel_ref_cnt;
  47         SEL             *refs;
  48         unsigned short  cls_def_cnt;
  49         unsigned short  cat_def_cnt;
  50         void            *defs[1];       /* variable size */
  51 };
  52
  53 typedef struct objc_module *Module;
  54
  55 struct objc_module {
  56         unsigned long   version;
  57         unsigned long   size;
  58         const char      *name;
  59         Symtab          symtab;
  60 };
  61
  62 struct objc_super {
  63         id receiver;
  64 #ifndef __cplusplus
  65         Class class;
  66 #else
  67         Class super_class;
  68 #endif
  69 };
  70
  71 /*
  72  * Messaging Primitives (prototypes)
  73  */
  74
  75 OBJC_EXPORT id objc_getClass(const char *name);
  76 OBJC_EXPORT id objc_getMetaClass(const char *name);
  77 OBJC_EXPORT id objc_msgSend(id self, SEL op, ...);
  78 OBJC_EXPORT id objc_msgSendSuper(struct objc_super *super, SEL op, ...);
  79
  80
  81 /* Floating-point-returning Messaging Primitives (prototypes)
  82  *
  83  * On some platforms, the ABI for functions returning a floating-point
  84  * value is incompatible with that for functions returning an integral type.
  85  * objc_msgSend_fpret must be used for these.
  86  *
  87  * ppc: objc_msgSend_fpret not used
  88  * ppc64: objc_msgSend_fpret not used
  89  * i386: objc_msgSend_fpret REQUIRED
  90  *
  91  * For `float` or `long double` return types, cast the function
  92  * to an appropriate function pointer type first.
  93  */
  94
  95 #ifdef __i386__
  96 OBJC_EXPORT double objc_msgSend_fpret(id self, SEL op, ...);
  97 #endif
  98
  99
 100 /* Struct-returning Messaging Primitives (prototypes)
 101  *
 102  * For historical reasons, the prototypes for the struct-returning
 103  * messengers are unusual. The portable, correct way to call these functions
 104  * is to cast them to your desired return type first.
 105  *
 106  * For example, `NSRect result = [myNSView frame]` could be written as:
 107  *   NSRect (*msgSend_stret_fn)(id, SEL, ...) = (NSRect(*)(id, SEL, ...))objc_msgSend_stret;
 108  *   NSRect result = (*msgSend_stret_fn)(myNSView, @selector(frame));
 109  * or, without the function pointer:
 110  *   NSRect result = (*(NSRect(*)(id, SEL, ...))objc_msgSend_stret)(myNSView, @selector(frame));
 111  *
 112  * BE WARNED that these prototypes have changed in the past and will change
 113  * in the future. Code that uses a cast like the example above will be
 114  * unaffected.
 115  */
 116
 117 #if defined(__cplusplus)
 118   OBJC_EXPORT id objc_msgSend_stret(id self, SEL op, ...);
 119   OBJC_EXPORT id objc_msgSendSuper_stret(struct objc_super *super, SEL op, ...);
 120 #else
 121   OBJC_EXPORT void objc_msgSend_stret(void * stretAddr, id self, SEL op, ...);
 122   OBJC_EXPORT void objc_msgSendSuper_stret(void * stretAddr, struct objc_super *super, SEL op, ...);
 123 #endif
 124
 125
 126 /* Forwarding */
 127
 128 /* Note that objc_msgSendv_stret() does not return a structure type,
 129  * and should not be cast to do so. This is unlike objc_msgSend_stret()
 130  * and objc_msgSendSuper_stret().
 131  */
 132
 133 OBJC_EXPORT id objc_msgSendv(id self, SEL op, unsigned arg_size, marg_list arg_frame);
 134 OBJC_EXPORT void objc_msgSendv_stret(void * stretAddr, id self, SEL op, unsigned arg_size, marg_list arg_frame);
 135 #ifdef __i386__
 136 OBJC_EXPORT double objc_msgSendv_fpret(id self, SEL op, unsigned arg_size, marg_list arg_frame);
 137 #endif
 138
 139
 140 /*
 141     getting all the classes in the application...
 142
 143     int objc_getClassList(buffer, bufferLen)
 144         classes is an array of Class values (which are pointers)
 145                 which will be filled by the function; if this
 146                 argument is NULL, no copying is done, only the
 147                 return value is returned
 148         bufferLen is the number of Class values the given buffer
 149                 can hold; if the buffer is not large enough to
 150                 hold all the classes, the buffer is filled to
 151                 the indicated capacity with some arbitrary subset
 152                 of the known classes, which could be different
 153                 from call to call
 154         returns the number of classes, which is the number put
 155                 in the buffer if the buffer was large enough,
 156                 or the length the buffer should have been
 157
 158     int numClasses = 0, newNumClasses = objc_getClassList(NULL, 0);
 159     Class *classes = NULL;
 160     while (numClasses < newNumClasses) {
 161         numClasses = newNumClasses;
 162         classes = realloc(classes, sizeof(Class) * numClasses);
 163         newNumClasses = objc_getClassList(classes, numClasses);
 164     }
 165     // now, can use the classes list; if NULL, there are no classes
 166     free(classes);
 167
 168 */
 169 OBJC_EXPORT int objc_getClassList(Class *buffer, int bufferLen);
 170
 171 #define OBSOLETE_OBJC_GETCLASSES 1
 172 #if OBSOLETE_OBJC_GETCLASSES
 173 OBJC_EXPORT void *objc_getClasses(void);
 174 #endif
 175
 176 OBJC_EXPORT id objc_lookUpClass(const char *name);
 177 OBJC_EXPORT id objc_getRequiredClass(const char *name);
 178 OBJC_EXPORT void objc_addClass(Class myClass);
 179
 180 /* customizing the error handling for objc_getClass/objc_getMetaClass */
 181
 182 OBJC_EXPORT void objc_setClassHandler(int (*)(const char *));
 183
 184 /* Making the Objective-C runtime thread safe. */
 185 OBJC_EXPORT void objc_setMultithreaded (BOOL flag);
 186
 187 /* overriding the default object allocation and error handling routines */
 188
 189 OBJC_EXPORT id  (*_alloc)(Class, unsigned int);
 190 OBJC_EXPORT id  (*_copy)(id, unsigned int);
 191 OBJC_EXPORT id  (*_realloc)(id, unsigned int);
 192 OBJC_EXPORT id  (*_dealloc)(id);
 193 OBJC_EXPORT id  (*_zoneAlloc)(Class, unsigned int, void *);
 194 OBJC_EXPORT id  (*_zoneRealloc)(id, unsigned int, void *);
 195 OBJC_EXPORT id  (*_zoneCopy)(id, unsigned int, void *);
 196
 197 OBJC_EXPORT void        (*_error)(id, const char *, va_list);
 198
 199
 200 #endif /* _OBJC_RUNTIME_H_ */