[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_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.
 *
 * @param object
 * The object to introspect.
 *
 * @param message
 * The message to log above and beyond the introspection.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
__attribute__((__format__(printf,2,3)))
void
dispatch_debug(dispatch_object_t object, const char *message, ...);

__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_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;
	84	struct dispatch_source_attr_s *_dsa;
	85	struct dispatch_semaphore_s *_dsema;
	86	struct dispatch_data_s *_ddata;
	87	struct dispatch_io_s *_dchannel;
	88	struct dispatch_operation_s *_doperation;
	89	struct dispatch_disk_s *_ddisk;
	90	} dispatch_object_t __attribute__((__transparent_union__));
	91	/! @parseOnly /
	92	#define DISPATCH_DECL(name) typedef struct name##_s *name##_t
93	/! @parseOnly /
94	#define DISPATCH_GLOBAL_OBJECT(t, x) (&(x))
95	/! @parseOnly /
96	#define DISPATCH_RETURNS_RETAINED
97	#endif
98
0ab74447 A	99	__BEGIN_DECLS
	100
	101	/*!
	102	* @function dispatch_debug
	103	*
	104	* @abstract
	105	* Programmatically log debug information about a dispatch object.
	106	*
e85f4437 A	107	* @discussion
	108	* Programmatically log debug information about a dispatch object. By default,
	109	* the log output is sent to syslog at notice level. In the debug version of
	110	* the library, the log output is sent to a file in /var/tmp.
	111	* The log output destination can be configured via the LIBDISPATCH_LOG
	112	* environment variable, valid values are: YES, NO, syslog, stderr, file.
	113	*
0ab74447 A	114	* @param object
	115	* The object to introspect.
	116	*
	117	* @param message
	118	* The message to log above and beyond the introspection.
	119	*/
e85f4437 A	120	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
	121	DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
	122	__attribute__((__format__(printf,2,3)))
0ab74447 A	123	void
	124	dispatch_debug(dispatch_object_t object, const char *message, ...);
	125
e85f4437 A	126	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
	127	DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
	128	__attribute__((__format__(printf,2,0)))
0ab74447 A	129	void
	130	dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
	131
	132	/*!
	133	* @function dispatch_retain
	134	*
	135	* @abstract
	136	* Increment the reference count of a dispatch object.
	137	*
	138	* @discussion
	139	* Calls to dispatch_retain() must be balanced with calls to
	140	* dispatch_release().
	141	*
	142	* @param object
	143	* The object to retain.
	144	* The result of passing NULL in this parameter is undefined.
	145	*/
e85f4437 A	146	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	147	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	148	void
0ab74447 A	149	dispatch_retain(dispatch_object_t object);
c093abd6 A	150	#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
	151	#undef dispatch_retain
	152	#define dispatch_retain(object) ({ dispatch_object_t _o = (object); \
	153	_dispatch_object_validate(_o); (void)[_o retain]; })
	154	#endif
0ab74447 A	155
	156	/*!
	157	* @function dispatch_release
	158	*
	159	* @abstract
	160	* Decrement the reference count of a dispatch object.
	161	*
	162	* @discussion
	163	* A dispatch object is asynchronously deallocated once all references are
	164	* released (i.e. the reference count becomes zero). The system does not
	165	* guarantee that a given client is the last or only reference to a given
	166	* object.
	167	*
	168	* @param object
	169	* The object to release.
	170	* The result of passing NULL in this parameter is undefined.
	171	*/
e85f4437 A	172	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	173	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	174	void
0ab74447 A	175	dispatch_release(dispatch_object_t object);
c093abd6 A	176	#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
	177	#undef dispatch_release
	178	#define dispatch_release(object) ({ dispatch_object_t _o = (object); \
	179	_dispatch_object_validate(_o); [_o release]; })
	180	#endif
0ab74447 A	181
	182	/*!
	183	* @function dispatch_get_context
	184	*
	185	* @abstract
	186	* Returns the application defined context of the object.
	187	*
	188	* @param object
	189	* The result of passing NULL in this parameter is undefined.
	190	*
	191	* @result
	192	* The context of the object; may be NULL.
	193	*/
e85f4437 A	194	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
	195	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
	196	DISPATCH_NOTHROW
0ab74447 A	197	void *
	198	dispatch_get_context(dispatch_object_t object);
	199
	200	/*!
	201	* @function dispatch_set_context
	202	*
	203	* @abstract
	204	* Associates an application defined context with the object.
	205	*
	206	* @param object
	207	* The result of passing NULL in this parameter is undefined.
	208	*
	209	* @param context
	210	* The new client defined context for the object. This may be NULL.
	211	*
	212	*/
e85f4437 A	213	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	214	DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
0ab74447 A	215	void
	216	dispatch_set_context(dispatch_object_t object, void *context);
	217
	218	/*!
	219	* @function dispatch_set_finalizer_f
	220	*
	221	* @abstract
	222	* Set the finalizer function for a dispatch object.
	223	*
	224	* @param
	225	* The dispatch object to modify.
	226	* The result of passing NULL in this parameter is undefined.
	227	*
	228	* @param
	229	* The finalizer function pointer.
	230	*
	231	* @discussion
	232	* A dispatch object's finalizer will be invoked on the object's target queue
	233	* after all references to the object have been released. This finalizer may be
	234	* used by the application to release any resources associated with the object,
	235	* such as freeing the object's context.
	236	* The context parameter passed to the finalizer function is the current
	237	* context of the dispatch object at the time the finalizer call is made.
	238	*/
e85f4437 A	239	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	240	DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
0ab74447 A	241	void
	242	dispatch_set_finalizer_f(dispatch_object_t object,
	243	dispatch_function_t finalizer);
	244
	245	/*!
	246	* @function dispatch_suspend
	247	*
	248	* @abstract
	249	* Suspends the invocation of blocks on a dispatch object.
	250	*
	251	* @discussion
	252	* A suspended object will not invoke any blocks associated with it. The
	253	* suspension of an object will occur after any running block associated with
	254	* the object completes.
	255	*
	256	* Calls to dispatch_suspend() must be balanced with calls
	257	* to dispatch_resume().
	258	*
e85f4437	259	* @param object
0ab74447 A	260	* The object to be suspended.
	261	* The result of passing NULL in this parameter is undefined.
	262	*/
e85f4437 A	263	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	264	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	265	void
	266	dispatch_suspend(dispatch_object_t object);
	267
	268	/*!
	269	* @function dispatch_resume
	270	*
	271	* @abstract
	272	* Resumes the invocation of blocks on a dispatch object.
	273	*
e85f4437	274	* @param object
0ab74447 A	275	* The object to be resumed.
	276	* The result of passing NULL in this parameter is undefined.
	277	*/
e85f4437 A	278	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	279	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	280	void
	281	dispatch_resume(dispatch_object_t object);
	282
	283	__END_DECLS
	284
	285	#endif