[apple/xnu.git] / libkern / os / object.h

/*
 * Copyright (c) 2011-2014 Apple Inc. All rights reserved.
 *
 * @APPLE_APACHE_LICENSE_HEADER_START@
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * @APPLE_APACHE_LICENSE_HEADER_END@
 */

#ifndef __OS_OBJECT__
#define __OS_OBJECT__

#ifdef __APPLE__
#include <Availability.h>
#endif
#include <os/base.h>

/*!
 * @header
 *
 * @preprocinfo
 * By default, libSystem objects such as GCD and XPC objects are declared as
 * Objective-C types when building with an Objective-C compiler. This allows
 * them to participate in ARC, in RR management by the Blocks runtime and in
 * leaks checking by the static analyzer, and enables them to be added to Cocoa
 * collections.
 *
 * NOTE: this requires explicit cancellation of dispatch sources and xpc
 *       connections whose handler blocks capture the source/connection object,
 *       resp. ensuring that such captures do not form retain cycles (e.g. by
 *       declaring the source as __weak).
 *
 * To opt-out of this default behavior, add -DOS_OBJECT_USE_OBJC=0 to your
 * compiler flags.
 *
 * This mode requires a platform with the modern Objective-C runtime, the
 * Objective-C GC compiler option to be disabled, and at least a Mac OS X 10.8
 * or iOS 6.0 deployment target.
 */

#ifndef OS_OBJECT_HAVE_OBJC_SUPPORT
#if defined(__OBJC__) && defined(__OBJC2__) && !defined(__OBJC_GC__) && ( \
		__MAC_OS_X_VERSION_MIN_REQUIRED >= __MAC_10_8 || \
		__IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_6_0)
#define OS_OBJECT_HAVE_OBJC_SUPPORT 1
#else
#define OS_OBJECT_HAVE_OBJC_SUPPORT 0
#endif
#endif

#if OS_OBJECT_HAVE_OBJC_SUPPORT
#ifndef OS_OBJECT_USE_OBJC
#define OS_OBJECT_USE_OBJC 1
#endif
#elif defined(OS_OBJECT_USE_OBJC) && OS_OBJECT_USE_OBJC
/* Unsupported platform for OS_OBJECT_USE_OBJC=1 */
#undef OS_OBJECT_USE_OBJC
#define OS_OBJECT_USE_OBJC 0
#else
#define OS_OBJECT_USE_OBJC 0
#endif

#if OS_OBJECT_USE_OBJC
#import <objc/NSObject.h>
#if defined(__has_attribute)
#if __has_attribute(objc_independent_class)
#define OS_OBJC_INDEPENDENT_CLASS __attribute__((objc_independent_class))
#endif
#endif // __has_attribute(objc_independent_class)
#ifndef OS_OBJC_INDEPENDENT_CLASS
#define OS_OBJC_INDEPENDENT_CLASS
#endif
#define OS_OBJECT_CLASS(name) OS_##name
#define OS_OBJECT_DECL_IMPL(name, ...) \
		@protocol OS_OBJECT_CLASS(name) __VA_ARGS__ \
		@end \
		typedef NSObject<OS_OBJECT_CLASS(name)> \
				* OS_OBJC_INDEPENDENT_CLASS name##_t
#define OS_OBJECT_DECL(name, ...) \
		OS_OBJECT_DECL_IMPL(name, <NSObject>)
#define OS_OBJECT_DECL_SUBCLASS(name, super) \
		OS_OBJECT_DECL_IMPL(name, <OS_OBJECT_CLASS(super)>)
#if defined(__has_attribute)
#if __has_attribute(ns_returns_retained)
#define OS_OBJECT_RETURNS_RETAINED __attribute__((__ns_returns_retained__))
#else
#define OS_OBJECT_RETURNS_RETAINED
#endif
#if __has_attribute(ns_consumed)
#define OS_OBJECT_CONSUMED __attribute__((__ns_consumed__))
#else
#define OS_OBJECT_CONSUMED
#endif
#else
#define OS_OBJECT_RETURNS_RETAINED
#define OS_OBJECT_CONSUMED
#endif
#if defined(__has_feature)
#if __has_feature(objc_arc)
#define OS_OBJECT_BRIDGE __bridge
#define OS_WARN_RESULT_NEEDS_RELEASE
#else
#define OS_OBJECT_BRIDGE
#define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
#endif
#else
#define OS_OBJECT_BRIDGE
#define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
#endif
#ifndef OS_OBJECT_USE_OBJC_RETAIN_RELEASE
#if defined(__clang_analyzer__)
#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
#elif defined(__has_feature)
#if __has_feature(objc_arc)
#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 1
#else
#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
#endif
#else
#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
#endif
#endif
#else
/*! @parseOnly */
#define OS_OBJECT_RETURNS_RETAINED
/*! @parseOnly */
#define OS_OBJECT_CONSUMED
/*! @parseOnly */
#define OS_OBJECT_BRIDGE
/*! @parseOnly */
#define OS_WARN_RESULT_NEEDS_RELEASE OS_WARN_RESULT
#define OS_OBJECT_USE_OBJC_RETAIN_RELEASE 0
#endif

#define OS_OBJECT_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object))

__BEGIN_DECLS

/*!
 * @function os_retain
 *
 * @abstract
 * Increment the reference count of an os_object.
 *
 * @discussion
 * On a platform with the modern Objective-C runtime this is exactly equivalent
 * to sending the object the -[retain] message.
 *
 * @param object
 * The object to retain.
 *
 * @result
 * The retained object.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_12,__IPHONE_10_0)
OS_EXPORT
void*
os_retain(void *object);
#if OS_OBJECT_USE_OBJC
#undef os_retain
#define os_retain(object) [object retain]
#endif

/*!
 * @function os_release
 *
 * @abstract
 * Decrement the reference count of a os_object.
 *
 * @discussion
 * On a platform with the modern Objective-C runtime this is exactly equivalent
 * to sending the object the -[release] message.
 *
 * @param object
 * The object to release.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_12,__IPHONE_10_0)
OS_EXPORT
void
os_release(void *object);
#if OS_OBJECT_USE_OBJC
#undef os_release
#define os_release(object) [object release]
#endif

#define fastpath(x) ((typeof(x))__builtin_expect((long)(x), ~0l))
#define slowpath(x) ((typeof(x))__builtin_expect((long)(x), 0l))

__END_DECLS

#endif
Commit	Line	Data
39037602 A	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