os/object.h

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