dispatch/object.h

   1 /*
   2  * Copyright (c) 2008-2010 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 __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
  29 __BEGIN_DECLS
  30
  31 /*!
  32  * @function dispatch_debug
  33  *
  34  * @abstract
  35  * Programmatically log debug information about a dispatch object.
  36  *
  37  * @discussion
  38  * Programmatically log debug information about a dispatch object. By default,
  39  * the log output is sent to syslog at notice level. In the debug version of
  40  * the library, the log output is sent to a file in /var/tmp.
  41  * The log output destination can be configured via the LIBDISPATCH_LOG
  42  * environment variable, valid values are: YES, NO, syslog, stderr, file.
  43  *
  44  * @param object
  45  * The object to introspect.
  46  *
  47  * @param message
  48  * The message to log above and beyond the introspection.
  49  */
  50 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  51 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
  52 __attribute__((__format__(printf,2,3)))
  53 void
  54 dispatch_debug(dispatch_object_t object, const char *message, ...);
  55
  56 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  57 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
  58 __attribute__((__format__(printf,2,0)))
  59 void
  60 dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
  61
  62 /*!
  63  * @function dispatch_retain
  64  *
  65  * @abstract
  66  * Increment the reference count of a dispatch object.
  67  *
  68  * @discussion
  69  * Calls to dispatch_retain() must be balanced with calls to
  70  * dispatch_release().
  71  *
  72  * @param object
  73  * The object to retain.
  74  * The result of passing NULL in this parameter is undefined.
  75  */
  76 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  77 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  78 void
  79 dispatch_retain(dispatch_object_t object);
  80
  81 /*!
  82  * @function dispatch_release
  83  *
  84  * @abstract
  85  * Decrement the reference count of a dispatch object.
  86  *
  87  * @discussion
  88  * A dispatch object is asynchronously deallocated once all references are
  89  * released (i.e. the reference count becomes zero). The system does not
  90  * guarantee that a given client is the last or only reference to a given
  91  * object.
  92  *
  93  * @param object
  94  * The object to release.
  95  * The result of passing NULL in this parameter is undefined.
  96  */
  97 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  98 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  99 void
 100 dispatch_release(dispatch_object_t object);
 101
 102 /*!
 103  * @function dispatch_get_context
 104  *
 105  * @abstract
 106  * Returns the application defined context of the object.
 107  *
 108  * @param object
 109  * The result of passing NULL in this parameter is undefined.
 110  *
 111  * @result
 112  * The context of the object; may be NULL.
 113  */
 114 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 115 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
 116 DISPATCH_NOTHROW
 117 void *
 118 dispatch_get_context(dispatch_object_t object);
 119
 120 /*!
 121  * @function dispatch_set_context
 122  *
 123  * @abstract
 124  * Associates an application defined context with the object.
 125  *
 126  * @param object
 127  * The result of passing NULL in this parameter is undefined.
 128  *
 129  * @param context
 130  * The new client defined context for the object. This may be NULL.
 131  *
 132  */
 133 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 134 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 135 void
 136 dispatch_set_context(dispatch_object_t object, void *context);
 137
 138 /*!
 139  * @function dispatch_set_finalizer_f
 140  *
 141  * @abstract
 142  * Set the finalizer function for a dispatch object.
 143  *
 144  * @param
 145  * The dispatch object to modify.
 146  * The result of passing NULL in this parameter is undefined.
 147  *
 148  * @param
 149  * The finalizer function pointer.
 150  *
 151  * @discussion
 152  * A dispatch object's finalizer will be invoked on the object's target queue
 153  * after all references to the object have been released. This finalizer may be
 154  * used by the application to release any resources associated with the object,
 155  * such as freeing the object's context.
 156  * The context parameter passed to the finalizer function is the current
 157  * context of the dispatch object at the time the finalizer call is made.
 158  */
 159 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 160 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 161 void
 162 dispatch_set_finalizer_f(dispatch_object_t object,
 163         dispatch_function_t finalizer);
 164
 165 /*!
 166  * @function dispatch_suspend
 167  *
 168  * @abstract
 169  * Suspends the invocation of blocks on a dispatch object.
 170  *
 171  * @discussion
 172  * A suspended object will not invoke any blocks associated with it. The
 173  * suspension of an object will occur after any running block associated with
 174  * the object completes.
 175  *
 176  * Calls to dispatch_suspend() must be balanced with calls
 177  * to dispatch_resume().
 178  *
 179  * @param object
 180  * The object to be suspended.
 181  * The result of passing NULL in this parameter is undefined.
 182  */
 183 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 184 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 185 void
 186 dispatch_suspend(dispatch_object_t object);
 187
 188 /*!
 189  * @function dispatch_resume
 190  *
 191  * @abstract
 192  * Resumes the invocation of blocks on a dispatch object.
 193  *
 194  * @param object
 195  * The object to be resumed.
 196  * The result of passing NULL in this parameter is undefined.
 197  */
 198 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 199 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 200 void
 201 dispatch_resume(dispatch_object_t object);
 202
 203 __END_DECLS
 204
 205 #endif