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) 156 OS_EXPORT 157 void* 158 os_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) 178 OS_EXPORT 179 void 180 os_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