dispatch/object.h

   1 /*
   2  * Copyright (c) 2008-2012 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 /*!
  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
  99 __BEGIN_DECLS
 100
 101 /*!
 102  * @function dispatch_debug
 103  *
 104  * @abstract
 105  * Programmatically log debug information about a dispatch object.
 106  *
 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  *
 114  * @param object
 115  * The object to introspect.
 116  *
 117  * @param message
 118  * The message to log above and beyond the introspection.
 119  */
 120 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 121 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
 122 __attribute__((__format__(printf,2,3)))
 123 void
 124 dispatch_debug(dispatch_object_t object, const char *message, ...);
 125
 126 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 127 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
 128 __attribute__((__format__(printf,2,0)))
 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  */
 146 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 147 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 148 void
 149 dispatch_retain(dispatch_object_t object);
 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
 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  */
 172 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 173 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 174 void
 175 dispatch_release(dispatch_object_t object);
 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
 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  */
 194 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 195 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
 196 DISPATCH_NOTHROW
 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  */
 213 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 214 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 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  */
 239 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 240 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 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  *
 259  * @param object
 260  * The object to be suspended.
 261  * The result of passing NULL in this parameter is undefined.
 262  */
 263 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 264 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 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  *
 274  * @param object
 275  * The object to be resumed.
 276  * The result of passing NULL in this parameter is undefined.
 277  */
 278 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 279 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 280 void
 281 dispatch_resume(dispatch_object_t object);
 282
 283 __END_DECLS
 284
 285 #endif