src/object.h

   1 /*
   2  * Copyright (c) 2008-2009 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  * @param object
  38  * The object to introspect.
  39  *
  40  * @param message
  41  * The message to log above and beyond the introspection.
  42  */
  43 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
  44 DISPATCH_NONNULL2 DISPATCH_NOTHROW __attribute__((__format__(printf,2,3)))
  45 void
  46 dispatch_debug(dispatch_object_t object, const char *message, ...);
  47
  48 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
  49 DISPATCH_NONNULL2 DISPATCH_NOTHROW __attribute__((__format__(printf,2,0)))
  50 void
  51 dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
  52
  53 /*!
  54  * @function dispatch_retain
  55  *
  56  * @abstract
  57  * Increment the reference count of a dispatch object.
  58  *
  59  * @discussion
  60  * Calls to dispatch_retain() must be balanced with calls to
  61  * dispatch_release().
  62  *
  63  * @param object
  64  * The object to retain.
  65  * The result of passing NULL in this parameter is undefined.
  66  */
  67 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
  68 DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  69 void
  70 dispatch_retain(dispatch_object_t object);
  71
  72 /*!
  73  * @function dispatch_release
  74  *
  75  * @abstract
  76  * Decrement the reference count of a dispatch object.
  77  *
  78  * @discussion
  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
  82  * object.
  83  *
  84  * @param object
  85  * The object to release.
  86  * The result of passing NULL in this parameter is undefined.
  87  */
  88 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
  89 DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  90 void
  91 dispatch_release(dispatch_object_t object);
  92
  93 /*!
  94  * @function dispatch_get_context
  95  *
  96  * @abstract
  97  * Returns the application defined context of the object.
  98  *
  99  * @param object
 100  * The result of passing NULL in this parameter is undefined.
 101  *
 102  * @result
 103  * The context of the object; may be NULL.
 104  */
 105 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 106 DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 107 void *
 108 dispatch_get_context(dispatch_object_t object);
 109
 110 /*!
 111  * @function dispatch_set_context
 112  *
 113  * @abstract
 114  * Associates an application defined context with the object.
 115  *
 116  * @param object
 117  * The result of passing NULL in this parameter is undefined.
 118  *
 119  * @param context
 120  * The new client defined context for the object. This may be NULL.
 121  *
 122  */
 123 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 124 DISPATCH_NOTHROW //DISPATCH_NONNULL1
 125 void
 126 dispatch_set_context(dispatch_object_t object, void *context);
 127
 128 /*!
 129  * @function dispatch_set_finalizer_f
 130  *
 131  * @abstract
 132  * Set the finalizer function for a dispatch object.
 133  *
 134  * @param
 135  * The dispatch object to modify.
 136  * The result of passing NULL in this parameter is undefined.
 137  *
 138  * @param
 139  * The finalizer function pointer.
 140  *
 141  * @discussion
 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.
 148  */
 149 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 150 DISPATCH_NOTHROW //DISPATCH_NONNULL1
 151 void
 152 dispatch_set_finalizer_f(dispatch_object_t object,
 153         dispatch_function_t finalizer);
 154
 155 /*!
 156  * @function dispatch_suspend
 157  *
 158  * @abstract
 159  * Suspends the invocation of blocks on a dispatch object.
 160  *
 161  * @discussion
 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.
 165  *
 166  * Calls to dispatch_suspend() must be balanced with calls
 167  * to dispatch_resume().
 168  *
 169  * @param       object
 170  * The object to be suspended.
 171  * The result of passing NULL in this parameter is undefined.
 172  */
 173 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 174 DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 175 void
 176 dispatch_suspend(dispatch_object_t object);
 177
 178 /*!
 179  * @function dispatch_resume
 180  *
 181  * @abstract
 182  * Resumes the invocation of blocks on a dispatch object.
 183  *
 184  * @param       object
 185  * The object to be resumed.
 186  * The result of passing NULL in this parameter is undefined.
 187  */
 188 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 189 DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 190 void
 191 dispatch_resume(dispatch_object_t object);
 192
 193 __END_DECLS
 194
 195 #endif