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 #pragma GCC system_header
  28
  29 #include <objc/objc.h>
  30 #include <malloc/malloc.h>
  31 #include <stdint.h>
  32 #include <stddef.h>
  33 #include <string.h>
  34 #include <Availability.h>
  35 #include <TargetConditionals.h>
  36
  37 #if !TARGET_OS_WIN32
  38 #include <sys/types.h>
  39 #include <libkern/OSAtomic.h>
  40 #else
  41 #   define WINVER 0x0501                // target Windows XP and later
  42 #   define _WIN32_WINNT 0x0501  // target Windows XP and later
  43 #   define WIN32_LEAN_AND_MEAN
  44 // workaround: windef.h typedefs BOOL as int
  45 #   define BOOL WINBOOL
  46 #   include <windows.h>
  47 #   undef BOOL
  48 #endif
  49
  50
  51 /* objc_collect() options */
  52 enum {
  53     // choose one
  54     OBJC_RATIO_COLLECTION        = (0 << 0),  // run "ratio" generational collections, then a full
  55     OBJC_GENERATIONAL_COLLECTION = (1 << 0),  // run fast incremental collection
  56     OBJC_FULL_COLLECTION         = (2 << 0),  // run full collection.
  57     OBJC_EXHAUSTIVE_COLLECTION   = (3 << 0),  // run full collections until memory available stops improving
  58
  59     OBJC_COLLECT_IF_NEEDED       = (1 << 3), // run collection only if needed (allocation threshold exceeded)
  60     OBJC_WAIT_UNTIL_DONE         = (1 << 4), // wait (when possible) for collection to end before returning (when collector is running on dedicated thread)
  61 };
  62
  63 /* objc_clear_stack() options */
  64 enum {
  65     OBJC_CLEAR_RESIDENT_STACK = (1 << 0)
  66 };
  67
  68 #ifndef OBJC_NO_GC
  69
  70
  71 /* GC declarations */
  72
  73 /* Collection utilities */
  74
  75 OBJC_EXPORT void objc_collect(unsigned long options)
  76     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
  77 OBJC_EXPORT BOOL objc_collectingEnabled(void)
  78     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
  79 OBJC_EXPORT malloc_zone_t *objc_collectableZone(void)
  80     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  81
  82 /* GC configuration */
  83
  84 /* Tells collector to wait until specified bytes have been allocated before trying to collect again. */
  85 OBJC_EXPORT void objc_setCollectionThreshold(size_t threshold)
  86     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
  87
  88 /* Tells collector to run a full collection for every ratio generational collections. */
  89 OBJC_EXPORT void objc_setCollectionRatio(size_t ratio)
  90     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
  91
  92 //
  93 // GC-safe compare-and-swap
  94 //
  95
  96 /* Atomic update, with write barrier. */
  97 OBJC_EXPORT BOOL objc_atomicCompareAndSwapPtr(id predicate, id replacement, volatile id *objectLocation)
  98     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA) OBJC_ARC_UNAVAILABLE;
  99 /* "Barrier" version also includes memory barrier. */
 100 OBJC_EXPORT BOOL objc_atomicCompareAndSwapPtrBarrier(id predicate, id replacement, volatile id *objectLocation)
 101     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA) OBJC_ARC_UNAVAILABLE;
 102
 103 // atomic update of a global variable
 104 OBJC_EXPORT BOOL objc_atomicCompareAndSwapGlobal(id predicate, id replacement, volatile id *objectLocation)
 105     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA) OBJC_ARC_UNAVAILABLE;
 106 OBJC_EXPORT BOOL objc_atomicCompareAndSwapGlobalBarrier(id predicate, id replacement, volatile id *objectLocation)
 107     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA) OBJC_ARC_UNAVAILABLE;
 108 // atomic update of an instance variable
 109 OBJC_EXPORT BOOL objc_atomicCompareAndSwapInstanceVariable(id predicate, id replacement, volatile id *objectLocation)
 110     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA) OBJC_ARC_UNAVAILABLE;
 111 OBJC_EXPORT BOOL objc_atomicCompareAndSwapInstanceVariableBarrier(id predicate, id replacement, volatile id *objectLocation)
 112     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA) OBJC_ARC_UNAVAILABLE;
 113
 114
 115 //
 116 // Read and write barriers
 117 //
 118
 119 OBJC_EXPORT id objc_assign_strongCast(id val, id *dest)
 120     __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_NA);
 121 OBJC_EXPORT id objc_assign_global(id val, id *dest)
 122     __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_NA);
 123 OBJC_EXPORT id objc_assign_threadlocal(id val, id *dest)
 124     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 125 OBJC_EXPORT id objc_assign_ivar(id value, id dest, ptrdiff_t offset)
 126     __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_NA);
 127 OBJC_EXPORT void *objc_memmove_collectable(void *dst, const void *src, size_t size)
 128     __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_NA);
 129
 130 OBJC_EXPORT id objc_read_weak(id *location)
 131     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 132 OBJC_EXPORT id objc_assign_weak(id value, id *location)
 133     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 134
 135
 136 //
 137 // Thread management
 138 //
 139
 140 /* Register the calling thread with the garbage collector. */
 141 OBJC_EXPORT void objc_registerThreadWithCollector(void)
 142     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
 143
 144 /* Unregisters the calling thread with the garbage collector.
 145    Unregistration also happens automatically at thread exit. */
 146 OBJC_EXPORT void objc_unregisterThreadWithCollector(void)
 147     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
 148
 149 /* To be called from code which must only execute on a registered thread. */
 150 /* If the calling thread is unregistered then an error message is emitted and the thread is implicitly registered. */
 151 OBJC_EXPORT void objc_assertRegisteredThreadWithCollector(void)
 152     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
 153
 154 /* Erases any stale references in unused parts of the stack. */
 155 OBJC_EXPORT void objc_clear_stack(unsigned long options)
 156     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 157
 158
 159 //
 160 // Finalization
 161 //
 162
 163 /* Returns true if object has been scheduled for finalization.  Can be used to avoid operations that may lead to resurrection, which are fatal. */
 164 OBJC_EXPORT BOOL objc_is_finalized(void *ptr)
 165     __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_NA);
 166
 167 // Deprcated. Tells runtime to issue finalize calls on the main thread only.
 168 OBJC_EXPORT void objc_finalizeOnMainThread(Class cls)
 169     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_5, __IPHONE_NA,__IPHONE_NA);
 170
 171
 172 //
 173 // Deprecated names.
 174 //
 175
 176 /* Deprecated. Use objc_collectingEnabled() instead. */
 177 OBJC_EXPORT BOOL objc_collecting_enabled(void)
 178     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4,__MAC_10_5, __IPHONE_NA,__IPHONE_NA);
 179 /* Deprecated. Use objc_setCollectionThreshold() instead. */
 180 OBJC_EXPORT void objc_set_collection_threshold(size_t threshold)
 181     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4,__MAC_10_5, __IPHONE_NA,__IPHONE_NA);
 182 /* Deprecated. Use objc_setCollectionRatio() instead. */
 183 OBJC_EXPORT void objc_set_collection_ratio(size_t ratio)
 184     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4,__MAC_10_5, __IPHONE_NA,__IPHONE_NA);
 185 /* Deprecated. Use objc_startCollectorThread() instead. */
 186 OBJC_EXPORT void objc_start_collector_thread(void)
 187     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4,__MAC_10_5, __IPHONE_NA,__IPHONE_NA);
 188 /* Deprecated. No replacement. Formerly told the collector to run using a dedicated background thread. */
 189 OBJC_EXPORT void objc_startCollectorThread(void)
 190 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_7, __IPHONE_NA,__IPHONE_NA);
 191
 192
 193 /* Deprecated. Use class_createInstance() instead. */
 194 OBJC_EXPORT id objc_allocate_object(Class cls, int extra)
 195 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4,__MAC_10_4, __IPHONE_NA,__IPHONE_NA);
 196
 197
 198 /* !defined(OBJC_NO_GC) */
 199 #else
 200 /* defined(OBJC_NO_GC) */
 201
 202
 203 /* Non-GC declarations */
 204
 205 static OBJC_INLINE void objc_collect(unsigned long options __unused) { }
 206 static OBJC_INLINE BOOL objc_collectingEnabled(void) { return NO; }
 207 #if TARGET_OS_MAC  &&  !TARGET_OS_EMBEDDED  &&  !TARGET_IPHONE_SIMULATOR
 208 static OBJC_INLINE malloc_zone_t *objc_collectableZone(void) { return nil; }
 209 #endif
 210 static OBJC_INLINE void objc_setCollectionThreshold(size_t threshold __unused) { }
 211 static OBJC_INLINE void objc_setCollectionRatio(size_t ratio __unused) { }
 212 static OBJC_INLINE void objc_startCollectorThread(void) { }
 213
 214 #if __has_feature(objc_arc)
 215
 216 /* Covers for GC memory operations are unavailable in ARC */
 217
 218 #else
 219
 220 #if TARGET_OS_WIN32
 221 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtr(id predicate, id replacement, volatile id *objectLocation)
 222     { void *original = InterlockedCompareExchangePointer((void * volatile *)objectLocation, (void *)replacement, (void *)predicate); return (original == predicate); }
 223
 224 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtrBarrier(id predicate, id replacement, volatile id *objectLocation)
 225     { void *original = InterlockedCompareExchangePointer((void * volatile *)objectLocation, (void *)replacement, (void *)predicate); return (original == predicate); }
 226 #else
 227 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtr(id predicate, id replacement, volatile id *objectLocation)
 228     { return OSAtomicCompareAndSwapPtr((void *)predicate, (void *)replacement, (void * volatile *)objectLocation); }
 229
 230 static OBJC_INLINE BOOL objc_atomicCompareAndSwapPtrBarrier(id predicate, id replacement, volatile id *objectLocation)
 231     { return OSAtomicCompareAndSwapPtrBarrier((void *)predicate, (void *)replacement, (void * volatile *)objectLocation); }
 232 #endif
 233
 234 static OBJC_INLINE BOOL objc_atomicCompareAndSwapGlobal(id predicate, id replacement, volatile id *objectLocation)
 235     { return objc_atomicCompareAndSwapPtr(predicate, replacement, objectLocation); }
 236
 237 static OBJC_INLINE BOOL objc_atomicCompareAndSwapGlobalBarrier(id predicate, id replacement, volatile id *objectLocation)
 238     { return objc_atomicCompareAndSwapPtrBarrier(predicate, replacement, objectLocation); }
 239
 240 static OBJC_INLINE BOOL objc_atomicCompareAndSwapInstanceVariable(id predicate, id replacement, volatile id *objectLocation)
 241     { return objc_atomicCompareAndSwapPtr(predicate, replacement, objectLocation); }
 242
 243 static OBJC_INLINE BOOL objc_atomicCompareAndSwapInstanceVariableBarrier(id predicate, id replacement, volatile id *objectLocation)
 244     { return objc_atomicCompareAndSwapPtrBarrier(predicate, replacement, objectLocation); }
 245
 246
 247 static OBJC_INLINE id objc_assign_strongCast(id val, id *dest)
 248     { return (*dest = val); }
 249
 250 static OBJC_INLINE id objc_assign_global(id val, id *dest)
 251     { return (*dest = val); }
 252
 253 static OBJC_INLINE id objc_assign_threadlocal(id val, id *dest)
 254     { return (*dest = val); }
 255
 256 static OBJC_INLINE id objc_assign_ivar(id val, id dest, ptrdiff_t offset)
 257     { return (*(id*)((char *)dest+offset) = val); }
 258
 259 static OBJC_INLINE id objc_read_weak(id *location)
 260     { return *location; }
 261
 262 static OBJC_INLINE id objc_assign_weak(id value, id *location)
 263     { return (*location = value); }
 264
 265 /* MRC */
 266 #endif
 267
 268 static OBJC_INLINE void *objc_memmove_collectable(void *dst, const void *src, size_t size)
 269     { return memmove(dst, src, size); }
 270
 271 static OBJC_INLINE void objc_finalizeOnMainThread(Class cls __unused) { }
 272 static OBJC_INLINE BOOL objc_is_finalized(void *ptr __unused) { return NO; }
 273 static OBJC_INLINE void objc_clear_stack(unsigned long options __unused) { }
 274
 275 static OBJC_INLINE BOOL objc_collecting_enabled(void) { return NO; }
 276 static OBJC_INLINE void objc_set_collection_threshold(size_t threshold __unused) { }
 277 static OBJC_INLINE void objc_set_collection_ratio(size_t ratio __unused) { }
 278 static OBJC_INLINE void objc_start_collector_thread(void) { }
 279
 280 #if __has_feature(objc_arc)
 281 extern id objc_allocate_object(Class cls, int extra) UNAVAILABLE_ATTRIBUTE;
 282 #else
 283 OBJC_EXPORT id class_createInstance(Class cls, size_t extraBytes)
 284     __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
 285 static OBJC_INLINE id objc_allocate_object(Class cls, int extra)
 286     { return class_createInstance(cls, extra); }
 287 #endif
 288
 289 static OBJC_INLINE void objc_registerThreadWithCollector() { }
 290 static OBJC_INLINE void objc_unregisterThreadWithCollector() { }
 291 static OBJC_INLINE void objc_assertRegisteredThreadWithCollector() { }
 292
 293 /* defined(OBJC_NO_GC) */
 294 #endif
 295
 296
 297 #if TARGET_OS_EMBEDDED
 298 enum {
 299     OBJC_GENERATIONAL = (1 << 0)
 300 };
 301 static OBJC_INLINE void objc_collect_if_needed(unsigned long options) __attribute__((deprecated));
 302 static OBJC_INLINE void objc_collect_if_needed(unsigned long options __unused) { }
 303 #endif
 304
 305 #endif