libobjc/objc/runtime.h

   1 /* GNU Objective-C Runtime API.
   2    Copyright (C) 2010 Free Software Foundation, Inc.
   3    Contributed by Nicola Pero <nicola.pero@meta-innovation.com>
   4
   5 This file is part of GCC.
   6
   7 GCC is free software; you can redistribute it and/or modify it
   8 under the terms of the GNU General Public License as published by the
   9 Free Software Foundation; either version 3, or (at your option) any
  10 later version.
  11
  12 GCC is distributed in the hope that it will be useful, but WITHOUT
  13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
  15 License for more details.
  16
  17 Under Section 7 of GPL version 3, you are granted additional
  18 permissions described in the GCC Runtime Library Exception, version
  19 3.1, as published by the Free Software Foundation.
  20
  21 You should have received a copy of the GNU General Public License and
  22 a copy of the GCC Runtime Library Exception along with this program;
  23 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  24 <http://www.gnu.org/licenses/>.  */
  25
  26 #ifndef __objc_runtime_INCLUDE_GNU
  27 #define __objc_runtime_INCLUDE_GNU
  28
  29 /*
  30   This file declares the "modern" GNU Objective-C Runtime API.
  31   Include this file to use it.
  32
  33   This API is replacing the "traditional" GNU Objective-C Runtime API
  34   (declared in objc/objc-api.h) which is the one supported by older
  35   versions of the GNU Objective-C Runtime.  The "modern" API is very
  36   similar to the API used by the modern Apple/NeXT runtime.
  37
  38   Because the two APIs have some conflicting definitions (in
  39   particular, Method and Category are defined differently) you should
  40   include either objc/objc-api.h (to use the traditional GNU
  41   Objective-C Runtime API) or objc/runtime.h (to use the modern GNU
  42   Objective-C Runtime API), but not both.
  43 */
  44 #ifdef __objc_api_INCLUDE_GNU
  45 # error You can not include both objc/objc-api.h and objc/runtime.h.  Include objc/objc-api.h for the traditional GNU Objective-C Runtime API and objc/runtime.h for the modern one.
  46 #endif
  47
  48 /* TODO: This file is incomplete.  */
  49
  50 #include "objc.h"
  51
  52 /* An 'Ivar' represents an instance variable.  It holds information
  53    about the name, type and offset of the instance variable.  */
  54 typedef struct objc_ivar *Ivar;
  55
  56 /* A 'Property' represents a property.  It holds information about the
  57    name of the property, and its attributes.
  58
  59    Compatibility Note: the Apple/NeXT runtime defines this as
  60    objc_property_t, so we define it that way as well, but obviously
  61    Property is the right name.  */
  62 typedef struct objc_property *Property;
  63 typedef struct objc_property *objc_property_t;
  64
  65 /* A 'Method' represents a method.  It holds information about the
  66    name, types and the IMP of the method.  */
  67 typedef struct objc_method *Method;
  68
  69 /* A 'Category' represents a category.  It holds information about the
  70    name of the category, the class it belongs to, and the methods,
  71    protocols and such like provided by the category.  */
  72 typedef struct objc_category *Category;
  73
  74 /* 'Protocol' is defined in objc/objc.h (which is included by this
  75    file).  */
  76
  77 /* Method descriptor returned by introspective Object methods.  At the
  78    moment, this is really just the first part of the more complete
  79    objc_method structure used internally by the runtime.  (PS: In the
  80    GNU Objective-C Runtime, selectors already include a type, so an
  81    objc_method_description does not add much to a SEL.  But in other
  82    runtimes, that is not the case, which is why
  83    objc_method_description exists).  */
  84 struct objc_method_description
  85 {
  86   SEL name;      /* Selector (name and signature) */
  87   char *types;   /* Type encoding */
  88 };
  89
  90 /* The following are used in encode strings to describe the type of
  91    Ivars and Methods.  */
  92 #define _C_ID       '@'
  93 #define _C_CLASS    '#'
  94 #define _C_SEL      ':'
  95 #define _C_CHR      'c'
  96 #define _C_UCHR     'C'
  97 #define _C_SHT      's'
  98 #define _C_USHT     'S'
  99 #define _C_INT      'i'
 100 #define _C_UINT     'I'
 101 #define _C_LNG      'l'
 102 #define _C_ULNG     'L'
 103 #define _C_LNG_LNG  'q'
 104 #define _C_ULNG_LNG 'Q'
 105 #define _C_FLT      'f'
 106 #define _C_DBL      'd'
 107 #define _C_LNG_DBL  'D'
 108 #define _C_BFLD     'b'
 109 #define _C_BOOL     'B'
 110 #define _C_VOID     'v'
 111 #define _C_UNDEF    '?'
 112 #define _C_PTR      '^'
 113 #define _C_CHARPTR  '*'
 114 #define _C_ARY_B    '['
 115 #define _C_ARY_E    ']'
 116 #define _C_UNION_B  '('
 117 #define _C_UNION_E  ')'
 118 #define _C_STRUCT_B '{'
 119 #define _C_STRUCT_E '}'
 120 #define _C_VECTOR   '!'
 121 #define _C_COMPLEX  'j'
 122
 123 /* _C_ATOM is never generated by the compiler.  You can treat it as
 124    equivalent to "*".  */
 125 #define _C_ATOM     '%'
 126
 127 /* The following are used in encode strings to describe some
 128    qualifiers of method and ivar types.  */
 129 #define _C_CONST        'r'
 130 #define _C_IN           'n'
 131 #define _C_INOUT        'N'
 132 #define _C_OUT          'o'
 133 #define _C_BYCOPY       'O'
 134 #define _C_BYREF        'R'
 135 #define _C_ONEWAY       'V'
 136 #define _C_GCINVISIBLE  '|'
 137
 138 /* The same when used as flags.  */
 139 #define _F_CONST        0x01
 140 #define _F_IN           0x01
 141 #define _F_OUT          0x02
 142 #define _F_INOUT        0x03
 143 #define _F_BYCOPY       0x04
 144 #define _F_BYREF        0x08
 145 #define _F_ONEWAY       0x10
 146 #define _F_GCINVISIBLE  0x20
 147
 148
 149 /** Internals: the following functions are in selector.c.  */
 150
 151 /* Return the name of a given selector.  */
 152 objc_EXPORT const char *sel_getName (SEL selector);
 153
 154 /* Return the type of a given selector.
 155
 156    Compatibility Note: the Apple/NeXT runtime has untyped selectors,
 157    so it does not have this function, which is specific to the GNU
 158    Runtime.  */
 159 objc_EXPORT const char *sel_getType (SEL selector);
 160
 161 /* This is the same as sel_registerName ().  Please use
 162    sel_registerName () instead.  */
 163 objc_EXPORT SEL sel_getUid (const char *name);
 164
 165 /* Register a selector with a given name (but unspecified types).  If
 166    you know the types, it is better to call sel_registerTypedName().
 167    If a selector with this name already exists, it is returned.  */
 168 objc_EXPORT SEL sel_registerName (const char *name);
 169
 170 /* Register a selector with a given name and types.  If a selector
 171    with this name and types already exists, it is returned.
 172
 173    Compatibility Note: the Apple/NeXT runtime has untyped selectors,
 174    so it does not have this function, which is specific to the GNU
 175    Runtime.  */
 176 objc_EXPORT SEL set_registerTypedName (const char *name, const char *type);
 177
 178 /* Return YES if first_selector is the same as second_selector, and NO
 179    if not.  */
 180 objc_EXPORT BOOL sel_isEqual (SEL first_selector, SEL second_selector);
 181
 182
 183 /** Internals: the following functions are in objects.c.  */
 184
 185 /* Create an instance of class 'class', adding extraBytes to the size
 186    of the returned object.  This method allocates the appropriate
 187    amount of memory for the instance, initializes it to zero, then
 188    calls all the C++ constructors on appropriate C++ instance
 189    variables of the instance (if any) (TODO: This is not implemented
 190    yet).  */
 191 objc_EXPORT id class_createInstance (Class class, size_t extraBytes);
 192
 193 /* Copy an object and return the copy.  extraBytes should be identical
 194    to the extraBytes parameter that was passed when creating the
 195    original object.  */
 196 objc_EXPORT id object_copy (id object, size_t extraBytes);
 197
 198 /* Dispose of an object.  This method calls the appropriate C++
 199    destructors on appropriate C++ instance variables of the instance
 200    (if any) (TODO: This is not implemented yet), then frees the memory
 201    for the instance.  */
 202 objc_EXPORT id object_dispose (id object);
 203
 204
 205 /* TODO: Add all the other functions in the API.  */
 206
 207
 208 /** Internals: the following functions are in objc-foreach.c.  */
 209
 210 /* 'objc_enumerationMutation()' is called when a collection is
 211    mutated while being "fast enumerated".  That is a hard error, and
 212    objc_enumerationMutation is called to deal with it.  'collection'
 213    is the collection object that was mutated during an enumeration.
 214
 215    objc_enumerationMutation() will invoke the mutation handler if any
 216    is set.  Then, it will abort the program.
 217
 218    Compatibility note: the Apple runtime will not abort the program
 219    after calling the mutation handler.
 220  */
 221 objc_EXPORT void objc_enumerationMutation (id collection);
 222
 223 /* 'objc_set_enumeration_mutation_handler' can be used to set a
 224    function that will be called (instead of aborting) when a fast
 225    enumeration is mutated during enumeration.  The handler will be
 226    called with the 'collection' being mutated as the only argument and
 227    it should not return; it should either exit the program, or could
 228    throw an exception.  The recommended implementation is to throw an
 229    exception - the user can then use exception handlers to deal with
 230    it.
 231
 232    This function is not thread safe (other threads may be trying to
 233    invoke the enumeration mutation handler while you are changing it!)
 234    and should be called during during the program initialization
 235    before threads are started.  It is mostly reserved for "Foundation"
 236    libraries; in the case of GNUstep, GNUstep Base may be using this
 237    function to improve the standard enumeration mutation handling.
 238    You probably shouldn't use this function unless you are writing
 239    your own Foundation library.
 240 */
 241 objc_EXPORT void objc_setEnumerationMutationHandler (void (*handler)(id));
 242
 243 /* This structure (used during fast enumeration) is automatically
 244    defined by the compiler (it is as if this definition was always
 245    included in all Objective-C files).  Note that it is usually
 246    defined again with the name of NSFastEnumeration by "Foundation"
 247    libraries such as GNUstep Base.  And if NSFastEnumeration is
 248    defined, the compiler will use it instead of
 249    __objcFastEnumerationState when doing fast enumeration.
 250 */
 251 /*
 252 struct __objcFastEnumerationState
 253 {
 254   unsigned long state;
 255   id            *itemsPtr;
 256   unsigned long *mutationsPtr;
 257   unsigned long extra[5];
 258 };
 259 */
 260
 261
 262 /** Internals: the following functions are implemented in encoding.c.  */
 263
 264 /* Traditional GNU Objective-C Runtime functions that are currently
 265    used to implement method forwarding.
 266 */
 267
 268 /* Return the size of a variable which has the specified 'type'
 269    encoding.  */
 270 int objc_sizeof_type (const char *type);
 271
 272 /* Return the align of a variable which has the specified 'type'
 273    encoding.  */
 274 int objc_alignof_type (const char *type);
 275
 276 /* Return the aligned size of a variable which has the specified
 277    'type' encoding.  The aligned size is the size rounded up to the
 278    nearest alignment.  */
 279 int objc_aligned_size (const char *type);
 280
 281 /* Return the promoted size of a variable which has the specified
 282    'type' encoding.  This is the size rounded up to the nearest
 283    integral of the wordsize, taken to be the size of a void *.  */
 284 int objc_promoted_size (const char *type);
 285
 286
 287 /* The following functions are used when parsing the type encoding of
 288    methods, to skip over parts that are ignored.  They take as
 289    argument a pointer to a location inside the type encoding of a
 290    method (which is a string) and return a new pointer, pointing to a
 291    new location inside the string after having skipped the unwanted
 292    information.  */
 293
 294 /* Skip some type qualifiers (_C_CONST, _C_IN, etc).  These may
 295   eventually precede typespecs occurring in method prototype
 296   encodings.  */
 297 const char *objc_skip_type_qualifiers (const char *type);
 298
 299 /* Skip one typespec element (_C_CLASS, _C_SEL, etc).  If the typespec
 300   is prepended by type qualifiers, these are skipped as well.  */
 301 const char *objc_skip_typespec (const char *type);
 302
 303 /* Skip an offset.  */
 304 const char *objc_skip_offset (const char *type);
 305
 306 /* Skip an argument specification (ie, skipping a typespec, which may
 307    include qualifiers, and an offset too).  */
 308 const char *objc_skip_argspec (const char *type);
 309
 310 /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type'
 311    (stopping at the first non-type qualifier found) and return an
 312    unsigned int which is the logical OR of all the corresponding flags
 313    (_F_CONST, _F_IN etc).  */
 314 unsigned objc_get_type_qualifiers (const char *type);
 315
 316
 317 /* Note that the following functions work for very simple structures,
 318    but get easily confused by more complicated ones (for example,
 319    containing vectors).  A better solution is required.
 320 */
 321
 322 /* The following three functions can be used to determine how a
 323    structure is laid out by the compiler. For example:
 324
 325   struct objc_struct_layout layout;
 326   int i;
 327
 328   objc_layout_structure (type, &layout);
 329   while (objc_layout_structure_next_member (&layout))
 330     {
 331       int position, align;
 332       const char *type;
 333
 334       objc_layout_structure_get_info (&layout, &position, &align, &type);
 335       printf ("element %d has offset %d, alignment %d\n",
 336               i++, position, align);
 337     }
 338
 339   These functions are used by objc_sizeof_type and objc_alignof_type
 340   functions to compute the size and alignment of structures. The
 341   previous method of computing the size and alignment of a structure
 342   was not working on some architectures, particulary on AIX, and in
 343   the presence of bitfields inside the structure.  */
 344 struct objc_struct_layout
 345 {
 346   const char *original_type;
 347   const char *type;
 348   const char *prev_type;
 349   unsigned int record_size;
 350   unsigned int record_align;
 351 };
 352
 353 void objc_layout_structure (const char *type,
 354                             struct objc_struct_layout *layout);
 355 BOOL  objc_layout_structure_next_member (struct objc_struct_layout *layout);
 356 void objc_layout_finish_structure (struct objc_struct_layout *layout,
 357                                    unsigned int *size,
 358                                    unsigned int *align);
 359 void objc_layout_structure_get_info (struct objc_struct_layout *layout,
 360                                      unsigned int *offset,
 361                                      unsigned int *align,
 362                                      const char **type);
 363
 364 #endif