gcc/objc/objc-api.h

   1 /* GNU Objective-C Runtime API.
   2    Copyright (C) 1993, 1995 Free Software Foundation, Inc.
   3
   4 This file is part of GNU CC.
   5
   6 GNU CC is free software; you can redistribute it and/or modify it
   7 under the terms of the GNU General Public License as published by the
   8 Free Software Foundation; either version 2, or (at your option) any
   9 later version.
  10
  11 GNU CC is distributed in the hope that it will be useful, but WITHOUT
  12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
  14 License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU CC; see the file COPYING.  If not, write to
  18 the Free Software Foundation, 59 Temple Place - Suite 330,
  19 Boston, MA 02111-1307, USA.  */
  20
  21 /* As a special exception, if you link this library with files compiled
  22    with GCC to produce an executable, this does not cause the resulting
  23    executable to be covered by the GNU General Public License.  This
  24    exception does not however invalidate any other reasons why the
  25    executable file might be covered by the GNU General Public License. */
  26
  27 #ifndef __objc_api_INCLUDE_GNU
  28 #define __objc_api_INCLUDE_GNU
  29
  30 #include "objc/objc.h"
  31 #include "objc/hash.h"
  32 #include <stdio.h>
  33
  34 /* For functions which return Method_t */
  35 #define METHOD_NULL     (Method_t)0
  36                                                 /* Boolean typedefs */
  37 /*
  38 ** Method descriptor returned by introspective Object methods.
  39 ** This is really just the first part of the more complete objc_method
  40 ** structure defined below and used internally by the runtime.
  41 */
  42 struct objc_method_description
  43 {
  44     SEL name;                   /* this is a selector, not a string */
  45     char *types;                /* type encoding */
  46 };
  47
  48 /* Filer types used to describe Ivars and Methods.  */
  49 #define _C_ID       '@'
  50 #define _C_CLASS    '#'
  51 #define _C_SEL      ':'
  52 #define _C_CHR      'c'
  53 #define _C_UCHR     'C'
  54 #define _C_SHT      's'
  55 #define _C_USHT     'S'
  56 #define _C_INT      'i'
  57 #define _C_UINT     'I'
  58 #define _C_LNG      'l'
  59 #define _C_ULNG     'L'
  60 #define _C_FLT      'f'
  61 #define _C_DBL      'd'
  62 #define _C_BFLD     'b'
  63 #define _C_VOID     'v'
  64 #define _C_UNDEF    '?'
  65 #define _C_PTR      '^'
  66 #define _C_CHARPTR  '*'
  67 #define _C_ATOM     '%'
  68 #define _C_ARY_B    '['
  69 #define _C_ARY_E    ']'
  70 #define _C_UNION_B  '('
  71 #define _C_UNION_E  ')'
  72 #define _C_STRUCT_B '{'
  73 #define _C_STRUCT_E '}'
  74
  75
  76
  77 /*
  78 ** Set this variable nonzero to print a line describing each
  79 ** message that is sent.  (this is currently disabled)
  80 */
  81 extern BOOL objc_trace;
  82
  83
  84 /*
  85 ** Whereas a Module (defined further down) is the root (typically) of a file,
  86 ** a Symtab is the root of the class and category definitions within the
  87 ** module.
  88 **
  89 ** A Symtab contains a variable length array of pointers to classes and
  90 ** categories  defined in the module.
  91 */
  92 typedef struct objc_symtab {
  93   unsigned long sel_ref_cnt;                     /* Unknown. */
  94   SEL        refs;                              /* Unknown. */
  95   unsigned short cls_def_cnt;                   /* Number of classes compiled
  96                                                   (defined) in the module. */
  97   unsigned short cat_def_cnt;                   /* Number of categories
  98                                                   compiled (defined) in the
  99                                                   module. */
 100   void      *defs[1];                           /* Variable array of pointers.
 101                                                   cls_def_cnt of type Class
 102                                                   followed by cat_def_cnt of
 103                                                   type Category_t. */
 104 } Symtab,   *Symtab_t;
 105
 106
 107 /* For every class which happens to have statically allocated instances in
 108    this module, one OBJC_STATIC_INSTANCES is allocated by the compiler.
 109    INSTANCES is NULL terminated and points to all statically allocated
 110    instances of this class.  */
 111 struct objc_static_instances
 112 {
 113   char *class_name;
 114   id instances[0];
 115 };
 116
 117 /*
 118 ** The compiler generates one of these structures for each module that
 119 ** composes the executable (eg main.m).
 120 **
 121 ** This data structure is the root of the definition tree for the module.
 122 **
 123 ** A collect program runs between ld stages and creates a ObjC ctor array.
 124 ** That array holds a pointer to each module structure of the executable.
 125 */
 126 typedef struct objc_module {
 127   unsigned long version;                        /* Compiler revision. */
 128   unsigned long size;                           /* sizeof(Module). */
 129   const char* name;                             /* Name of the file where the
 130                                                   module was generated.   The
 131                                                   name includes the path. */
 132
 133   /* Pointer to a NULL terminated array of objc_static_instances.  */
 134   struct objc_static_instances **statics;
 135
 136   Symtab_t    symtab;                           /* Pointer to the Symtab of
 137                                                   the module.  The Symtab
 138                                                   holds an array of pointers to
 139                                                   the classes and categories
 140                                                   defined in the module. */
 141 } Module, *Module_t;
 142
 143
 144 /*
 145 ** The compiler generates one of these structures for a class that has
 146 ** instance variables defined in its specification.
 147 */
 148 typedef struct objc_ivar* Ivar_t;
 149 typedef struct objc_ivar_list {
 150   int   ivar_count;                             /* Number of structures (Ivar)
 151                                                   contained in the list.  One
 152                                                   structure per instance
 153                                                   variable defined in the
 154                                                   class. */
 155   struct objc_ivar {
 156     const char* ivar_name;                      /* Name of the instance
 157                                                   variable as entered in the
 158                                                   class definition. */
 159     const char* ivar_type;                      /* Description of the Ivar's
 160                                                   type.  Useful for
 161                                                   debuggers. */
 162     int        ivar_offset;                    /* Byte offset from the base
 163                                                   address of the instance
 164                                                   structure to the variable. */
 165
 166   } ivar_list[1];                               /* Variable length
 167                                                   structure. */
 168 } IvarList, *IvarList_t;
 169
 170
 171 /*
 172 ** The compiler generates one (or more) of these structures for a class that
 173 ** has methods defined in its specification.
 174 **
 175 ** The implementation of a class can be broken into separate pieces in a file
 176 ** and categories can break them across modules. To handle this problem is a
 177 ** singly linked list of methods.
 178 */
 179 typedef struct objc_method Method;
 180 typedef Method* Method_t;
 181 typedef struct objc_method_list {
 182   struct objc_method_list*  method_next;      /* This variable is used to link
 183                                                 a method list to another.  It
 184                                                 is a singly linked list. */
 185   int            method_count;               /* Number of methods defined in
 186                                                 this structure. */
 187   struct objc_method {
 188     SEL         method_name;                  /* This variable is the method's
 189                                                 name.  It is a char*.
 190                                                   The unique integer passed to
 191                                                 objc_msg_send is a char* too.
 192                                                 It is compared against
 193                                                 method_name using strcmp. */
 194     const char* method_types;                 /* Description of the method's
 195                                                 parameter list.  Useful for
 196                                                 debuggers. */
 197     IMP         method_imp;                   /* Address of the method in the
 198                                                 executable. */
 199   } method_list[1];                           /* Variable length
 200                                                 structure. */
 201 } MethodList, *MethodList_t;
 202
 203 struct objc_protocol_list {
 204   struct objc_protocol_list *next;
 205   int count;
 206   Protocol *list[1];
 207 };
 208
 209 /*
 210 ** This is used to assure consistent access to the info field of
 211 ** classes
 212 */
 213 #ifndef HOST_BITS_PER_LONG
 214 #define HOST_BITS_PER_LONG  (sizeof(long)*8)
 215 #endif
 216
 217 #define __CLS_INFO(cls) ((cls)->info)
 218 #define __CLS_ISINFO(cls, mask) ((__CLS_INFO(cls)&mask)==mask)
 219 #define __CLS_SETINFO(cls, mask) (__CLS_INFO(cls) |= mask)
 220
 221 /* The structure is of type MetaClass */
 222 #define _CLS_META 0x2L
 223 #define CLS_ISMETA(cls) ((cls)&&__CLS_ISINFO(cls, _CLS_META))
 224
 225
 226 /* The structure is of type Class */
 227 #define _CLS_CLASS 0x1L
 228 #define CLS_ISCLASS(cls) ((cls)&&__CLS_ISINFO(cls, _CLS_CLASS))
 229
 230 /*
 231 ** The class is initialized within the runtime.  This means that
 232 ** it has had correct super and sublinks assigned
 233 */
 234 #define _CLS_RESOLV 0x8L
 235 #define CLS_ISRESOLV(cls) __CLS_ISINFO(cls, _CLS_RESOLV)
 236 #define CLS_SETRESOLV(cls) __CLS_SETINFO(cls, _CLS_RESOLV)
 237
 238 /*
 239 ** The class has been send a +initialize message or a such is not
 240 ** defined for this class
 241 */
 242 #define _CLS_INITIALIZED 0x04L
 243 #define CLS_ISINITIALIZED(cls) __CLS_ISINFO(cls, _CLS_INITIALIZED)
 244 #define CLS_SETINITIALIZED(cls) __CLS_SETINFO(cls, _CLS_INITIALIZED)
 245
 246 /*
 247 ** The class number of this class.  This must be the same for both the
 248 ** class and it's meta class object
 249 */
 250 #define CLS_GETNUMBER(cls) (__CLS_INFO(cls) >> (HOST_BITS_PER_LONG/2))
 251 #define CLS_SETNUMBER(cls, num) \
 252   ({ (cls)->info <<= (HOST_BITS_PER_LONG/2); \
 253      (cls)->info >>= (HOST_BITS_PER_LONG/2); \
 254      __CLS_SETINFO(cls, (((unsigned long)num) << (HOST_BITS_PER_LONG/2))); })
 255
 256 /*
 257 ** The compiler generates one of these structures for each category.  A class
 258 ** may have many categories and contain both instance and factory methods.
 259 */
 260 typedef struct objc_category {
 261   const char*   category_name;                /* Name of the category.  Name
 262                                                 contained in the () of the
 263                                                 category definition. */
 264   const char*   class_name;                   /* Name of the class to which
 265                                                 the category belongs. */
 266   MethodList_t  instance_methods;             /* Linked list of instance
 267                                                 methods defined in the
 268                                                 category. NULL indicates no
 269                                                 instance methods defined. */
 270   MethodList_t  class_methods;                /* Linked list of factory
 271                                                 methods defined in the
 272                                                 category.  NULL indicates no
 273                                                 class methods defined. */
 274   struct objc_protocol_list *protocols;       /* List of Protocols
 275                                                  conformed to */
 276 } Category, *Category_t;
 277
 278 /*
 279 ** Structure used when a message is send to a class's super class.  The
 280 ** compiler generates one of these structures and passes it to
 281 ** objc_msg_super.
 282 */
 283 typedef struct objc_super {
 284   id      self;                           /* Id of the object sending
 285                                                 the message. */
 286   Class class;                              /* Object's super class. */
 287 } Super, *Super_t;
 288
 289 IMP objc_msg_lookup_super(Super_t super, SEL sel);
 290
 291 retval_t objc_msg_sendv(id, SEL, arglist_t);
 292
 293
 294
 295 /*
 296 ** This is a hook which is called by objc_lookup_class and
 297 ** objc_get_class if the runtime is not able to find the class.
 298 ** This may e.g. try to load in the class using dynamic loading.
 299 ** The function is guaranteed to be passed a non-NULL name string.
 300 */
 301 extern Class (*_objc_lookup_class)(const char *name);
 302
 303 /*
 304 ** This is a hook which is called by __objc_exec_class every time a class
 305 ** or a category is loaded into the runtime.  This may e.g. help a
 306 ** dynamic loader determine the classes that have been loaded when
 307 ** an object file is dynamically linked in.
 308 */
 309 extern void (*_objc_load_callback)(Class class, Category* category);
 310
 311 extern id (*_objc_object_alloc)(Class class);
 312
 313 extern id (*_objc_object_copy)(id object);
 314
 315 extern id (*_objc_object_dispose)(id object);
 316
 317 Method_t class_get_class_method(MetaClass class, SEL aSel);
 318
 319 Method_t class_get_instance_method(Class class, SEL aSel);
 320
 321 Class class_pose_as(Class impostor, Class superclass);
 322
 323 Class objc_get_class(const char *name);
 324
 325 Class objc_lookup_class(const char *name);
 326
 327 Class objc_next_class(void **enum_state);
 328
 329 const char *sel_get_name(SEL selector);
 330
 331 const char *sel_get_type(SEL selector);
 332
 333 SEL sel_get_uid(const char *name);
 334
 335 SEL sel_get_any_uid(const char *name);
 336
 337 SEL sel_get_any_typed_uid(const char *name);
 338
 339 SEL sel_get_typed_uid(const char *name, const char*);
 340
 341 SEL sel_register_name(const char *name);
 342
 343 SEL sel_register_typed_name(const char *name, const char*type);
 344
 345
 346 BOOL sel_is_mapped (SEL aSel);
 347
 348 extern id class_create_instance(Class class);
 349
 350 static inline const char *
 351 class_get_class_name(Class class)
 352 {
 353   return CLS_ISCLASS(class)?class->name:((class==Nil)?"Nil":0);
 354 }
 355
 356 static inline long
 357 class_get_instance_size(Class class)
 358 {
 359   return CLS_ISCLASS(class)?class->instance_size:0;
 360 }
 361
 362 static inline MetaClass
 363 class_get_meta_class(Class class)
 364 {
 365   return CLS_ISCLASS(class)?class->class_pointer:Nil;
 366 }
 367
 368 static inline Class
 369 class_get_super_class(Class class)
 370 {
 371   return CLS_ISCLASS(class)?class->super_class:Nil;
 372 }
 373
 374 static inline int
 375 class_get_version(Class class)
 376 {
 377   return CLS_ISCLASS(class)?class->version:-1;
 378 }
 379
 380 static inline BOOL
 381 class_is_class(Class class)
 382 {
 383   return CLS_ISCLASS(class);
 384 }
 385
 386 static inline BOOL
 387 class_is_meta_class(Class class)
 388 {
 389   return CLS_ISMETA(class);
 390 }
 391
 392
 393 static inline void
 394 class_set_version(Class class, long version)
 395 {
 396   if (CLS_ISCLASS(class))
 397     class->version = version;
 398 }
 399
 400 static inline IMP
 401 method_get_imp(Method_t method)
 402 {
 403   return (method!=METHOD_NULL)?method->method_imp:(IMP)0;
 404 }
 405
 406 IMP get_imp (Class class, SEL sel);
 407
 408 id object_copy(id object);
 409
 410 id object_dispose(id object);
 411
 412 static inline Class
 413 object_get_class(id object)
 414 {
 415   return ((object!=nil)
 416           ? (CLS_ISCLASS(object->class_pointer)
 417              ? object->class_pointer
 418              : (CLS_ISMETA(object->class_pointer)
 419                 ? (Class)object
 420                 : Nil))
 421           : Nil);
 422 }
 423
 424 static inline const char *
 425 object_get_class_name(id object)
 426 {
 427   return ((object!=nil)?(CLS_ISCLASS(object->class_pointer)
 428                          ?object->class_pointer->name
 429                          :((Class)object)->name)
 430                        :"Nil");
 431 }
 432
 433 static inline MetaClass
 434 object_get_meta_class(id object)
 435 {
 436   return ((object!=nil)?(CLS_ISCLASS(object->class_pointer)
 437                          ?object->class_pointer->class_pointer
 438                          :(CLS_ISMETA(object->class_pointer)
 439                            ?object->class_pointer
 440                            :Nil))
 441                        :Nil);
 442 }
 443
 444 static inline Class
 445 object_get_super_class
 446 (id object)
 447 {
 448   return ((object!=nil)?(CLS_ISCLASS(object->class_pointer)
 449                          ?object->class_pointer->super_class
 450                          :(CLS_ISMETA(object->class_pointer)
 451                            ?((Class)object)->super_class
 452                            :Nil))
 453                        :Nil);
 454 }
 455
 456 static inline BOOL
 457 object_is_class(id object)
 458 {
 459   return CLS_ISCLASS((Class)object);
 460 }
 461
 462 static inline BOOL
 463 object_is_instance(id object)
 464 {
 465   return (object!=nil)&&CLS_ISCLASS(object->class_pointer);
 466 }
 467
 468 static inline BOOL
 469 object_is_meta_class(id object)
 470 {
 471   return CLS_ISMETA((Class)object);
 472 }
 473
 474 #endif /* not __objc_api_INCLUDE_GNU */
 475
 476
 477