libkern/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 #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 #if defined(__has_attribute)
  77 #if __has_attribute(objc_independent_class)
  78 #define OS_OBJC_INDEPENDENT_CLASS __attribute__((objc_independent_class))
  79 #endif
  80 #endif // __has_attribute(objc_independent_class)
  81 #ifndef OS_OBJC_INDEPENDENT_CLASS
  82 #define OS_OBJC_INDEPENDENT_CLASS
  83 #endif
  84 #define OS_OBJECT_CLASS(name) OS_##name
  85 #define OS_OBJECT_DECL_IMPL(name, ...) \
  86                 @protocol OS_OBJECT_CLASS(name) __VA_ARGS__ \
  87                 @end \
  88                 typedef NSObject<OS_OBJECT_CLASS(name)> \
  89                                 * OS_OBJC_INDEPENDENT_CLASS name##_t
  90 #define OS_OBJECT_DECL(name, ...) \
  91                 OS_OBJECT_DECL_IMPL(name, <NSObject>)
  92 #define OS_OBJECT_DECL_SUBCLASS(name, super) \
  93                 OS_OBJECT_DECL_IMPL(name, <OS_OBJECT_CLASS(super)>)
  94 #if defined(__has_attribute)
  95 #if __has_attribute(ns_returns_retained)
  96 #define OS_OBJECT_RETURNS_RETAINED __attribute__((__ns_returns_retained__))
  97 #else
  98 #define OS_OBJECT_RETURNS_RETAINED
  99 #endif
 100 #if __has_attribute(ns_consumed)
 101 #define OS_OBJECT_CONSUMED __attribute__((__ns_consumed__))
 102 #else
 103 #define OS_OBJECT_CONSUMED
 104 #endif
 105 #else
 106 #define OS_OBJECT_RETURNS_RETAINED
 107 #define OS_OBJECT_CONSUMED
 108 #endif
 109 #if defined(__has_feature)
 110 #if __has_feature(objc_arc)
 111 #define OS_OBJECT_BRIDGE __bridge
 112 #define OS_WARN_RESULT_NEEDS_RELEASE
 113 #else
 114 #define OS_OBJECT_BRIDGE
 115 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
 116 #endif
 117 #else
 118 #define OS_OBJECT_BRIDGE
 119 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
 120 #endif
 121 #ifndef OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 122 #if defined(__clang_analyzer__)
 123 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
 124 #elif defined(__has_feature)
 125 #if __has_feature(objc_arc)
 126 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
 127 #else
 128 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
 129 #endif
 130 #else
 131 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
 132 #endif
 133 #endif
 134 #else
 135 /*! @parseOnly */
 136 #define OS_OBJECT_RETURNS_RETAINED
 137 /*! @parseOnly */
 138 #define OS_OBJECT_CONSUMED
 139 /*! @parseOnly */
 140 #define OS_OBJECT_BRIDGE
 141 /*! @parseOnly */
 142 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
 143 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
 144 #endif
 145
 146 #define OS_OBJECT_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object))
 147
 148 __BEGIN_DECLS
 149
 150 /*!
 151  * @function os_retain
 152  *
 153  * @abstract
 154  * Increment the reference count of an os_object.
 155  *
 156  * @discussion
 157  * On a platform with the modern Objective-C runtime this is exactly equivalent
 158  * to sending the object the -[retain] message.
 159  *
 160  * @param object
 161  * The object to retain.
 162  *
 163  * @result
 164  * The retained object.
 165  */
 166     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0)
 167 OS_EXPORT
 168 void*
 169 os_retain(void *object);
 170 #if OS_OBJECT_USE_OBJC
 171 #undef os_retain
 172 #define os_retain(object) [object retain]
 173 #endif
 174
 175 /*!
 176  * @function os_release
 177  *
 178  * @abstract
 179  * Decrement the reference count of a os_object.
 180  *
 181  * @discussion
 182  * On a platform with the modern Objective-C runtime this is exactly equivalent
 183  * to sending the object the -[release] message.
 184  *
 185  * @param object
 186  * The object to release.
 187  */
 188 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0)
 189 OS_EXPORT
 190 void
 191 os_release(void *object);
 192 #if OS_OBJECT_USE_OBJC
 193 #undef os_release
 194 #define os_release(object) [object release]
 195 #endif
 196
 197 #define fastpath(x) ((typeof(x))__builtin_expect((long)(x), ~0l))
 198 #define slowpath(x) ((typeof(x))__builtin_expect((long)(x), 0l))
 199
 200 __END_DECLS
 201
 202 #endif