gcc/objc/objc-api.h

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