libobjc/objc/runtime.h

   1 /* GNU Objective-C Runtime API - Modern 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 /** Implementation: the following functions are defined inline.  */
 150
 151 /* Return the class of 'object', or Nil if the object is nil.  If
 152    'object' is a class, the meta class is returned; if 'object' is a
 153    meta class, the root meta class is returned (note that this is
 154    different from the traditional GNU Objective-C Runtime API function
 155    object_get_class(), which for a meta class would return the meta
 156    class itself).  This function is inline, so it is really fast and
 157    should be used instead of accessing object->class_pointer
 158    directly.  */
 159 static inline Class
 160 object_getClass (id object)
 161 {
 162   if (object != nil)
 163     return object->class_pointer;
 164   else
 165     return Nil;
 166 }
 167
 168
 169 /** Implementation: the following functions are in selector.c.  */
 170
 171 /* Return the name of a given selector.  If 'selector' is NULL, return
 172    "<null selector>".  */
 173 objc_EXPORT const char *sel_getName (SEL selector);
 174
 175 /* Return the type of a given selector.
 176
 177    Compatibility Note: the Apple/NeXT runtime has untyped selectors,
 178    so it does not have this function, which is specific to the GNU
 179    Runtime.  */
 180 objc_EXPORT const char *sel_getType (SEL selector);
 181
 182 /* This is the same as sel_registerName ().  Please use
 183    sel_registerName () instead.  */
 184 objc_EXPORT SEL sel_getUid (const char *name);
 185
 186 /* Register a selector with a given name (but unspecified types).  If
 187    you know the types, it is better to call sel_registerTypedName().
 188    If a selector with this name already exists, it is returned.  */
 189 objc_EXPORT SEL sel_registerName (const char *name);
 190
 191 /* Register a selector with a given name and types.  If a selector
 192    with this name and types already exists, it is returned.
 193
 194    Compatibility Note: the Apple/NeXT runtime has untyped selectors,
 195    so it does not have this function, which is specific to the GNU
 196    Runtime.  */
 197 objc_EXPORT SEL set_registerTypedName (const char *name, const char *type);
 198
 199 /* Return YES if first_selector is the same as second_selector, and NO
 200    if not.  */
 201 objc_EXPORT BOOL sel_isEqual (SEL first_selector, SEL second_selector);
 202
 203
 204 /** Implementation: the following functions are in objects.c.  */
 205
 206 /* Create an instance of class 'class_', adding extraBytes to the size
 207    of the returned object.  This method allocates the appropriate
 208    amount of memory for the instance, initializes it to zero, then
 209    calls all the C++ constructors on appropriate C++ instance
 210    variables of the instance (if any) (TODO: The C++ constructors bit
 211    is not implemented yet).  */
 212 objc_EXPORT id class_createInstance (Class class_, size_t extraBytes);
 213
 214 /* Copy an object and return the copy.  extraBytes should be identical
 215    to the extraBytes parameter that was passed when creating the
 216    original object.  */
 217 objc_EXPORT id object_copy (id object, size_t extraBytes);
 218
 219 /* Dispose of an object.  This method calls the appropriate C++
 220    destructors on appropriate C++ instance variables of the instance
 221    (if any) (TODO: This is not implemented yet), then frees the memory
 222    for the instance.  */
 223 objc_EXPORT id object_dispose (id object);
 224
 225 /* Return the name of the class of 'object'.  If 'object' is 'nil',
 226    returns "Nil".  */
 227 objc_EXPORT const char * object_getClassName (id object);
 228
 229 /* Change the class of object to be class_.  Return the previous class
 230    of object.  This is currently not really thread-safe.  */
 231 objc_EXPORT Class object_setClass (id object, Class class_);
 232
 233
 234 /** Implementation: the following functions are in ivars.c.  */
 235
 236 /* Return an instance variable given the class and the instance
 237    variable name.  This is an expensive function to call, so try to
 238    reuse the returned Ivar if you can.  */
 239 objc_EXPORT Ivar class_getInstanceVariable (Class class_, const char *name);
 240
 241 /* If the object was created in class_createInstance() with some
 242    extraBytes, returns a pointer to them.  If it was not, then the
 243    returned pointer may make no sense.  */
 244 objc_EXPORT void * object_getIndexedIvars (id object);
 245
 246 /* Get the value of an instance variable of type 'id'.  The function
 247    returns the instance variable.  To get the value of the instance
 248    variable, you should pass as 'returnValue' a pointer to an 'id';
 249    the value will be copied there.  Note that 'returnValue' is really
 250    a 'void *', not a 'void **'.  This function really works only with
 251    instance variables of type 'id'; for other types of instance
 252    variables, access directly the data at (char *)object +
 253    ivar_getOffset (ivar).  */
 254 objc_EXPORT Ivar object_getInstanceVariable (id object, const char *name, void **returnValue);
 255
 256 /* Set the value of an instance variable.  The value to set is passed
 257    in 'newValue' (which really is an 'id', not a 'void *').  The
 258    function returns the instance variable.  This function really works
 259    only with instance variables of type 'id'; for other types of
 260    instance variables, access directly the data at (char *)object +
 261    ivar_getOffset (ivar).  */
 262 objc_EXPORT Ivar object_setInstanceVariable (id object, const char *name, void *newValue);
 263
 264 /* Get the value of an instance variable of type 'id' of the object
 265    'object'.  This is faster than object_getInstanceVariable if you
 266    already have the instance variable because it avoids the expensive
 267    call to class_getInstanceVariable that is done by
 268    object_getInstanceVariable.  */
 269 objc_EXPORT id object_getIvar (id object, Ivar variable);
 270
 271 /* Set the value of an instance variable of type 'id' of the object
 272    'object'.  This is faster than object_setInstanceVariable if you
 273    already have the instance variable because it avoids the expensive
 274    call to class_getInstanceVariable that is done by
 275    object_setInstanceVariable.  */
 276 objc_EXPORT void object_setIvar (id object, Ivar variable, id value);
 277
 278 /* Return the name of the instance variable.  */
 279 objc_EXPORT const char * ivar_getName (Ivar variable);
 280
 281 /* Return the offset of the instance variable from the start of the
 282    object data.  */
 283 objc_EXPORT ptrdiff_t ivar_getOffset (Ivar variable);
 284
 285 /* Return the type encoding of the variable.  */
 286 objc_EXPORT const char * ivar_getTypeEncoding (Ivar variable);
 287
 288
 289 /** Implementation: the following functions are in class.c.  */
 290
 291 /* Compatibility Note: The Apple/NeXT runtime does not have
 292    objc_get_unknown_class_handler and
 293    objc_setGetUnknownClassHandler().  They provide functionality that
 294    the traditional GNU Objective-C Runtime API used to provide via the
 295    _objc_lookup_class hook.  */
 296
 297 /* An 'objc_get_unknown_class_handler' function is used by
 298    objc_getClass() to get a class that is currently unknown to the
 299    compiler.  You could use it for example to have the class loaded by
 300    dynamically loading a library.  'class_name' is the name of the
 301    class.  The function should return the Class object if it manages to
 302    load the class, and Nil if not.  */
 303 typedef Class (*objc_get_unknown_class_handler)(const char *class_name);
 304
 305 /* Sets a new handler function for getting unknown classes (to be used
 306    by objc_getClass () and related), and returns the previous one.
 307    This function is not safe to call in a multi-threaded environment
 308    because other threads may be trying to use the get unknown class
 309    handler while you change it!  */
 310 objc_get_unknown_class_handler
 311 objc_setGetUnknownClassHandler (objc_get_unknown_class_handler new_handler);
 312
 313
 314 /* Return the class with name 'name', if it is already registered with
 315    the runtime.  If it is not registered, and
 316    objc_setGetUnknownClassHandler() has been called to set a handler
 317    for unknown classes, the handler is called to give it a chance to
 318    load the class in some other way.  If the class is not known to the
 319    runtime and the handler is not set or returns Nil, objc_getClass()
 320    returns Nil.  */
 321 objc_EXPORT Class objc_getClass (const char *name);
 322
 323 /* Return the class with name 'name', if it is already registered with
 324    the runtime.  Return Nil if not.  This function does not call the
 325    objc_get_unknown_class_handler function if the class is not
 326    found.  */
 327 objc_EXPORT Class objc_lookupClass (const char *name);
 328
 329 /* Return the meta class associated to the class with name 'name', if
 330    it is already registered with the runtime.  First, it finds the
 331    class using objc_getClass().  Then, it returns the associated meta
 332    class.  If the class could not be found using objc_getClass(),
 333    returns Nil.  */
 334 objc_EXPORT Class objc_getMetaClass (const char *name);
 335
 336 /* This is identical to objc_getClass(), but if the class is not found,
 337    it aborts the process instead of returning Nil.  */
 338 objc_EXPORT Class objc_getRequiredClass (const char *name);
 339
 340 /* If 'returnValue' is NULL, 'objc_getClassList' returns the number of
 341    classes currently registered with the runtime.  If 'returnValue' is
 342    not NULL, it should be a (Class *) pointer to an area of memory
 343    which can contain up to 'maxNumberOfClassesToReturn' Class records.
 344    'objc_getClassList' will fill the area pointed to by 'returnValue'
 345    with all the Classes registered with the runtime (or up to
 346    maxNumberOfClassesToReturn if there are more than
 347    maxNumberOfClassesToReturn).  The function return value is the
 348    number of classes actually returned in 'returnValue'.  */
 349 objc_EXPORT int objc_getClassList (Class *returnValue, int maxNumberOfClassesToReturn);
 350
 351 /* Compatibility Note: The Apple/NeXT runtime also has
 352
 353     Class objc_getFutureClass (const char *name);
 354     void objc_setFutureClass (Class class_, const char *name);
 355
 356    the documentation is unclear on what they are supposed to do, and
 357    the GNU Objective-C Runtime currently does not provide them.  */
 358
 359
 360 /* TODO: Add all the other functions in the API.  */
 361
 362
 363 /** Implementation: the following functions are in objc-foreach.c.  */
 364
 365 /* 'objc_enumerationMutation()' is called when a collection is
 366    mutated while being "fast enumerated".  That is a hard error, and
 367    objc_enumerationMutation is called to deal with it.  'collection'
 368    is the collection object that was mutated during an enumeration.
 369
 370    objc_enumerationMutation() will invoke the mutation handler if any
 371    is set.  Then, it will abort the program.
 372
 373    Compatibility note: the Apple runtime will not abort the program
 374    after calling the mutation handler.  */
 375 objc_EXPORT void objc_enumerationMutation (id collection);
 376
 377 /* 'objc_set_enumeration_mutation_handler' can be used to set a
 378    function that will be called (instead of aborting) when a fast
 379    enumeration is mutated during enumeration.  The handler will be
 380    called with the 'collection' being mutated as the only argument and
 381    it should not return; it should either exit the program, or could
 382    throw an exception.  The recommended implementation is to throw an
 383    exception - the user can then use exception handlers to deal with
 384    it.
 385
 386    This function is not thread safe (other threads may be trying to
 387    invoke the enumeration mutation handler while you are changing it!)
 388    and should be called during during the program initialization
 389    before threads are started.  It is mostly reserved for "Foundation"
 390    libraries; in the case of GNUstep, GNUstep Base may be using this
 391    function to improve the standard enumeration mutation handling.
 392    You probably shouldn't use this function unless you are writing
 393    your own Foundation library.  */
 394 objc_EXPORT void objc_setEnumerationMutationHandler (void (*handler)(id));
 395
 396 /* This structure (used during fast enumeration) is automatically
 397    defined by the compiler (it is as if this definition was always
 398    included in all Objective-C files).  Note that it is usually
 399    defined again with the name of NSFastEnumeration by "Foundation"
 400    libraries such as GNUstep Base.  And if NSFastEnumeration is
 401    defined, the compiler will use it instead of
 402    __objcFastEnumerationState when doing fast enumeration.  */
 403 /*
 404 struct __objcFastEnumerationState
 405 {
 406   unsigned long state;
 407   id            *itemsPtr;
 408   unsigned long *mutationsPtr;
 409   unsigned long extra[5];
 410 };
 411 */
 412
 413
 414 /** Implementation: the following functions are in encoding.c.  */
 415
 416 /* Traditional GNU Objective-C Runtime functions that are currently
 417    used to implement method forwarding.
 418 */
 419
 420 /* Return the size of a variable which has the specified 'type'
 421    encoding.  */
 422 int objc_sizeof_type (const char *type);
 423
 424 /* Return the align of a variable which has the specified 'type'
 425    encoding.  */
 426 int objc_alignof_type (const char *type);
 427
 428 /* Return the aligned size of a variable which has the specified
 429    'type' encoding.  The aligned size is the size rounded up to the
 430    nearest alignment.  */
 431 int objc_aligned_size (const char *type);
 432
 433 /* Return the promoted size of a variable which has the specified
 434    'type' encoding.  This is the size rounded up to the nearest
 435    integral of the wordsize, taken to be the size of a void *.  */
 436 int objc_promoted_size (const char *type);
 437
 438
 439 /* The following functions are used when parsing the type encoding of
 440    methods, to skip over parts that are ignored.  They take as
 441    argument a pointer to a location inside the type encoding of a
 442    method (which is a string) and return a new pointer, pointing to a
 443    new location inside the string after having skipped the unwanted
 444    information.  */
 445
 446 /* Skip some type qualifiers (_C_CONST, _C_IN, etc).  These may
 447   eventually precede typespecs occurring in method prototype
 448   encodings.  */
 449 const char *objc_skip_type_qualifiers (const char *type);
 450
 451 /* Skip one typespec element (_C_CLASS, _C_SEL, etc).  If the typespec
 452   is prepended by type qualifiers, these are skipped as well.  */
 453 const char *objc_skip_typespec (const char *type);
 454
 455 /* Skip an offset.  */
 456 const char *objc_skip_offset (const char *type);
 457
 458 /* Skip an argument specification (ie, skipping a typespec, which may
 459    include qualifiers, and an offset too).  */
 460 const char *objc_skip_argspec (const char *type);
 461
 462 /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type'
 463    (stopping at the first non-type qualifier found) and return an
 464    unsigned int which is the logical OR of all the corresponding flags
 465    (_F_CONST, _F_IN etc).  */
 466 unsigned objc_get_type_qualifiers (const char *type);
 467
 468
 469 /* Note that the following functions work for very simple structures,
 470    but get easily confused by more complicated ones (for example,
 471    containing vectors).  A better solution is required.
 472 */
 473
 474 /* The following three functions can be used to determine how a
 475    structure is laid out by the compiler. For example:
 476
 477   struct objc_struct_layout layout;
 478   int i;
 479
 480   objc_layout_structure (type, &layout);
 481   while (objc_layout_structure_next_member (&layout))
 482     {
 483       int position, align;
 484       const char *type;
 485
 486       objc_layout_structure_get_info (&layout, &position, &align, &type);
 487       printf ("element %d has offset %d, alignment %d\n",
 488               i++, position, align);
 489     }
 490
 491   These functions are used by objc_sizeof_type and objc_alignof_type
 492   functions to compute the size and alignment of structures. The
 493   previous method of computing the size and alignment of a structure
 494   was not working on some architectures, particulary on AIX, and in
 495   the presence of bitfields inside the structure.  */
 496 struct objc_struct_layout
 497 {
 498   const char *original_type;
 499   const char *type;
 500   const char *prev_type;
 501   unsigned int record_size;
 502   unsigned int record_align;
 503 };
 504
 505 void objc_layout_structure (const char *type,
 506                             struct objc_struct_layout *layout);
 507 BOOL  objc_layout_structure_next_member (struct objc_struct_layout *layout);
 508 void objc_layout_finish_structure (struct objc_struct_layout *layout,
 509                                    unsigned int *size,
 510                                    unsigned int *align);
 511 void objc_layout_structure_get_info (struct objc_struct_layout *layout,
 512                                      unsigned int *offset,
 513                                      unsigned int *align,
 514                                      const char **type);
 515
 516 #endif