1/*
2 * Copyright (c) 2011-2014 Apple Inc. All rights reserved.
3 *
4 * @APPLE_APACHE_LICENSE_HEADER_START@
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 *     http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 *
18 * @APPLE_APACHE_LICENSE_HEADER_END@
19 */
20
21#ifndef __OS_OBJECT__
22#define __OS_OBJECT__
23
24#ifdef __APPLE__
25#include <Availability.h>
26#endif
27#include <os/base.h>
28
29/*!
30 * @header
31 *
32 * @preprocinfo
33 * By default, libSystem objects such as GCD and XPC objects are declared as
34 * Objective-C types when building with an Objective-C compiler. This allows
35 * them to participate in ARC, in RR management by the Blocks runtime and in
36 * leaks checking by the static analyzer, and enables them to be added to Cocoa
37 * collections.
38 *
39 * NOTE: this requires explicit cancellation of dispatch sources and xpc
40 *       connections whose handler blocks capture the source/connection object,
41 *       resp. ensuring that such captures do not form retain cycles (e.g. by
42 *       declaring the source as __weak).
43 *
44 * To opt-out of this default behavior, add -DOS_OBJECT_USE_OBJC=0 to your
45 * compiler flags.
46 *
47 * This mode requires a platform with the modern Objective-C runtime, the
48 * Objective-C GC compiler option to be disabled, and at least a Mac OS X 10.8
49 * or iOS 6.0 deployment target.
50 */
51
52#ifndef OS_OBJECT_HAVE_OBJC_SUPPORT
53#if defined(__OBJC__) && defined(__OBJC2__) && !defined(__OBJC_GC__) && ( \
54		__MAC_OS_X_VERSION_MIN_REQUIRED >= __MAC_10_8 || \
55		__IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_6_0)
56#define OS_OBJECT_HAVE_OBJC_SUPPORT 1
57#else
58#define OS_OBJECT_HAVE_OBJC_SUPPORT 0
59#endif
60#endif
61
62#if OS_OBJECT_HAVE_OBJC_SUPPORT
63#ifndef OS_OBJECT_USE_OBJC
64#define OS_OBJECT_USE_OBJC 1
65#endif
66#elif defined(OS_OBJECT_USE_OBJC) && OS_OBJECT_USE_OBJC
67/* Unsupported platform for OS_OBJECT_USE_OBJC=1 */
68#undef OS_OBJECT_USE_OBJC
69#define OS_OBJECT_USE_OBJC 0
70#else
71#define OS_OBJECT_USE_OBJC 0
72#endif
73
74#if OS_OBJECT_USE_OBJC
75#import <objc/NSObject.h>
76#define OS_OBJECT_CLASS(name) OS_##name
77#define OS_OBJECT_DECL(name, ...) \
78		@protocol OS_OBJECT_CLASS(name) __VA_ARGS__ \
79		@end \
80		typedef NSObject<OS_OBJECT_CLASS(name)> *name##_t
81#define OS_OBJECT_DECL_SUBCLASS(name, super) \
82		OS_OBJECT_DECL(name, <OS_OBJECT_CLASS(super)>)
83#if defined(__has_attribute)
84#if __has_attribute(ns_returns_retained)
85#define OS_OBJECT_RETURNS_RETAINED __attribute__((__ns_returns_retained__))
86#else
87#define OS_OBJECT_RETURNS_RETAINED
88#endif
89#if __has_attribute(ns_consumed)
90#define OS_OBJECT_CONSUMED __attribute__((__ns_consumed__))
91#else
92#define OS_OBJECT_CONSUMED
93#endif
94#else
95#define OS_OBJECT_RETURNS_RETAINED
96#define OS_OBJECT_CONSUMED
97#endif
98#if defined(__has_feature)
99#if __has_feature(objc_arc)
100#define OS_OBJECT_BRIDGE __bridge
101#define OS_WARN_RESULT_NEEDS_RELEASE
102#else
103#define OS_OBJECT_BRIDGE
104#define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
105#endif
106#else
107#define OS_OBJECT_BRIDGE
108#define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
109#endif
110#ifndef OS_OBJECT_USE_OBJC_RETAIN_RELEASE
111#if defined(__clang_analyzer__)
112#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
113#elif defined(__has_feature)
114#if __has_feature(objc_arc)
115#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
116#else
117#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
118#endif
119#else
120#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
121#endif
122#endif
123#else
124/*! @parseOnly */
125#define OS_OBJECT_RETURNS_RETAINED
126/*! @parseOnly */
127#define OS_OBJECT_CONSUMED
128/*! @parseOnly */
129#define OS_OBJECT_BRIDGE
130/*! @parseOnly */
131#define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
132#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
133#endif
134
135#define OS_OBJECT_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object))
136
137__BEGIN_DECLS
138
139/*!
140 * @function os_retain
141 *
142 * @abstract
143 * Increment the reference count of an os_object.
144 *
145 * @discussion
146 * On a platform with the modern Objective-C runtime this is exactly equivalent
147 * to sending the object the -[retain] message.
148 *
149 * @param object
150 * The object to retain.
151 *
152 * @result
153 * The retained object.
154 */
155__OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
156OS_EXPORT
157void*
158os_retain(void *object);
159#if OS_OBJECT_USE_OBJC
160#undef os_retain
161#define os_retain(object) [object retain]
162#endif
163
164/*!
165 * @function os_release
166 *
167 * @abstract
168 * Decrement the reference count of a os_object.
169 *
170 * @discussion
171 * On a platform with the modern Objective-C runtime this is exactly equivalent
172 * to sending the object the -[release] message.
173 *
174 * @param object
175 * The object to release.
176 */
177__OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
178OS_EXPORT
179void
180os_release(void *object);
181#if OS_OBJECT_USE_OBJC
182#undef os_release
183#define os_release(object) [object release]
184#endif
185
186__END_DECLS
187
188#endif
189