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