object.h (11082B) - Raw
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 #include <os/availability.h> 27 #include <TargetConditionals.h> 28 #include <os/base.h> 29 #elif defined(_WIN32) 30 #include <os/generic_win_base.h> 31 #elif defined(__unix__) 32 #include <os/generic_unix_base.h> 33 #endif 34 35 /*! 36 * @header 37 * 38 * @preprocinfo 39 * By default, libSystem objects such as GCD and XPC objects are declared as 40 * Objective-C types when building with an Objective-C compiler. This allows 41 * them to participate in ARC, in RR management by the Blocks runtime and in 42 * leaks checking by the static analyzer, and enables them to be added to Cocoa 43 * collections. 44 * 45 * NOTE: this requires explicit cancellation of dispatch sources and xpc 46 * connections whose handler blocks capture the source/connection object, 47 * resp. ensuring that such captures do not form retain cycles (e.g. by 48 * declaring the source as __weak). 49 * 50 * To opt-out of this default behavior, add -DOS_OBJECT_USE_OBJC=0 to your 51 * compiler flags. 52 * 53 * This mode requires a platform with the modern Objective-C runtime, the 54 * Objective-C GC compiler option to be disabled, and at least a Mac OS X 10.8 55 * or iOS 6.0 deployment target. 56 */ 57 58 #define OS_OBJECT_ASSUME_ABI_SINGLE_BEGIN OS_ASSUME_PTR_ABI_SINGLE_BEGIN 59 #define OS_OBJECT_ASSUME_ABI_SINGLE_END OS_ASSUME_PTR_ABI_SINGLE_END 60 61 #ifndef OS_OBJECT_HAVE_OBJC_SUPPORT 62 #if !defined(__OBJC__) || defined(__OBJC_GC__) 63 # define OS_OBJECT_HAVE_OBJC_SUPPORT 0 64 #elif !defined(TARGET_OS_MAC) || !TARGET_OS_MAC 65 # define OS_OBJECT_HAVE_OBJC_SUPPORT 0 66 #elif TARGET_OS_IOS && __IPHONE_OS_VERSION_MIN_REQUIRED < __IPHONE_6_0 67 # define OS_OBJECT_HAVE_OBJC_SUPPORT 0 68 #elif TARGET_OS_MAC && !TARGET_OS_IPHONE 69 # if __MAC_OS_X_VERSION_MIN_REQUIRED < __MAC_10_8 70 # define OS_OBJECT_HAVE_OBJC_SUPPORT 0 71 # elif defined(__i386__) && __MAC_OS_X_VERSION_MIN_REQUIRED < __MAC_10_12 72 # define OS_OBJECT_HAVE_OBJC_SUPPORT 0 73 # else 74 # define OS_OBJECT_HAVE_OBJC_SUPPORT 1 75 # endif 76 #else 77 # define OS_OBJECT_HAVE_OBJC_SUPPORT 1 78 #endif 79 #endif // OS_OBJECT_HAVE_OBJC_SUPPORT 80 81 #if OS_OBJECT_HAVE_OBJC_SUPPORT 82 #if defined(__swift__) && __swift__ && !OS_OBJECT_USE_OBJC 83 #define OS_OBJECT_USE_OBJC 1 84 #endif 85 #ifndef OS_OBJECT_USE_OBJC 86 #define OS_OBJECT_USE_OBJC 1 87 #endif 88 #elif defined(OS_OBJECT_USE_OBJC) && OS_OBJECT_USE_OBJC 89 /* Unsupported platform for OS_OBJECT_USE_OBJC=1 */ 90 #undef OS_OBJECT_USE_OBJC 91 #define OS_OBJECT_USE_OBJC 0 92 #else 93 #define OS_OBJECT_USE_OBJC 0 94 #endif 95 96 #ifndef OS_OBJECT_SWIFT3 97 #ifdef __swift__ 98 #define OS_OBJECT_SWIFT3 1 99 #else // __swift__ 100 #define OS_OBJECT_SWIFT3 0 101 #endif // __swift__ 102 #endif // OS_OBJECT_SWIFT3 103 104 #if __has_feature(assume_nonnull) 105 #define OS_OBJECT_ASSUME_NONNULL_BEGIN _Pragma("clang assume_nonnull begin") 106 #define OS_OBJECT_ASSUME_NONNULL_END _Pragma("clang assume_nonnull end") 107 #else 108 #define OS_OBJECT_ASSUME_NONNULL_BEGIN 109 #define OS_OBJECT_ASSUME_NONNULL_END 110 #endif 111 #define OS_OBJECT_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__)) 112 113 #if OS_OBJECT_USE_OBJC 114 #import <objc/NSObject.h> 115 #if __has_attribute(objc_independent_class) 116 #define OS_OBJC_INDEPENDENT_CLASS __attribute__((objc_independent_class)) 117 #endif // __has_attribute(objc_independent_class) 118 #ifndef OS_OBJC_INDEPENDENT_CLASS 119 #define OS_OBJC_INDEPENDENT_CLASS 120 #endif 121 #define OS_OBJECT_CLASS(name) OS_##name 122 #define OS_OBJECT_DECL_PROTOCOL(name, ...) \ 123 @protocol OS_OBJECT_CLASS(name) __VA_ARGS__ \ 124 @end 125 #define OS_OBJECT_CLASS_IMPLEMENTS_PROTOCOL_IMPL(name, proto) \ 126 @interface name () <proto> \ 127 @end 128 #define OS_OBJECT_CLASS_IMPLEMENTS_PROTOCOL(name, proto) \ 129 OS_OBJECT_CLASS_IMPLEMENTS_PROTOCOL_IMPL( \ 130 OS_OBJECT_CLASS(name), OS_OBJECT_CLASS(proto)) 131 #define OS_OBJECT_DECL_IMPL(name, adhere, ...) \ 132 OS_OBJECT_DECL_PROTOCOL(name, __VA_ARGS__) \ 133 typedef adhere<OS_OBJECT_CLASS(name)> \ 134 * OS_OBJC_INDEPENDENT_CLASS name##_t 135 #define OS_OBJECT_DECL_BASE(name, ...) \ 136 @interface OS_OBJECT_CLASS(name) : __VA_ARGS__ \ 137 - (instancetype)init OS_SWIFT_UNAVAILABLE("Unavailable in Swift"); \ 138 @end 139 #define OS_OBJECT_DECL_IMPL_CLASS(name, ...) \ 140 OS_OBJECT_DECL_BASE(name, ## __VA_ARGS__) \ 141 typedef OS_OBJECT_CLASS(name) \ 142 * OS_OBJC_INDEPENDENT_CLASS name##_t 143 #define OS_OBJECT_DECL(name, ...) \ 144 OS_OBJECT_DECL_IMPL(name, NSObject, <NSObject>) 145 #define OS_OBJECT_DECL_SUBCLASS(name, super) \ 146 OS_OBJECT_DECL_IMPL(name, NSObject, <OS_OBJECT_CLASS(super)>) 147 #if __has_attribute(ns_returns_retained) 148 #define OS_OBJECT_RETURNS_RETAINED __attribute__((__ns_returns_retained__)) 149 #else 150 #define OS_OBJECT_RETURNS_RETAINED 151 #endif 152 #if __has_attribute(ns_consumed) 153 #define OS_OBJECT_CONSUMED __attribute__((__ns_consumed__)) 154 #else 155 #define OS_OBJECT_CONSUMED 156 #endif 157 #if __has_feature(objc_arc) 158 #define OS_OBJECT_BRIDGE __bridge 159 #define OS_WARN_RESULT_NEEDS_RELEASE 160 #else 161 #define OS_OBJECT_BRIDGE 162 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT 163 #endif 164 165 166 #if __has_attribute(objc_runtime_visible) && \ 167 ((defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && \ 168 __MAC_OS_X_VERSION_MIN_REQUIRED < __MAC_10_12) || \ 169 (defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && \ 170 !defined(__TV_OS_VERSION_MIN_REQUIRED) && \ 171 !defined(__WATCH_OS_VERSION_MIN_REQUIRED) && \ 172 __IPHONE_OS_VERSION_MIN_REQUIRED < __IPHONE_10_0) || \ 173 (defined(__TV_OS_VERSION_MIN_REQUIRED) && \ 174 __TV_OS_VERSION_MIN_REQUIRED < __TVOS_10_0) || \ 175 (defined(__WATCH_OS_VERSION_MIN_REQUIRED) && \ 176 __WATCH_OS_VERSION_MIN_REQUIRED < __WATCHOS_3_0)) 177 /* 178 * To provide backward deployment of ObjC objects in Swift on pre-10.12 179 * SDKs, OS_object classes can be marked as OS_OBJECT_OBJC_RUNTIME_VISIBLE. 180 * When compiling with a deployment target earlier than OS X 10.12 (iOS 10.0, 181 * tvOS 10.0, watchOS 3.0) the Swift compiler will only refer to this type at 182 * runtime (using the ObjC runtime). 183 */ 184 #define OS_OBJECT_OBJC_RUNTIME_VISIBLE __attribute__((objc_runtime_visible)) 185 #else 186 #define OS_OBJECT_OBJC_RUNTIME_VISIBLE 187 #endif 188 #ifndef OS_OBJECT_USE_OBJC_RETAIN_RELEASE 189 #if defined(__clang_analyzer__) 190 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1 191 #elif __has_feature(objc_arc) && !OS_OBJECT_SWIFT3 192 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1 193 #else 194 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0 195 #endif 196 #endif 197 198 #if __has_attribute(__swift_attr__) 199 #define OS_OBJECT_SWIFT_SENDABLE __attribute__((swift_attr("@Sendable"))) 200 #define OS_OBJECT_SWIFT_HAS_MISSING_DESIGNATED_INIT \ 201 __attribute__((swift_attr("@_hasMissingDesignatedInitializers"))) 202 #else 203 #define OS_OBJECT_SWIFT_SENDABLE 204 #define OS_OBJECT_SWIFT_HAS_MISSING_DESIGNATED_INIT 205 #endif // __has_attribute(__swift_attr__) 206 207 #if OS_OBJECT_SWIFT3 208 #define OS_OBJECT_DECL_SWIFT(name) \ 209 OS_EXPORT OS_OBJECT_OBJC_RUNTIME_VISIBLE \ 210 OS_OBJECT_DECL_IMPL_CLASS(name, NSObject) 211 #define OS_OBJECT_DECL_SENDABLE_SWIFT(name) \ 212 OS_EXPORT OS_OBJECT_OBJC_RUNTIME_VISIBLE OS_OBJECT_SWIFT_SENDABLE \ 213 OS_OBJECT_DECL_IMPL_CLASS(name, NSObject) 214 #define OS_OBJECT_DECL_SUBCLASS_SWIFT(name, super) \ 215 OS_EXPORT OS_OBJECT_OBJC_RUNTIME_VISIBLE \ 216 OS_OBJECT_DECL_IMPL_CLASS(name, OS_OBJECT_CLASS(super)) 217 #define OS_OBJECT_DECL_SENDABLE_SUBCLASS_SWIFT(name, super) \ 218 OS_EXPORT OS_OBJECT_OBJC_RUNTIME_VISIBLE OS_OBJECT_SWIFT_SENDABLE \ 219 OS_OBJECT_DECL_IMPL_CLASS(name, OS_OBJECT_CLASS(super)) 220 #endif // OS_OBJECT_SWIFT3 221 OS_EXPORT OS_OBJECT_OBJC_RUNTIME_VISIBLE 222 OS_OBJECT_DECL_BASE(object, NSObject); 223 #else 224 /*! @parseOnly */ 225 #define OS_OBJECT_RETURNS_RETAINED 226 /*! @parseOnly */ 227 #define OS_OBJECT_CONSUMED 228 /*! @parseOnly */ 229 #define OS_OBJECT_BRIDGE 230 /*! @parseOnly */ 231 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT 232 /*! @parseOnly */ 233 #define OS_OBJECT_OBJC_RUNTIME_VISIBLE 234 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0 235 #endif 236 237 #if OS_OBJECT_SWIFT3 238 #define OS_OBJECT_DECL_CLASS(name) \ 239 OS_OBJECT_DECL_SUBCLASS_SWIFT(name, object) 240 #define OS_OBJECT_DECL_SENDABLE_CLASS(name) \ 241 OS_OBJECT_DECL_SENDABLE_SUBCLASS_SWIFT(name, object) 242 #elif OS_OBJECT_USE_OBJC 243 #define OS_OBJECT_DECL_CLASS(name) \ 244 OS_OBJECT_DECL(name) 245 #define OS_OBJECT_DECL_SENDABLE_CLASS(name) \ 246 OS_OBJECT_DECL(name) 247 #else 248 #define OS_OBJECT_DECL_CLASS(name) \ 249 typedef struct name##_s *name##_t 250 #define OS_OBJECT_DECL_SENDABLE_CLASS(name) \ 251 typedef struct name##_s *name##_t 252 #endif 253 254 #if OS_OBJECT_USE_OBJC 255 /* Declares a class of the specific name and exposes the interface and typedefs 256 * name##_t to the pointer to the class */ 257 #define OS_OBJECT_SHOW_CLASS(name, ...) \ 258 OS_EXPORT OS_OBJECT_OBJC_RUNTIME_VISIBLE \ 259 OS_OBJECT_DECL_IMPL_CLASS(name, ## __VA_ARGS__ ) 260 /* Declares a subclass of the same name, and 261 * subclass adheres to protocol specified. Typedefs baseclass<proto> * to subclass##_t */ 262 #define OS_OBJECT_SHOW_SUBCLASS(subclass_name, super, proto_name) \ 263 OS_EXPORT OS_OBJECT_OBJC_RUNTIME_VISIBLE \ 264 OS_OBJECT_DECL_BASE(subclass_name, OS_OBJECT_CLASS(super)<OS_OBJECT_CLASS(proto_name)>); \ 265 typedef OS_OBJECT_CLASS(super)<OS_OBJECT_CLASS(proto_name)> \ 266 * OS_OBJC_INDEPENDENT_CLASS subclass_name##_t 267 #else /* Plain C */ 268 #define OS_OBJECT_DECL_PROTOCOL(name, ...) 269 #define OS_OBJECT_SHOW_CLASS(name, ...) \ 270 typedef struct name##_s *name##_t 271 #define OS_OBJECT_SHOW_SUBCLASS(name, super, ...) \ 272 typedef super##_t name##_t 273 #endif 274 275 #define OS_OBJECT_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object)) 276 277 __BEGIN_DECLS 278 OS_OBJECT_ASSUME_ABI_SINGLE_BEGIN 279 280 /*! 281 * @function os_retain 282 * 283 * @abstract 284 * Increment the reference count of an os_object. 285 * 286 * @discussion 287 * On a platform with the modern Objective-C runtime this is exactly equivalent 288 * to sending the object the -[retain] message. 289 * 290 * @param object 291 * The object to retain. 292 * 293 * @result 294 * The retained object. 295 */ 296 API_AVAILABLE(macos(10.10), ios(8.0)) 297 OS_EXPORT OS_SWIFT_UNAVAILABLE("Can't be used with ARC") 298 void* 299 os_retain(void *object); 300 #if OS_OBJECT_USE_OBJC 301 #undef os_retain 302 #define os_retain(object) [object retain] 303 #endif 304 305 /*! 306 * @function os_release 307 * 308 * @abstract 309 * Decrement the reference count of a os_object. 310 * 311 * @discussion 312 * On a platform with the modern Objective-C runtime this is exactly equivalent 313 * to sending the object the -[release] message. 314 * 315 * @param object 316 * The object to release. 317 */ 318 API_AVAILABLE(macos(10.10), ios(8.0)) 319 OS_EXPORT 320 void OS_SWIFT_UNAVAILABLE("Can't be used with ARC") 321 os_release(void *object); 322 #if OS_OBJECT_USE_OBJC 323 #undef os_release 324 #define os_release(object) [object release] 325 #endif 326 327 OS_OBJECT_ASSUME_ABI_SINGLE_END 328 __END_DECLS 329 330 #endif