2 * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
4 * @APPLE_APACHE_LICENSE_HEADER_START@
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
10 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @APPLE_APACHE_LICENSE_HEADER_END@
21 #ifndef __DISPATCH_OBJECT__
22 #define __DISPATCH_OBJECT__
24 #ifndef __DISPATCH_INDIRECT__
25 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
26 #include <dispatch/base.h> // for HeaderDoc
29 __DISPATCH_BEGIN_DECLS
32 * @function dispatch_debug
35 * Programmatically log debug information about a dispatch object.
38 * The object to introspect.
41 * The message to log above and beyond the introspection.
43 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
44 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW DISPATCH_FORMAT(printf,2,3)
46 dispatch_debug(dispatch_object_t object, const char *message, ...);
48 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
49 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW DISPATCH_FORMAT(printf,2,0)
51 dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
54 * @function dispatch_retain
57 * Increment the reference count of a dispatch object.
60 * Calls to dispatch_retain() must be balanced with calls to
64 * The object to retain.
65 * The result of passing NULL in this parameter is undefined.
67 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
68 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
70 dispatch_retain(dispatch_object_t object);
73 * @function dispatch_release
76 * Decrement the reference count of a dispatch object.
79 * A dispatch object is asynchronously deallocated once all references are
80 * released (i.e. the reference count becomes zero). The system does not
81 * guarantee that a given client is the last or only reference to a given
85 * The object to release.
86 * The result of passing NULL in this parameter is undefined.
88 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
89 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
91 dispatch_release(dispatch_object_t object);
94 * @function dispatch_get_context
97 * Returns the application defined context of the object.
100 * The result of passing NULL in this parameter is undefined.
103 * The context of the object; may be NULL.
105 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
106 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
108 dispatch_get_context(dispatch_object_t object);
111 * @function dispatch_set_context
114 * Associates an application defined context with the object.
117 * The result of passing NULL in this parameter is undefined.
120 * The new client defined context for the object. This may be NULL.
123 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
124 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
126 dispatch_set_context(dispatch_object_t object, void *context);
129 * @function dispatch_set_finalizer_f
132 * Set the finalizer function for a dispatch object.
135 * The dispatch object to modify.
136 * The result of passing NULL in this parameter is undefined.
139 * The finalizer function pointer.
142 * A dispatch object's finalizer will be invoked on the object's target queue
143 * after all references to the object have been released. This finalizer may be
144 * used by the application to release any resources associated with the object,
145 * such as freeing the object's context.
146 * The context parameter passed to the finalizer function is the current
147 * context of the dispatch object at the time the finalizer call is made.
149 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
150 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
152 dispatch_set_finalizer_f(dispatch_object_t object,
153 dispatch_function_t finalizer);
156 * @function dispatch_suspend
159 * Suspends the invocation of blocks on a dispatch object.
162 * A suspended object will not invoke any blocks associated with it. The
163 * suspension of an object will occur after any running block associated with
164 * the object completes.
166 * Calls to dispatch_suspend() must be balanced with calls
167 * to dispatch_resume().
170 * The object to be suspended.
171 * The result of passing NULL in this parameter is undefined.
173 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
174 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
176 dispatch_suspend(dispatch_object_t object);
179 * @function dispatch_resume
182 * Resumes the invocation of blocks on a dispatch object.
185 * The object to be resumed.
186 * The result of passing NULL in this parameter is undefined.
188 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
189 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
191 dispatch_resume(dispatch_object_t object);