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