/* * Copyright (c) 2008-2010 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 __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); /*! * @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); /*! * @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