[apple/libdispatch.git] / dispatch / object.h

/*
 * Copyright (c) 2008-2012 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 __DISPATCH_OBJECT__
#define __DISPATCH_OBJECT__

#ifndef __DISPATCH_INDIRECT__
#error "Please #include <dispatch/dispatch.h> instead of this file directly."
#include <dispatch/base.h> // for HeaderDoc
#endif

/*!
 * @typedef dispatch_object_t
 *
 * @abstract
 * Abstract base type for all dispatch objects.
 * The details of the type definition are language-specific.
 *
 * @discussion
 * Dispatch objects are reference counted via calls to dispatch_retain() and
 * dispatch_release().
 */

#if OS_OBJECT_USE_OBJC
/*
 * By default, dispatch 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.
 * See <os/object.h> for details.
 */
OS_OBJECT_DECL(dispatch_object);
#define DISPATCH_DECL(name) OS_OBJECT_DECL_SUBCLASS(name, dispatch_object)
#define DISPATCH_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object))
#define DISPATCH_RETURNS_RETAINED OS_OBJECT_RETURNS_RETAINED
DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
_dispatch_object_validate(dispatch_object_t object) {
	void *isa = *(void* volatile*)(OS_OBJECT_BRIDGE void*)object;
	(void)isa;
}
#elif defined(__cplusplus)
/*
 * Dispatch objects are NOT C++ objects. Nevertheless, we can at least keep C++
 * aware of type compatibility.
 */
typedef struct dispatch_object_s {
private:
	dispatch_object_s();
	~dispatch_object_s();
	dispatch_object_s(const dispatch_object_s &);
	void operator=(const dispatch_object_s &);
} *dispatch_object_t;
#define DISPATCH_DECL(name) \
		typedef struct name##_s : public dispatch_object_s {} *name##_t
#define DISPATCH_GLOBAL_OBJECT(type, object) (&(object))
#define DISPATCH_RETURNS_RETAINED
#else /* Plain C */
typedef union {
	struct _os_object_s *_os_obj;
	struct dispatch_object_s *_do;
	struct dispatch_continuation_s *_dc;
	struct dispatch_queue_s *_dq;
	struct dispatch_queue_attr_s *_dqa;
	struct dispatch_group_s *_dg;
	struct dispatch_source_s *_ds;
	struct dispatch_mach_s *_dm;
	struct dispatch_mach_msg_s *_dmsg;
	struct dispatch_timer_aggregate_s *_dta;
	struct dispatch_source_attr_s *_dsa;
	struct dispatch_semaphore_s *_dsema;
	struct dispatch_data_s *_ddata;
	struct dispatch_io_s *_dchannel;
	struct dispatch_operation_s *_doperation;
	struct dispatch_disk_s *_ddisk;
} dispatch_object_t __attribute__((__transparent_union__));
/*! @parseOnly */
#define DISPATCH_DECL(name) typedef struct name##_s *name##_t
/*! @parseOnly */
#define DISPATCH_GLOBAL_OBJECT(t, x) (&(x))
/*! @parseOnly */
#define DISPATCH_RETURNS_RETAINED
#endif

__BEGIN_DECLS

/*!
 * @function dispatch_debug
 *
 * @abstract
 * Programmatically log debug information about a dispatch object.
 *
 * @discussion
 * Programmatically log debug information about a dispatch object. By default,
 * the log output is sent to syslog at notice level. In the debug version of
 * the library, the log output is sent to a file in /var/tmp.
 * The log output destination can be configured via the LIBDISPATCH_LOG
 * environment variable, valid values are: YES, NO, syslog, stderr, file.
 *
 * This function is deprecated and will be removed in a future release.
 * Objective-C callers may use -debugDescription instead.
 *
 * @param object
 * The object to introspect.
 *
 * @param message
 * The message to log above and beyond the introspection.
 */
__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
__attribute__((__format__(printf,2,3)))
void
dispatch_debug(dispatch_object_t object, const char *message, ...);

__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
__attribute__((__format__(printf,2,0)))
void
dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);

/*!
 * @function dispatch_retain
 *
 * @abstract
 * Increment the reference count of a dispatch object.
 *
 * @discussion
 * Calls to dispatch_retain() must be balanced with calls to
 * dispatch_release().
 *
 * @param object
 * The object to retain.
 * The result of passing NULL in this parameter is undefined.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_retain(dispatch_object_t object);
#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
#undef dispatch_retain
#define dispatch_retain(object) ({ dispatch_object_t _o = (object); \
		_dispatch_object_validate(_o); (void)[_o retain]; })
#endif

/*!
 * @function dispatch_release
 *
 * @abstract
 * Decrement the reference count of a dispatch object.
 *
 * @discussion
 * A dispatch object is asynchronously deallocated once all references are
 * released (i.e. the reference count becomes zero). The system does not
 * guarantee that a given client is the last or only reference to a given
 * object.
 *
 * @param object
 * The object to release.
 * The result of passing NULL in this parameter is undefined.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_release(dispatch_object_t object);
#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
#undef dispatch_release
#define dispatch_release(object) ({ dispatch_object_t _o = (object); \
		_dispatch_object_validate(_o); [_o release]; })
#endif

/*!
 * @function dispatch_get_context
 *
 * @abstract
 * Returns the application defined context of the object.
 *
 * @param object
 * The result of passing NULL in this parameter is undefined.
 *
 * @result
 * The context of the object; may be NULL.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
DISPATCH_NOTHROW
void *
dispatch_get_context(dispatch_object_t object);

/*!
 * @function dispatch_set_context
 *
 * @abstract
 * Associates an application defined context with the object.
 *
 * @param object
 * The result of passing NULL in this parameter is undefined.
 *
 * @param context
 * The new client defined context for the object. This may be NULL.
 *
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
void
dispatch_set_context(dispatch_object_t object, void *context);

/*!
 * @function dispatch_set_finalizer_f
 *
 * @abstract
 * Set the finalizer function for a dispatch object.
 *
 * @param
 * The dispatch object to modify.
 * The result of passing NULL in this parameter is undefined.
 *
 * @param
 * The finalizer function pointer.
 *
 * @discussion
 * A dispatch object's finalizer will be invoked on the object's target queue
 * after all references to the object have been released. This finalizer may be
 * used by the application to release any resources associated with the object,
 * such as freeing the object's context.
 * The context parameter passed to the finalizer function is the current
 * context of the dispatch object at the time the finalizer call is made.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
void
dispatch_set_finalizer_f(dispatch_object_t object,
	dispatch_function_t finalizer);

/*!
 * @function dispatch_suspend
 *
 * @abstract
 * Suspends the invocation of blocks on a dispatch object.
 *
 * @discussion
 * A suspended object will not invoke any blocks associated with it. The
 * suspension of an object will occur after any running block associated with
 * the object completes.
 *
 * Calls to dispatch_suspend() must be balanced with calls
 * to dispatch_resume().
 *
 * @param object
 * The object to be suspended.
 * The result of passing NULL in this parameter is undefined.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_suspend(dispatch_object_t object);

/*!
 * @function dispatch_resume
 *
 * @abstract
 * Resumes the invocation of blocks on a dispatch object.
 *
 * @param object
 * The object to be resumed.
 * The result of passing NULL in this parameter is undefined.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_resume(dispatch_object_t object);

__END_DECLS

#endif
Commit	Line	Data
0ab74447	1	/*
c093abd6	2	* Copyright (c) 2008-2012 Apple Inc. All rights reserved.
0ab74447 A	3	*
0ab74447 A	4	* @APPLE_APACHE_LICENSE_HEADER_START@
e85f4437	5	*
0ab74447 A	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
e85f4437	9	*
0ab74447	10	* http://www.apache.org/licenses/LICENSE-2.0
e85f4437	11	*
0ab74447 A	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.
e85f4437	17	*
0ab74447 A	18	* @APPLE_APACHE_LICENSE_HEADER_END@
	19	*/
	20
	21	#ifndef __DISPATCH_OBJECT__
	22	#define __DISPATCH_OBJECT__
	23
	24	#ifndef __DISPATCH_INDIRECT__
	25	#error "Please #include <dispatch/dispatch.h> instead of this file directly."
	26	#include <dispatch/base.h> // for HeaderDoc
	27	#endif
	28
c093abd6 A	29	/*!
	30	* @typedef dispatch_object_t
	31	*
	32	* @abstract
	33	* Abstract base type for all dispatch objects.
	34	* The details of the type definition are language-specific.
	35	*
	36	* @discussion
	37	* Dispatch objects are reference counted via calls to dispatch_retain() and
	38	* dispatch_release().
	39	*/
	40
	41	#if OS_OBJECT_USE_OBJC
	42	/*
	43	* By default, dispatch objects are declared as Objective-C types when building
	44	* with an Objective-C compiler. This allows them to participate in ARC, in RR
	45	* management by the Blocks runtime and in leaks checking by the static
	46	* analyzer, and enables them to be added to Cocoa collections.
	47	* See <os/object.h> for details.
	48	*/
	49	OS_OBJECT_DECL(dispatch_object);
	50	#define DISPATCH_DECL(name) OS_OBJECT_DECL_SUBCLASS(name, dispatch_object)
	51	#define DISPATCH_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object))
	52	#define DISPATCH_RETURNS_RETAINED OS_OBJECT_RETURNS_RETAINED
	53	DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	54	void
	55	_dispatch_object_validate(dispatch_object_t object) {
	56	void isa = (void* volatile)(OS_OBJECT_BRIDGE void)object;
	57	(void)isa;
	58	}
	59	#elif defined(__cplusplus)
	60	/*
	61	* Dispatch objects are NOT C++ objects. Nevertheless, we can at least keep C++
	62	* aware of type compatibility.
	63	*/
	64	typedef struct dispatch_object_s {
	65	private:
	66	dispatch_object_s();
	67	~dispatch_object_s();
	68	dispatch_object_s(const dispatch_object_s &);
	69	void operator=(const dispatch_object_s &);
	70	} *dispatch_object_t;
	71	#define DISPATCH_DECL(name) \
	72	typedef struct name##_s : public dispatch_object_s {} *name##_t
	73	#define DISPATCH_GLOBAL_OBJECT(type, object) (&(object))
	74	#define DISPATCH_RETURNS_RETAINED
	75	#else /* Plain C */
	76	typedef union {
	77	struct _os_object_s *_os_obj;
	78	struct dispatch_object_s *_do;
	79	struct dispatch_continuation_s *_dc;
	80	struct dispatch_queue_s *_dq;
	81	struct dispatch_queue_attr_s *_dqa;
	82	struct dispatch_group_s *_dg;
	83	struct dispatch_source_s *_ds;
517da941 A	84	struct dispatch_mach_s *_dm;
	85	struct dispatch_mach_msg_s *_dmsg;
	86	struct dispatch_timer_aggregate_s *_dta;
c093abd6 A	87	struct dispatch_source_attr_s *_dsa;
	88	struct dispatch_semaphore_s *_dsema;
	89	struct dispatch_data_s *_ddata;
	90	struct dispatch_io_s *_dchannel;
	91	struct dispatch_operation_s *_doperation;
	92	struct dispatch_disk_s *_ddisk;
	93	} dispatch_object_t __attribute__((__transparent_union__));
	94	/! @parseOnly /
	95	#define DISPATCH_DECL(name) typedef struct name##_s *name##_t
	96	/! @parseOnly /
	97	#define DISPATCH_GLOBAL_OBJECT(t, x) (&(x))
	98	/! @parseOnly /
	99	#define DISPATCH_RETURNS_RETAINED
	100	#endif
	101
0ab74447 A	102	__BEGIN_DECLS
	103
	104	/*!
	105	* @function dispatch_debug
	106	*
	107	* @abstract
	108	* Programmatically log debug information about a dispatch object.
	109	*
e85f4437 A	110	* @discussion
	111	* Programmatically log debug information about a dispatch object. By default,
	112	* the log output is sent to syslog at notice level. In the debug version of
	113	* the library, the log output is sent to a file in /var/tmp.
	114	* The log output destination can be configured via the LIBDISPATCH_LOG
	115	* environment variable, valid values are: YES, NO, syslog, stderr, file.
	116	*
517da941 A	117	* This function is deprecated and will be removed in a future release.
	118	* Objective-C callers may use -debugDescription instead.
	119	*
0ab74447 A	120	* @param object
	121	* The object to introspect.
	122	*
	123	* @param message
	124	* The message to log above and beyond the introspection.
	125	*/
517da941	126	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
e85f4437 A	127	DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
e85f4437 A	128	__attribute__((__format__(printf,2,3)))
0ab74447 A	129	void
	130	dispatch_debug(dispatch_object_t object, const char *message, ...);
	131
517da941	132	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
e85f4437 A	133	DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
e85f4437 A	134	__attribute__((__format__(printf,2,0)))
0ab74447 A	135	void
	136	dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
	137
	138	/*!
	139	* @function dispatch_retain
	140	*
	141	* @abstract
	142	* Increment the reference count of a dispatch object.
	143	*
	144	* @discussion
	145	* Calls to dispatch_retain() must be balanced with calls to
	146	* dispatch_release().
	147	*
	148	* @param object
	149	* The object to retain.
	150	* The result of passing NULL in this parameter is undefined.
	151	*/
e85f4437 A	152	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	153	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	154	void
0ab74447 A	155	dispatch_retain(dispatch_object_t object);
c093abd6 A	156	#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
	157	#undef dispatch_retain
	158	#define dispatch_retain(object) ({ dispatch_object_t _o = (object); \
	159	_dispatch_object_validate(_o); (void)[_o retain]; })
	160	#endif
0ab74447 A	161
	162	/*!
	163	* @function dispatch_release
	164	*
	165	* @abstract
	166	* Decrement the reference count of a dispatch object.
	167	*
	168	* @discussion
	169	* A dispatch object is asynchronously deallocated once all references are
	170	* released (i.e. the reference count becomes zero). The system does not
	171	* guarantee that a given client is the last or only reference to a given
	172	* object.
	173	*
	174	* @param object
	175	* The object to release.
	176	* The result of passing NULL in this parameter is undefined.
	177	*/
e85f4437 A	178	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	179	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	180	void
0ab74447 A	181	dispatch_release(dispatch_object_t object);
c093abd6 A	182	#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
	183	#undef dispatch_release
	184	#define dispatch_release(object) ({ dispatch_object_t _o = (object); \
	185	_dispatch_object_validate(_o); [_o release]; })
	186	#endif
0ab74447 A	187
	188	/*!
	189	* @function dispatch_get_context
	190	*
	191	* @abstract
	192	* Returns the application defined context of the object.
	193	*
	194	* @param object
	195	* The result of passing NULL in this parameter is undefined.
	196	*
	197	* @result
	198	* The context of the object; may be NULL.
	199	*/
e85f4437 A	200	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
	201	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
	202	DISPATCH_NOTHROW
0ab74447 A	203	void *
	204	dispatch_get_context(dispatch_object_t object);
	205
	206	/*!
	207	* @function dispatch_set_context
	208	*
	209	* @abstract
	210	* Associates an application defined context with the object.
	211	*
	212	* @param object
	213	* The result of passing NULL in this parameter is undefined.
	214	*
	215	* @param context
	216	* The new client defined context for the object. This may be NULL.
	217	*
	218	*/
e85f4437 A	219	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	220	DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
0ab74447 A	221	void
	222	dispatch_set_context(dispatch_object_t object, void *context);
	223
	224	/*!
	225	* @function dispatch_set_finalizer_f
	226	*
	227	* @abstract
	228	* Set the finalizer function for a dispatch object.
	229	*
	230	* @param
	231	* The dispatch object to modify.
	232	* The result of passing NULL in this parameter is undefined.
	233	*
	234	* @param
	235	* The finalizer function pointer.
	236	*
	237	* @discussion
	238	* A dispatch object's finalizer will be invoked on the object's target queue
	239	* after all references to the object have been released. This finalizer may be
	240	* used by the application to release any resources associated with the object,
	241	* such as freeing the object's context.
	242	* The context parameter passed to the finalizer function is the current
	243	* context of the dispatch object at the time the finalizer call is made.
	244	*/
e85f4437 A	245	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	246	DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
0ab74447 A	247	void
	248	dispatch_set_finalizer_f(dispatch_object_t object,
	249	dispatch_function_t finalizer);
	250
	251	/*!
	252	* @function dispatch_suspend
	253	*
	254	* @abstract
	255	* Suspends the invocation of blocks on a dispatch object.
	256	*
	257	* @discussion
	258	* A suspended object will not invoke any blocks associated with it. The
	259	* suspension of an object will occur after any running block associated with
	260	* the object completes.
	261	*
	262	* Calls to dispatch_suspend() must be balanced with calls
	263	* to dispatch_resume().
	264	*
e85f4437	265	* @param object
0ab74447 A	266	* The object to be suspended.
	267	* The result of passing NULL in this parameter is undefined.
	268	*/
e85f4437 A	269	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	270	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	271	void
	272	dispatch_suspend(dispatch_object_t object);
	273
	274	/*!
	275	* @function dispatch_resume
	276	*
	277	* @abstract
	278	* Resumes the invocation of blocks on a dispatch object.
	279	*
e85f4437	280	* @param object
0ab74447 A	281	* The object to be resumed.
	282	* The result of passing NULL in this parameter is undefined.
	283	*/
e85f4437 A	284	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	285	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	286	void
	287	dispatch_resume(dispatch_object_t object);
	288
	289	__END_DECLS
	290
	291	#endif