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 #if KERNEL
  22
  23 #ifndef __OS_OBJECT__
  24 #define __OS_OBJECT__
  25
  26 #ifdef __APPLE__
  27 #include <Availability.h>
  28 #endif
  29 #include <os/base.h>
  30
  31 /*!
  32  * @header
  33  *
  34  * @preprocinfo
  35  * By default, libSystem objects such as GCD and XPC objects are declared as
  36  * Objective-C types when building with an Objective-C compiler. This allows
  37  * them to participate in ARC, in RR management by the Blocks runtime and in
  38  * leaks checking by the static analyzer, and enables them to be added to Cocoa
  39  * collections.
  40  *
  41  * NOTE: this requires explicit cancellation of dispatch sources and xpc
  42  *       connections whose handler blocks capture the source/connection object,
  43  *       resp. ensuring that such captures do not form retain cycles (e.g. by
  44  *       declaring the source as __weak).
  45  *
  46  * To opt-out of this default behavior, add -DOS_OBJECT_USE_OBJC=0 to your
  47  * compiler flags.
  48  *
  49  * This mode requires a platform with the modern Objective-C runtime, the
  50  * Objective-C GC compiler option to be disabled, and at least a Mac OS X 10.8
  51  * or iOS 6.0 deployment target.
  52  */
  53
  54 #ifndef OS_OBJECT_HAVE_OBJC_SUPPORT
  55 #if defined(__OBJC__) && defined(__OBJC2__) && !defined(__OBJC_GC__) && ( \
  56         __MAC_OS_X_VERSION_MIN_REQUIRED >= __MAC_10_8 || \
  57         __IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_6_0)
  58 #define OS_OBJECT_HAVE_OBJC_SUPPORT 1
  59 #else
  60 #define OS_OBJECT_HAVE_OBJC_SUPPORT 0
  61 #endif
  62 #endif
  63
  64 #if OS_OBJECT_HAVE_OBJC_SUPPORT
  65 #ifndef OS_OBJECT_USE_OBJC
  66 #define OS_OBJECT_USE_OBJC 1
  67 #endif
  68 #elif defined(OS_OBJECT_USE_OBJC) && OS_OBJECT_USE_OBJC
  69 /* Unsupported platform for OS_OBJECT_USE_OBJC=1 */
  70 #undef OS_OBJECT_USE_OBJC
  71 #define OS_OBJECT_USE_OBJC 0
  72 #else
  73 #define OS_OBJECT_USE_OBJC 0
  74 #endif
  75
  76 #if OS_OBJECT_USE_OBJC
  77 #import <objc/NSObject.h>
  78 #if defined(__has_attribute)
  79 #if __has_attribute(objc_independent_class)
  80 #define OS_OBJC_INDEPENDENT_CLASS __attribute__((objc_independent_class))
  81 #endif
  82 #endif // __has_attribute(objc_independent_class)
  83 #ifndef OS_OBJC_INDEPENDENT_CLASS
  84 #define OS_OBJC_INDEPENDENT_CLASS
  85 #endif
  86 #define OS_OBJECT_CLASS(name) OS_##name
  87 #define OS_OBJECT_DECL_IMPL(name, ...) \
  88                 @protocol OS_OBJECT_CLASS(name) __VA_ARGS__ \
  89                 @end \
  90                 typedef NSObject<OS_OBJECT_CLASS(name)> \
  91                                 * OS_OBJC_INDEPENDENT_CLASS name##_t
  92 #define OS_OBJECT_DECL(name, ...) \
  93                 OS_OBJECT_DECL_IMPL(name, <NSObject>)
  94 #define OS_OBJECT_DECL_SUBCLASS(name, super) \
  95                 OS_OBJECT_DECL_IMPL(name, <OS_OBJECT_CLASS(super)>)
  96 #if defined(__has_attribute)
  97 #if __has_attribute(ns_returns_retained)
  98 #define OS_OBJECT_RETURNS_RETAINED __attribute__((__ns_returns_retained__))
  99 #else
 100 #define OS_OBJECT_RETURNS_RETAINED
 101 #endif
 102 #if __has_attribute(ns_consumed)
 103 #define OS_OBJECT_CONSUMED __attribute__((__ns_consumed__))
 104 #else
 105 #define OS_OBJECT_CONSUMED
 106 #endif
 107 #else
 108 #define OS_OBJECT_RETURNS_RETAINED
 109 #define OS_OBJECT_CONSUMED
 110 #endif
 111 #if defined(__has_feature)
 112 #if __has_feature(objc_arc)
 113 #define OS_OBJECT_BRIDGE __bridge
 114 #define OS_WARN_RESULT_NEEDS_RELEASE
 115 #else
 116 #define OS_OBJECT_BRIDGE
 117 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
 118 #endif
 119 #else
 120 #define OS_OBJECT_BRIDGE
 121 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
 122 #endif
 123 #ifndef OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 124 #if defined(__clang_analyzer__)
 125 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
 126 #elif defined(__has_feature)
 127 #if __has_feature(objc_arc)
 128 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
 129 #else
 130 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
 131 #endif
 132 #else
 133 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
 134 #endif
 135 #endif
 136 #else
 137 /*! @parseOnly */
 138 #define OS_OBJECT_RETURNS_RETAINED
 139 /*! @parseOnly */
 140 #define OS_OBJECT_CONSUMED
 141 /*! @parseOnly */
 142 #define OS_OBJECT_BRIDGE
 143 /*! @parseOnly */
 144 #define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
 145 #define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
 146 #endif
 147
 148 #define OS_OBJECT_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object))
 149
 150 __BEGIN_DECLS
 151
 152 /*!
 153  * @function os_retain
 154  *
 155  * @abstract
 156  * Increment the reference count of an os_object.
 157  *
 158  * @discussion
 159  * On a platform with the modern Objective-C runtime this is exactly equivalent
 160  * to sending the object the -[retain] message.
 161  *
 162  * @param object
 163  * The object to retain.
 164  *
 165  * @result
 166  * The retained object.
 167  */
 168     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0)
 169 OS_EXPORT
 170 void*
 171 os_retain(void *object);
 172 #if OS_OBJECT_USE_OBJC
 173 #undef os_retain
 174 #define os_retain(object) [object retain]
 175 #endif
 176
 177 /*!
 178  * @function os_release
 179  *
 180  * @abstract
 181  * Decrement the reference count of a os_object.
 182  *
 183  * @discussion
 184  * On a platform with the modern Objective-C runtime this is exactly equivalent
 185  * to sending the object the -[release] message.
 186  *
 187  * @param object
 188  * The object to release.
 189  */
 190 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0)
 191 OS_EXPORT
 192 void
 193 os_release(void *object);
 194 #if OS_OBJECT_USE_OBJC
 195 #undef os_release
 196 #define os_release(object) [object release]
 197 #endif
 198
 199 #define fastpath(x) ((typeof(x))__builtin_expect((long)(x), ~0l))
 200 #define slowpath(x) ((typeof(x))__builtin_expect((long)(x), 0l))
 201
 202 __END_DECLS
 203
 204 #endif /* OS_OBJECT file guard */
 205
 206 #else /* KERNEL */
 207
 208 /* This should use the libdispatch header */
 209 #include_next <os/object.h>
 210
 211 #endif /* KERNEL */