runtime/objc-auto.h

   1 /*
   2  * Copyright (c) 2004-2007 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _OBJC_AUTO_H_
  25 #define _OBJC_AUTO_H_
  26
  27 #include <objc/objc.h>
  28 #include <stdint.h>
  29 #include <stddef.h>
  30 #include <string.h>
  31 #include <Availability.h>
  32 #include <AvailabilityMacros.h>
  33 #include <TargetConditionals.h>
  34
  35 #if !TARGET_OS_WIN32
  36 #include <sys/types.h>
  37 #include <libkern/OSAtomic.h>
  38 #else
  39 #   define WINVER 0x0501                // target Windows XP and later
  40 #   define _WIN32_WINNT 0x0501  // target Windows XP and later
  41 #   define WIN32_LEAN_AND_MEAN
  42 // workaround: windef.h typedefs BOOL as int
  43 #   define BOOL WINBOOL
  44 #   include <windows.h>
  45 #   undef BOOL
  46 #endif
  47
  48
  49 /* GC is unsupported on some architectures. */
  50
  51 #if TARGET_OS_EMBEDDED  ||  TARGET_OS_WIN32
  52 #   define OBJC_NO_GC 1
  53 #endif
  54
  55 #ifdef OBJC_NO_GC
  56 #   define OBJC_GC_EXPORT static
  57 #else
  58 #   define OBJC_GC_EXPORT OBJC_EXPORT
  59 #endif
  60
  61
  62 /* objc_collect() options */
  63 enum {
  64     // choose one
  65     OBJC_RATIO_COLLECTION        = (0 << 0),  // run "ratio" generational collections, then a full
  66     OBJC_GENERATIONAL_COLLECTION = (1 << 0),  // run fast incremental collection
  67     OBJC_FULL_COLLECTION         = (2 << 0),  // run full collection.
  68     OBJC_EXHAUSTIVE_COLLECTION   = (3 << 0),  // run full collections until memory available stops improving
  69
  70     OBJC_COLLECT_IF_NEEDED       = (1 << 3), // run collection only if needed (allocation threshold exceeded)
  71     OBJC_WAIT_UNTIL_DONE         = (1 << 4), // wait (when possible) for collection to end before returning (when collector is running on dedicated thread)
  72 };
  73
  74 /* objc_clear_stack() options */
  75 enum {
  76     OBJC_CLEAR_RESIDENT_STACK = (1 << 0)
  77 };
  78
  79
  80 /* Collection utilities */
  81
  82 OBJC_GC_EXPORT void objc_collect(unsigned long options);
  83 OBJC_GC_EXPORT BOOL objc_collectingEnabled(void);
  84
  85
  86 /* GC configuration */
  87
  88 /* Tells collector to wait until specified bytes have been allocated before trying to collect again. */
  89 OBJC_GC_EXPORT void objc_setCollectionThreshold(size_t threshold);
  90
  91 /* Tells collector to run a full collection for every ratio generational collections. */
  92 OBJC_GC_EXPORT void objc_setCollectionRatio(size_t ratio);
  93
  94 /* Tells collector to start collecting on dedicated thread */
  95 OBJC_GC_EXPORT void objc_startCollectorThread(void);
  96
  97 /* Atomic update, with write barrier. */
  98 OBJC_GC_EXPORT BOOL objc_atomicCompareAndSwapPtr(id predicate, id replacement, volatile id *objectLocation) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
  99 /* "Barrier" version also includes memory barrier. */
 100 OBJC_GC_EXPORT BOOL objc_atomicCompareAndSwapPtrBarrier(id predicate, id replacement, volatile id *objectLocation) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
 101
 102 // atomic update of a global variable
 103 OBJC_GC_EXPORT BOOL objc_atomicCompareAndSwapGlobal(id predicate, id replacement, volatile id *objectLocation);
 104 OBJC_GC_EXPORT BOOL objc_atomicCompareAndSwapGlobalBarrier(id predicate, id replacement, volatile id *objectLocation);
 105 // atomic update of an instance variable
 106 OBJC_GC_EXPORT BOOL objc_atomicCompareAndSwapInstanceVariable(id predicate, id replacement, volatile id *objectLocation);
 107 OBJC_GC_EXPORT BOOL objc_atomicCompareAndSwapInstanceVariableBarrier(id predicate, id replacement, volatile id *objectLocation);
 108
 109
 110 /* Write barriers.  Used by the compiler.  */
 111 OBJC_GC_EXPORT id objc_assign_strongCast(id val, id *dest);
 112 OBJC_GC_EXPORT id objc_assign_global(id val, id *dest);
 113 OBJC_GC_EXPORT id objc_assign_ivar(id value, id dest, ptrdiff_t offset);
 114 OBJC_GC_EXPORT void *objc_memmove_collectable(void *dst, const void *src, size_t size);
 115
 116 OBJC_GC_EXPORT id objc_read_weak(id *location);
 117 OBJC_GC_EXPORT id objc_assign_weak(id value, id *location);
 118
 119
 120 //
 121 // SPI. The following routines are available as debugging and transitional aides.
 122 //
 123
 124 /* Tells runtime to issue finalize calls on the main thread only. */
 125 OBJC_GC_EXPORT void objc_finalizeOnMainThread(Class cls)
 126     AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER_BUT_DEPRECATED;
 127
 128
 129 /* Returns true if object has been scheduled for finalization.  Can be used to avoid operations that may lead to resurrection, which are fatal. */
 130 OBJC_GC_EXPORT BOOL objc_is_finalized(void *ptr);
 131
 132 /* Stack management */
 133 OBJC_GC_EXPORT void objc_clear_stack(unsigned long options);
 134
 135 //
 136 // Obsolete.  Present only until all uses can be migrated to newer API.
 137 //
 138
 139 OBJC_GC_EXPORT BOOL objc_collecting_enabled(void);
 140 OBJC_GC_EXPORT void objc_set_collection_threshold(size_t threshold);
 141 OBJC_GC_EXPORT void objc_set_collection_ratio(size_t ratio);
 142 OBJC_GC_EXPORT void objc_start_collector_thread(void);
 143
 144 /* Memory management */
 145 OBJC_EXPORT id objc_allocate_object(Class cls, int extra);
 146
 147 /* Register/unregister the current thread with the garbage collector. */
 148 OBJC_GC_EXPORT void objc_registerThreadWithCollector();
 149 OBJC_GC_EXPORT void objc_unregisterThreadWithCollector();
 150
 151 /* To be called from code which must only execute on a registered thread. */
 152 /* If the calling thread is unregistered then an error message is emitted and the thread is implicitly registered. */
 153 OBJC_GC_EXPORT void objc_assertRegisteredThreadWithCollector();
 154
 155 #ifdef OBJC_NO_GC
 156
 157 /* Non-GC versions */
 158
 159 static OBJC_INLINE void objc_collect(unsigned long options) { }
 160 static OBJC_INLINE BOOL objc_collectingEnabled(void) { return NO; }
 161 static OBJC_INLINE void objc_setCollectionThreshold(size_t threshold) { }
 162 static OBJC_INLINE void objc_setCollectionRatio(size_t ratio) { }
 163 static OBJC_INLINE void objc_startCollectorThread(void) { }
 164
 165 #if TARGET_OS_WIN32
 166 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtr(id predicate, id replacement, volatile id *objectLocation)
 167     { void *original = InterlockedCompareExchangePointer((void * volatile *)objectLocation, (void *)replacement, (void *)predicate); return (original == predicate); }
 168
 169 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtrBarrier(id predicate, id replacement, volatile id *objectLocation)
 170     { void *original = InterlockedCompareExchangePointer((void * volatile *)objectLocation, (void *)replacement, (void *)predicate); return (original == predicate); }
 171 #else
 172 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtr(id predicate, id replacement, volatile id *objectLocation)
 173     { return OSAtomicCompareAndSwapPtr((void *)predicate, (void *)replacement, (void * volatile *)objectLocation); }
 174
 175 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtrBarrier(id predicate, id replacement, volatile id *objectLocation)
 176     { return OSAtomicCompareAndSwapPtrBarrier((void *)predicate, (void *)replacement, (void * volatile *)objectLocation); }
 177 #endif
 178
 179 static OBJC_INLINE BOOL objc_atomicCompareAndSwapGlobal(id predicate, id replacement, volatile id *objectLocation)
 180     { return objc_atomicCompareAndSwapPtr(predicate, replacement, objectLocation); }
 181
 182 static OBJC_INLINE BOOL objc_atomicCompareAndSwapGlobalBarrier(id predicate, id replacement, volatile id *objectLocation)
 183     { return objc_atomicCompareAndSwapPtrBarrier(predicate, replacement, objectLocation); }
 184
 185 static OBJC_INLINE BOOL objc_atomicCompareAndSwapInstanceVariable(id predicate, id replacement, volatile id *objectLocation)
 186     { return objc_atomicCompareAndSwapPtr(predicate, replacement, objectLocation); }
 187
 188 static OBJC_INLINE BOOL objc_atomicCompareAndSwapInstanceVariableBarrier(id predicate, id replacement, volatile id *objectLocation)
 189     { return objc_atomicCompareAndSwapPtrBarrier(predicate, replacement, objectLocation); }
 190
 191
 192 static OBJC_INLINE id objc_assign_strongCast(id val, id *dest)
 193     { return (*dest = val); }
 194
 195 static OBJC_INLINE id objc_assign_global(id val, id *dest)
 196     { return (*dest = val); }
 197
 198 static OBJC_INLINE id objc_assign_ivar(id val, id dest, ptrdiff_t offset)
 199     { return (*(id*)((char *)dest+offset) = val); }
 200
 201 static OBJC_INLINE void *objc_memmove_collectable(void *dst, const void *src, size_t size)
 202     { return memmove(dst, src, size); }
 203
 204 static OBJC_INLINE id objc_read_weak(id *location)
 205     { return *location; }
 206
 207 static OBJC_INLINE id objc_assign_weak(id value, id *location)
 208     { return (*location = value); }
 209
 210
 211 static OBJC_INLINE void objc_finalizeOnMainThread(Class cls) { }
 212 static OBJC_INLINE BOOL objc_is_finalized(void *ptr) { return NO; }
 213 static OBJC_INLINE void objc_clear_stack(unsigned long options) { }
 214
 215 static OBJC_INLINE BOOL objc_collecting_enabled(void) { return NO; }
 216 static OBJC_INLINE void objc_set_collection_threshold(size_t threshold) { }
 217 static OBJC_INLINE void objc_set_collection_ratio(size_t ratio) { }
 218 static OBJC_INLINE void objc_start_collector_thread(void) { }
 219
 220 OBJC_EXPORT id class_createInstance(Class cls, size_t extraBytes);
 221 static OBJC_INLINE id objc_allocate_object(Class cls, int extra)
 222     { return class_createInstance(cls, extra); }
 223
 224 static OBJC_INLINE void objc_registerThreadWithCollector() { }
 225 static OBJC_INLINE void objc_unregisterThreadWithCollector() { }
 226 static OBJC_INLINE void objc_assertRegisteredThreadWithCollector() { }
 227
 228 #endif
 229 #endif