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 /*
  45 #ifdef __objc_api_INCLUDE_GNU
  46 # 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.
  47 #endif
  48 */
  49
  50 /* TODO: This file is incomplete.  */
  51
  52 #include "objc.h"
  53
  54 /* 'objc_enumerationMutation()' is called when a collection is
  55    mutated while being "fast enumerated".  That is a hard error, and
  56    objc_enumerationMutation is called to deal with it.  'collection'
  57    is the collection object that was mutated during an enumeration.
  58
  59    objc_enumerationMutation() will invoke the mutation handler if any
  60    is set.  Then, it will abort the program.
  61
  62    Compatibility note: the Apple runtime will not abort the program
  63    after calling the mutation handler.
  64  */
  65 objc_EXPORT void objc_enumerationMutation (id collection);
  66
  67 /* 'objc_set_enumeration_mutation_handler' can be used to set a
  68    function that will be called (instead of aborting) when a fast
  69    enumeration is mutated during enumeration.  The handler will be
  70    called with the 'collection' being mutated as the only argument and
  71    it should not return; it should either exit the program, or could
  72    throw an exception.  The recommended implementation is to throw an
  73    exception - the user can then use exception handlers to deal with
  74    it.
  75
  76    This function is not thread safe (other threads may be trying to
  77    invoke the enumeration mutation handler while you are changing it!)
  78    and should be called during during the program initialization
  79    before threads are started.  It is mostly reserved for "Foundation"
  80    libraries; in the case of GNUstep, GNUstep Base may be using this
  81    function to improve the standard enumeration mutation handling.
  82    You probably shouldn't use this function unless you are writing
  83    your own Foundation library.
  84 */
  85 objc_EXPORT void objc_setEnumerationMutationHandler (void (*handler)(id));
  86
  87 /* This structure (used during fast enumeration) is automatically
  88    defined by the compiler (it is as if this definition was always
  89    included in all Objective-C files).  Note that it is usually
  90    defined again with the name of NSFastEnumeration by "Foundation"
  91    libraries such as GNUstep Base.  And if NSFastEnumeration is
  92    defined, the compiler will use it instead of
  93    __objcFastEnumerationState when doing fast enumeration.
  94 */
  95 /*
  96 struct __objcFastEnumerationState
  97 {
  98   unsigned long state;
  99   id            *itemsPtr;
 100   unsigned long *mutationsPtr;
 101   unsigned long extra[5];
 102 };
 103 */
 104
 105 #endif