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 #include "objc-decls.h"
  52
  53 /* An 'Ivar' represents an instance variable.  It holds information
  54    about the name, type and offset of the instance variable.  */
  55 typedef struct objc_ivar *Ivar;
  56
  57 /* A 'Property' represents a property.  It holds information about the
  58    name of the property, and its attributes.
  59
  60    Compatibility Note: the Apple/NeXT runtime defines this as
  61    objc_property_t, so we define it that way as well, but obviously
  62    Property is the right name.  */
  63 typedef struct objc_property *Property;
  64 typedef struct objc_property *objc_property_t;
  65
  66 /* A 'Method' represents a method.  It holds information about the
  67    name, types and the IMP of the method.  */
  68 typedef struct objc_method *Method;
  69
  70 /* A 'Category' represents a category.  It holds information about the
  71    name of the category, the class it belongs to, and the methods,
  72    protocols and such like provided by the category.  */
  73 typedef struct objc_category *Category;
  74
  75 /* 'Protocol' is defined in objc/objc.h (which is included by this
  76    file).  */
  77
  78 /* Method descriptor returned by introspective Object methods.  At the
  79    moment, this is really just the first part of the more complete
  80    objc_method structure used internally by the runtime.  (PS: In the
  81    GNU Objective-C Runtime, selectors already include a type, so an
  82    objc_method_description does not add much to a SEL.  But in other
  83    runtimes, that is not the case, which is why
  84    objc_method_description exists).  */
  85 struct objc_method_description
  86 {
  87   SEL name;      /* Selector (name and signature) */
  88   char *types;   /* Type encoding */
  89 };
  90
  91 /* The following are used in encode strings to describe the type of
  92    Ivars and Methods.  */
  93 #define _C_ID       '@'
  94 #define _C_CLASS    '#'
  95 #define _C_SEL      ':'
  96 #define _C_CHR      'c'
  97 #define _C_UCHR     'C'
  98 #define _C_SHT      's'
  99 #define _C_USHT     'S'
 100 #define _C_INT      'i'
 101 #define _C_UINT     'I'
 102 #define _C_LNG      'l'
 103 #define _C_ULNG     'L'
 104 #define _C_LNG_LNG  'q'
 105 #define _C_ULNG_LNG 'Q'
 106 #define _C_FLT      'f'
 107 #define _C_DBL      'd'
 108 #define _C_LNG_DBL  'D'
 109 #define _C_BFLD     'b'
 110 #define _C_BOOL     'B'
 111 #define _C_VOID     'v'
 112 #define _C_UNDEF    '?'
 113 #define _C_PTR      '^'
 114 #define _C_CHARPTR  '*'
 115 #define _C_ARY_B    '['
 116 #define _C_ARY_E    ']'
 117 #define _C_UNION_B  '('
 118 #define _C_UNION_E  ')'
 119 #define _C_STRUCT_B '{'
 120 #define _C_STRUCT_E '}'
 121 #define _C_VECTOR   '!'
 122 #define _C_COMPLEX  'j'
 123
 124 /* _C_ATOM is never generated by the compiler.  You can treat it as
 125    equivalent to "*".  */
 126 #define _C_ATOM     '%'
 127
 128 /* The following are used in encode strings to describe some
 129    qualifiers of method and ivar types.  */
 130 #define _C_CONST        'r'
 131 #define _C_IN           'n'
 132 #define _C_INOUT        'N'
 133 #define _C_OUT          'o'
 134 #define _C_BYCOPY       'O'
 135 #define _C_BYREF        'R'
 136 #define _C_ONEWAY       'V'
 137 #define _C_GCINVISIBLE  '|'
 138
 139 /* The same when used as flags.  */
 140 #define _F_CONST        0x01
 141 #define _F_IN           0x01
 142 #define _F_OUT          0x02
 143 #define _F_INOUT        0x03
 144 #define _F_BYCOPY       0x04
 145 #define _F_BYREF        0x08
 146 #define _F_ONEWAY       0x10
 147 #define _F_GCINVISIBLE  0x20
 148
 149
 150 /** Implementation: the following functions are defined inline.  */
 151
 152 /* Return the class of 'object', or Nil if the object is nil.  If
 153    'object' is a class, the meta class is returned; if 'object' is a
 154    meta class, the root meta class is returned (note that this is
 155    different from the traditional GNU Objective-C Runtime API function
 156    object_get_class(), which for a meta class would return the meta
 157    class itself).  This function is inline, so it is really fast and
 158    should be used instead of accessing object->class_pointer
 159    directly.  */
 160 static inline Class
 161 object_getClass (id object)
 162 {
 163   if (object != nil)
 164     return object->class_pointer;
 165   else
 166     return Nil;
 167 }
 168
 169
 170 /** Implementation: the following functions are in selector.c.  */
 171
 172 /* Return the name of a given selector.  If 'selector' is NULL, return
 173    "<null selector>".  */
 174 objc_EXPORT const char *sel_getName (SEL selector);
 175
 176 /* Return the type of a given selector.
 177
 178    Compatibility Note: the Apple/NeXT runtime has untyped selectors,
 179    so it does not have this function, which is specific to the GNU
 180    Runtime.  */
 181 objc_EXPORT const char *sel_getType (SEL selector);
 182
 183 /* This is the same as sel_registerName ().  Please use
 184    sel_registerName () instead.  */
 185 objc_EXPORT SEL sel_getUid (const char *name);
 186
 187 /* Register a selector with a given name (but unspecified types).  If
 188    you know the types, it is better to call sel_registerTypedName().
 189    If a selector with this name already exists, it is returned.  */
 190 objc_EXPORT SEL sel_registerName (const char *name);
 191
 192 /* Register a selector with a given name and types.  If a selector
 193    with this name and types already exists, it is returned.
 194
 195    Compatibility Note: the Apple/NeXT runtime has untyped selectors,
 196    so it does not have this function, which is specific to the GNU
 197    Runtime.  */
 198 objc_EXPORT SEL set_registerTypedName (const char *name, const char *type);
 199
 200 /* Return YES if first_selector is the same as second_selector, and NO
 201    if not.  */
 202 objc_EXPORT BOOL sel_isEqual (SEL first_selector, SEL second_selector);
 203
 204
 205 /** Implementation: the following functions are in objects.c.  */
 206
 207 /* Create an instance of class 'class_', adding extraBytes to the size
 208    of the returned object.  This method allocates the appropriate
 209    amount of memory for the instance, initializes it to zero, then
 210    calls all the C++ constructors on appropriate C++ instance
 211    variables of the instance (if any) (TODO: The C++ constructors bit
 212    is not implemented yet).  */
 213 objc_EXPORT id class_createInstance (Class class_, size_t extraBytes);
 214
 215 /* Copy an object and return the copy.  extraBytes should be identical
 216    to the extraBytes parameter that was passed when creating the
 217    original object.  */
 218 objc_EXPORT id object_copy (id object, size_t extraBytes);
 219
 220 /* Dispose of an object.  This method calls the appropriate C++
 221    destructors on appropriate C++ instance variables of the instance
 222    (if any) (TODO: This is not implemented yet), then frees the memory
 223    for the instance.  */
 224 objc_EXPORT id object_dispose (id object);
 225
 226 /* Return the name of the class of 'object'.  If 'object' is 'nil',
 227    returns "Nil".  */
 228 objc_EXPORT const char * object_getClassName (id object);
 229
 230 /* Change the class of object to be class_.  Return the previous class
 231    of object.  This is currently not really thread-safe.  */
 232 objc_EXPORT Class object_setClass (id object, Class class_);
 233
 234
 235 /** Implementation: the following functions are in ivars.c.  */
 236
 237 /* Return an instance variable given the class and the instance
 238    variable name.  This is an expensive function to call, so try to
 239    reuse the returned Ivar if you can.  */
 240 objc_EXPORT Ivar class_getInstanceVariable (Class class_, const char *name);
 241
 242 /* Return a class variable given the class and the class variable
 243    name.  This is an expensive function to call, so try to reuse the
 244    returned Ivar if you can.
 245
 246    This function always returns NULL since class variables are
 247    currently unavailable in Objective-C.  */
 248 objc_EXPORT Ivar class_getClassVariable (Class class_, const char *name);
 249
 250 /* If the object was created in class_createInstance() with some
 251    extraBytes, returns a pointer to them.  If it was not, then the
 252    returned pointer may make no sense.  */
 253 objc_EXPORT void * object_getIndexedIvars (id object);
 254
 255 /* Get the value of an instance variable of type 'id'.  The function
 256    returns the instance variable.  To get the value of the instance
 257    variable, you should pass as 'returnValue' a pointer to an 'id';
 258    the value will be copied there.  Note that 'returnValue' is really
 259    a 'void *', not a 'void **'.  This function really works only with
 260    instance variables of type 'id'; for other types of instance
 261    variables, access directly the data at (char *)object +
 262    ivar_getOffset (ivar).  */
 263 objc_EXPORT Ivar object_getInstanceVariable (id object, const char *name, void **returnValue);
 264
 265 /* Set the value of an instance variable.  The value to set is passed
 266    in 'newValue' (which really is an 'id', not a 'void *').  The
 267    function returns the instance variable.  This function really works
 268    only with instance variables of type 'id'; for other types of
 269    instance variables, access directly the data at (char *)object +
 270    ivar_getOffset (ivar).  */
 271 objc_EXPORT Ivar object_setInstanceVariable (id object, const char *name, void *newValue);
 272
 273 /* Get the value of an instance variable of type 'id' of the object
 274    'object'.  This is faster than object_getInstanceVariable if you
 275    already have the instance variable because it avoids the expensive
 276    call to class_getInstanceVariable that is done by
 277    object_getInstanceVariable.  */
 278 objc_EXPORT id object_getIvar (id object, Ivar variable);
 279
 280 /* Set the value of an instance variable of type 'id' of the object
 281    'object'.  This is faster than object_setInstanceVariable if you
 282    already have the instance variable because it avoids the expensive
 283    call to class_getInstanceVariable that is done by
 284    object_setInstanceVariable.  */
 285 objc_EXPORT void object_setIvar (id object, Ivar variable, id value);
 286
 287 /* Return the name of the instance variable.  */
 288 objc_EXPORT const char * ivar_getName (Ivar variable);
 289
 290 /* Return the offset of the instance variable from the start of the
 291    object data.  */
 292 objc_EXPORT ptrdiff_t ivar_getOffset (Ivar variable);
 293
 294 /* Return the type encoding of the variable.  */
 295 objc_EXPORT const char * ivar_getTypeEncoding (Ivar variable);
 296
 297
 298 /** Implementation: the following functions are in class.c.  */
 299
 300 /* Compatibility Note: The Apple/NeXT runtime does not have
 301    objc_get_unknown_class_handler and
 302    objc_setGetUnknownClassHandler().  They provide functionality that
 303    the traditional GNU Objective-C Runtime API used to provide via the
 304    _objc_lookup_class hook.  */
 305
 306 /* An 'objc_get_unknown_class_handler' function is used by
 307    objc_getClass() to get a class that is currently unknown to the
 308    compiler.  You could use it for example to have the class loaded by
 309    dynamically loading a library.  'class_name' is the name of the
 310    class.  The function should return the Class object if it manages to
 311    load the class, and Nil if not.  */
 312 typedef Class (*objc_get_unknown_class_handler)(const char *class_name);
 313
 314 /* Sets a new handler function for getting unknown classes (to be used
 315    by objc_getClass () and related), and returns the previous one.
 316    This function is not safe to call in a multi-threaded environment
 317    because other threads may be trying to use the get unknown class
 318    handler while you change it!  */
 319 objc_get_unknown_class_handler
 320 objc_setGetUnknownClassHandler (objc_get_unknown_class_handler new_handler);
 321
 322
 323 /* Return the class with name 'name', if it is already registered with
 324    the runtime.  If it is not registered, and
 325    objc_setGetUnknownClassHandler() has been called to set a handler
 326    for unknown classes, the handler is called to give it a chance to
 327    load the class in some other way.  If the class is not known to the
 328    runtime and the handler is not set or returns Nil, objc_getClass()
 329    returns Nil.  */
 330 objc_EXPORT Class objc_getClass (const char *name);
 331
 332 /* Return the class with name 'name', if it is already registered with
 333    the runtime.  Return Nil if not.  This function does not call the
 334    objc_get_unknown_class_handler function if the class is not
 335    found.  */
 336 objc_EXPORT Class objc_lookupClass (const char *name);
 337
 338 /* Return the meta class associated to the class with name 'name', if
 339    it is already registered with the runtime.  First, it finds the
 340    class using objc_getClass().  Then, it returns the associated meta
 341    class.  If the class could not be found using objc_getClass(),
 342    returns Nil.  */
 343 objc_EXPORT Class objc_getMetaClass (const char *name);
 344
 345 /* This is identical to objc_getClass(), but if the class is not found,
 346    it aborts the process instead of returning Nil.  */
 347 objc_EXPORT Class objc_getRequiredClass (const char *name);
 348
 349 /* If 'returnValue' is NULL, 'objc_getClassList' returns the number of
 350    classes currently registered with the runtime.  If 'returnValue' is
 351    not NULL, it should be a (Class *) pointer to an area of memory
 352    which can contain up to 'maxNumberOfClassesToReturn' Class records.
 353    'objc_getClassList' will fill the area pointed to by 'returnValue'
 354    with all the Classes registered with the runtime (or up to
 355    maxNumberOfClassesToReturn if there are more than
 356    maxNumberOfClassesToReturn).  The function return value is the
 357    number of classes actually returned in 'returnValue'.  */
 358 objc_EXPORT int objc_getClassList (Class *returnValue, int maxNumberOfClassesToReturn);
 359
 360 /* Compatibility Note: The Apple/NeXT runtime also has
 361
 362     Class objc_getFutureClass (const char *name);
 363     void objc_setFutureClass (Class class_, const char *name);
 364
 365    the documentation is unclear on what they are supposed to do, and
 366    the GNU Objective-C Runtime currently does not provide them.  */
 367
 368 /* Return the name of the class 'class_', or the string "nil" if the
 369    class_ is Nil.  */
 370 objc_EXPORT const char * class_getName (Class class_);
 371
 372 /* Return YES if 'class_' is a meta class, and NO if not.  If 'class_'
 373    is Nil, return NO.  */
 374 objc_EXPORT BOOL class_isMetaClass (Class class_);
 375
 376 /* Return the superclass of 'class_'.  If 'class_' is Nil, or it is a root
 377    class, return Nil.
 378
 379    TODO: It may be worth to define this inline, since it is usually
 380    used in loops when traversing the class hierarchy.  */
 381 objc_EXPORT Class class_getSuperclass (Class class_);
 382
 383 /* Return the 'version' number of the class, which is an integer that
 384    can be used to track changes in the class API, methods and
 385    variables.  If class_ is Nil, return 0.  If class_ is not Nil, the
 386    version is 0 unless class_setVersion() has been called to set a
 387    different one.
 388
 389    Please note that internally the version is a long, but the API only
 390    allows you to set and retrieve int values.  */
 391 objc_EXPORT int class_getVersion (Class class_);
 392
 393 /* Set the 'version' number of the class, which is an integer that can
 394    be used to track changes in the class API, methods and variables.
 395    If 'class_' is Nil, does nothing.
 396
 397    This is typically used internally by "Foundation" libraries such as
 398    GNUstep Base to support serialization / deserialization of objects
 399    that work across changes in the classes.  If you are using such a
 400    library, you probably want to use their versioning API, which may
 401    be based on this one, but is integrated with the rest of the
 402    library.
 403
 404    Please note that internally the version is a long, but the API only
 405    allows you to set and retrieve int values.  */
 406 objc_EXPORT void class_setVersion (Class class_, int version);
 407
 408 /* Return the size in bytes (a byte is the size of a char) of an
 409    instance of the class.  If class_ is Nil, return 0; else it return
 410    a non-zero number (since the 'isa' instance variable is required
 411    for all classes).  */
 412 objc_EXPORT size_t class_getInstanceSize (Class class_);
 413
 414
 415 /** Implementation: the following functions are in protocols.c.  */
 416
 417 /* Return the protocol with name 'name', or nil if it the protocol is
 418    not known to the runtime.  */
 419 objc_EXPORT Protocol *objc_getProtocol (const char *name);
 420
 421 /* Return all the protocols known to the runtime.  The return value of
 422    the function is a pointer to an area, allocated with malloc(), that
 423    contains all the protocols known to the runtime; the list is
 424    terminated by NULL.  You should free this area using free() once
 425    you no longer need it.  Optionally, if you pass a non-NULL
 426    'numberOfReturnedProtocols' pointer, the unsigned int that it
 427    points to will be filled with the number of protocols returned.  If
 428    there are no protocols known to the runtime, NULL is returned.  */
 429 objc_EXPORT Protocol **objc_copyProtocolList (unsigned int *numberOfReturnedProtocols);
 430
 431 /* Add a protocol to a class, and return YES if it was done
 432    succesfully, and NO if not.  At the moment, NO should only happen
 433    if class_ or protocol are nil, if the protocol is not a Protocol
 434    object or if the class already conforms to the protocol.  */
 435 objc_EXPORT BOOL class_addProtocol (Class class_, Protocol *protocol);
 436
 437 /* Return YES if the class 'class_' conforms to Protocol 'protocol',
 438    and NO if not.  */
 439 objc_EXPORT BOOL class_conformsToProtocol (Class class_, Protocol *protocol);
 440
 441 /* Return all the protocols that the class conforms to.  The return
 442    value of the function is a pointer to an area, allocated with
 443    malloc(), that contains all the protocols formally adopted by the
 444    class.  It does not include protocols adopted by superclasses.  The
 445    list is terminated by NULL.  Optionally, if you pass a non-NULL
 446    'numberOfReturnedProtocols' pointer, the unsigned int that it
 447    points to will be filled with the number of protocols returned.  */
 448 objc_EXPORT Protocol **class_copyProtocolList (Class class_, unsigned int *numberOfReturnedProtocols);
 449
 450 /* Return YES if protocol 'protocol' conforms to protocol
 451    'anotherProtocol', and NO if not.  Note that if one of the two
 452    protocols is nil, it returns NO.  */
 453 objc_EXPORT BOOL protocol_conformsToProtocol (Protocol *protocol, Protocol *anotherProtocol);
 454
 455 /* Return YES if protocol 'protocol' is the same as protocol
 456    'anotherProtocol', and 'NO' if not.  Note that it returns YES if
 457    the two protocols are both nil.  */
 458 objc_EXPORT BOOL protocol_isEqual (Protocol *protocol, Protocol *anotherProtocol);
 459
 460 /* Return the name of protocol 'protocol'.  If 'protocol' is nil or is
 461    not a Protocol, return NULL.  */
 462 objc_EXPORT const char *protocol_getName (Protocol *protocol);
 463
 464 /* Return the method description for the method with selector
 465    'selector' in protocol 'protocol'; if 'requiredMethod' is YES, the
 466    function searches the list of required methods; if NO, the list of
 467    optional methods.  If 'instanceMethod' is YES, the function search
 468    for an instance method; if NO, for a class method.  If there is no
 469    matching method, an objc_method_description structure with both
 470    name and types set to NULL is returned.  This function will only
 471    find methods that are directly declared in the protocol itself, not
 472    in other protocols that this protocol adopts.
 473
 474    Note that the traditional ABI does not store the list of optional
 475    methods of a protocol in a compiled module, so the traditional ABI
 476    will always return (NULL, NULL) when requiredMethod == NO.  */
 477 objc_EXPORT struct objc_method_description protocol_getMethodDescription (Protocol *protocol,
 478                                                                           SEL selector,
 479                                                                           BOOL requiredMethod,
 480                                                                           BOOL instanceMethod);
 481
 482 /* Return the method descriptions of all the methods of the protocol.
 483    The return value of the function is a pointer to an area, allocated
 484    with malloc(), that contains all the method descriptions of the
 485    methods of the protocol.  It does not recursively include methods
 486    of the protocols adopted by this protocol.  The list is terminated
 487    by a NULL objc_method_description (one with both fields set to
 488    NULL).  Optionally, if you pass a non-NULL
 489    'numberOfReturnedMethods' pointer, the unsigned int that it points
 490    to will be filled with the number of properties returned.
 491
 492    Note that the traditional ABI does not store the list of optional
 493    methods of a protocol in a compiled module, so the traditional ABI
 494    will always return an empty list if requiredMethod is set to
 495    NO.  */
 496 objc_EXPORT struct objc_method_description *protocol_copyMethodDescriptionList (Protocol *protocol,
 497                                                                                 BOOL requiredMethod,
 498                                                                                 BOOL instanceMethod,
 499                                                                                 unsigned int *numberOfReturnedMethods);
 500
 501 /* Return the property with name 'propertyName' of the protocol
 502    'protocol'.  If 'requiredProperty' is YES, the function searches
 503    the list of required properties; if NO, the list of optional
 504    properties.  If 'instanceProperty' is YES, the function searches
 505    the list of instance properties; if NO, the list of class
 506    properties.  At the moment, optional properties and class
 507    properties are not part of the Objective-C language, so both
 508    'requiredProperty' and 'instanceProperty' should be set to YES.
 509    This function returns NULL if the required property can not be
 510    found.
 511
 512    Note that the traditional ABI does not store the list of properties
 513    of a protocol in a compiled module, so the traditional ABI will
 514    always return NULL.  */
 515 objc_EXPORT Property protocol_getProperty (Protocol *protocol, const char *propertyName,
 516                                            BOOL requiredProperty, BOOL instanceProperty);
 517
 518 /* Return all the properties of the protocol.  The return value of the
 519    function is a pointer to an area, allocated with malloc(), that
 520    contains all the properties of the protocol.  It does not
 521    recursively include properties of the protocols adopted by this
 522    protocol.  The list is terminated by NULL.  Optionally, if you pass
 523    a non-NULL 'numberOfReturnedProperties' pointer, the unsigned int
 524    that it points to will be filled with the number of properties
 525    returned.
 526
 527    Note that the traditional ABI does not store the list of properties
 528    of a protocol in a compiled module, so the traditional ABI will
 529    always return NULL and store 0 in numberOfReturnedProperties.  */
 530 objc_EXPORT Property *protocol_copyPropertyList (Protocol *protocol, unsigned int *numberOfReturnedProperties);
 531
 532 /* Return all the protocols that the protocol conforms to.  The return
 533    value of the function is a pointer to an area, allocated with
 534    malloc(), that contains all the protocols formally adopted by the
 535    protocol.  It does not recursively include protocols adopted by the
 536    protocols adopted by this protocol.  The list is terminated by
 537    NULL.  Optionally, if you pass a non-NULL
 538    'numberOfReturnedProtocols' pointer, the unsigned int that it
 539    points to will be filled with the number of protocols returned.  */
 540 objc_EXPORT Protocol **protocol_copyProtocolList (Protocol *protocol, unsigned int *numberOfReturnedProtocols);
 541
 542
 543 /* TODO: Add all the other functions in the API.  */
 544
 545
 546 /** Implementation: the following functions are in objc-foreach.c.  */
 547
 548 /* 'objc_enumerationMutation()' is called when a collection is
 549    mutated while being "fast enumerated".  That is a hard error, and
 550    objc_enumerationMutation is called to deal with it.  'collection'
 551    is the collection object that was mutated during an enumeration.
 552
 553    objc_enumerationMutation() will invoke the mutation handler if any
 554    is set.  Then, it will abort the program.
 555
 556    Compatibility note: the Apple runtime will not abort the program
 557    after calling the mutation handler.  */
 558 objc_EXPORT void objc_enumerationMutation (id collection);
 559
 560 /* 'objc_set_enumeration_mutation_handler' can be used to set a
 561    function that will be called (instead of aborting) when a fast
 562    enumeration is mutated during enumeration.  The handler will be
 563    called with the 'collection' being mutated as the only argument and
 564    it should not return; it should either exit the program, or could
 565    throw an exception.  The recommended implementation is to throw an
 566    exception - the user can then use exception handlers to deal with
 567    it.
 568
 569    This function is not thread safe (other threads may be trying to
 570    invoke the enumeration mutation handler while you are changing it!)
 571    and should be called during during the program initialization
 572    before threads are started.  It is mostly reserved for "Foundation"
 573    libraries; in the case of GNUstep, GNUstep Base may be using this
 574    function to improve the standard enumeration mutation handling.
 575    You probably shouldn't use this function unless you are writing
 576    your own Foundation library.  */
 577 objc_EXPORT void objc_setEnumerationMutationHandler (void (*handler)(id));
 578
 579 /* This structure (used during fast enumeration) is automatically
 580    defined by the compiler (it is as if this definition was always
 581    included in all Objective-C files).  Note that it is usually
 582    defined again with the name of NSFastEnumeration by "Foundation"
 583    libraries such as GNUstep Base.  And if NSFastEnumeration is
 584    defined, the compiler will use it instead of
 585    __objcFastEnumerationState when doing fast enumeration.  */
 586 /*
 587 struct __objcFastEnumerationState
 588 {
 589   unsigned long state;
 590   id            *itemsPtr;
 591   unsigned long *mutationsPtr;
 592   unsigned long extra[5];
 593 };
 594 */
 595
 596
 597 /** Implementation: the following functions are in memory.c.  */
 598
 599 /* Traditional GNU Objective-C Runtime functions that are used for
 600    memory allocation and disposal.  These functions are used in the
 601    same way as you use malloc, realloc, calloc and free and make sure
 602    that memory allocation works properly with the garbage
 603    collector.
 604
 605    Compatibility Note: these functions are not available with the
 606    Apple/NeXT runtime.  */
 607
 608 objc_EXPORT void *objc_malloc(size_t size);
 609
 610 /* FIXME: Shouldn't the following be called objc_malloc_atomic ?  The
 611    GC function is GC_malloc_atomic() which makes sense.
 612  */
 613 objc_EXPORT void *objc_atomic_malloc(size_t size);
 614
 615 objc_EXPORT void *objc_realloc(void *mem, size_t size);
 616
 617 objc_EXPORT void *objc_calloc(size_t nelem, size_t size);
 618
 619 objc_EXPORT void objc_free(void *mem);
 620
 621
 622 /** Implementation: the following functions are in encoding.c.  */
 623
 624 /* Traditional GNU Objective-C Runtime functions that are currently
 625    used to implement method forwarding.
 626
 627    Compatibility Note: these functions are not available with the
 628    Apple/NeXT runtime.  */
 629
 630 /* Return the size of a variable which has the specified 'type'
 631    encoding.  */
 632 int objc_sizeof_type (const char *type);
 633
 634 /* Return the align of a variable which has the specified 'type'
 635    encoding.  */
 636 int objc_alignof_type (const char *type);
 637
 638 /* Return the aligned size of a variable which has the specified
 639    'type' encoding.  The aligned size is the size rounded up to the
 640    nearest alignment.  */
 641 int objc_aligned_size (const char *type);
 642
 643 /* Return the promoted size of a variable which has the specified
 644    'type' encoding.  This is the size rounded up to the nearest
 645    integral of the wordsize, taken to be the size of a void *.  */
 646 int objc_promoted_size (const char *type);
 647
 648
 649 /* The following functions are used when parsing the type encoding of
 650    methods, to skip over parts that are ignored.  They take as
 651    argument a pointer to a location inside the type encoding of a
 652    method (which is a string) and return a new pointer, pointing to a
 653    new location inside the string after having skipped the unwanted
 654    information.  */
 655
 656 /* Skip some type qualifiers (_C_CONST, _C_IN, etc).  These may
 657   eventually precede typespecs occurring in method prototype
 658   encodings.  */
 659 const char *objc_skip_type_qualifiers (const char *type);
 660
 661 /* Skip one typespec element (_C_CLASS, _C_SEL, etc).  If the typespec
 662   is prepended by type qualifiers, these are skipped as well.  */
 663 const char *objc_skip_typespec (const char *type);
 664
 665 /* Skip an offset.  */
 666 const char *objc_skip_offset (const char *type);
 667
 668 /* Skip an argument specification (ie, skipping a typespec, which may
 669    include qualifiers, and an offset too).  */
 670 const char *objc_skip_argspec (const char *type);
 671
 672 /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type'
 673    (stopping at the first non-type qualifier found) and return an
 674    unsigned int which is the logical OR of all the corresponding flags
 675    (_F_CONST, _F_IN etc).  */
 676 unsigned objc_get_type_qualifiers (const char *type);
 677
 678
 679 /* Note that the following functions work for very simple structures,
 680    but get easily confused by more complicated ones (for example,
 681    containing vectors).  A better solution is required.
 682 */
 683
 684 /* The following three functions can be used to determine how a
 685    structure is laid out by the compiler. For example:
 686
 687   struct objc_struct_layout layout;
 688   int i;
 689
 690   objc_layout_structure (type, &layout);
 691   while (objc_layout_structure_next_member (&layout))
 692     {
 693       int position, align;
 694       const char *type;
 695
 696       objc_layout_structure_get_info (&layout, &position, &align, &type);
 697       printf ("element %d has offset %d, alignment %d\n",
 698               i++, position, align);
 699     }
 700
 701   These functions are used by objc_sizeof_type and objc_alignof_type
 702   functions to compute the size and alignment of structures. The
 703   previous method of computing the size and alignment of a structure
 704   was not working on some architectures, particulary on AIX, and in
 705   the presence of bitfields inside the structure.  */
 706 struct objc_struct_layout
 707 {
 708   const char *original_type;
 709   const char *type;
 710   const char *prev_type;
 711   unsigned int record_size;
 712   unsigned int record_align;
 713 };
 714
 715 void objc_layout_structure (const char *type,
 716                             struct objc_struct_layout *layout);
 717 BOOL  objc_layout_structure_next_member (struct objc_struct_layout *layout);
 718 void objc_layout_finish_structure (struct objc_struct_layout *layout,
 719                                    unsigned int *size,
 720                                    unsigned int *align);
 721 void objc_layout_structure_get_info (struct objc_struct_layout *layout,
 722                                      unsigned int *offset,
 723                                      unsigned int *align,
 724                                      const char **type);
 725
 726 #endif