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_mach_s *_dm;
  85         struct dispatch_mach_msg_s *_dmsg;
  86         struct dispatch_timer_aggregate_s *_dta;
  87         struct dispatch_source_attr_s *_dsa;
  88         struct dispatch_semaphore_s *_dsema;
  89         struct dispatch_data_s *_ddata;
  90         struct dispatch_io_s *_dchannel;
  91         struct dispatch_operation_s *_doperation;
  92         struct dispatch_disk_s *_ddisk;
  93 } dispatch_object_t __attribute__((__transparent_union__));
  94 /*! @parseOnly */
  95 #define DISPATCH_DECL(name) typedef struct name##_s *name##_t
  96 /*! @parseOnly */
  97 #define DISPATCH_GLOBAL_OBJECT(t, x) (&(x))
  98 /*! @parseOnly */
  99 #define DISPATCH_RETURNS_RETAINED
 100 #endif
 101
 102 __BEGIN_DECLS
 103
 104 /*!
 105  * @function dispatch_debug
 106  *
 107  * @abstract
 108  * Programmatically log debug information about a dispatch object.
 109  *
 110  * @discussion
 111  * Programmatically log debug information about a dispatch object. By default,
 112  * the log output is sent to syslog at notice level. In the debug version of
 113  * the library, the log output is sent to a file in /var/tmp.
 114  * The log output destination can be configured via the LIBDISPATCH_LOG
 115  * environment variable, valid values are: YES, NO, syslog, stderr, file.
 116  *
 117  * This function is deprecated and will be removed in a future release.
 118  * Objective-C callers may use -debugDescription instead.
 119  *
 120  * @param object
 121  * The object to introspect.
 122  *
 123  * @param message
 124  * The message to log above and beyond the introspection.
 125  */
 126 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
 127 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
 128 __attribute__((__format__(printf,2,3)))
 129 void
 130 dispatch_debug(dispatch_object_t object, const char *message, ...);
 131
 132 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
 133 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
 134 __attribute__((__format__(printf,2,0)))
 135 void
 136 dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
 137
 138 /*!
 139  * @function dispatch_retain
 140  *
 141  * @abstract
 142  * Increment the reference count of a dispatch object.
 143  *
 144  * @discussion
 145  * Calls to dispatch_retain() must be balanced with calls to
 146  * dispatch_release().
 147  *
 148  * @param object
 149  * The object to retain.
 150  * The result of passing NULL in this parameter is undefined.
 151  */
 152 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 153 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 154 void
 155 dispatch_retain(dispatch_object_t object);
 156 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 157 #undef dispatch_retain
 158 #define dispatch_retain(object) ({ dispatch_object_t _o = (object); \
 159                 _dispatch_object_validate(_o); (void)[_o retain]; })
 160 #endif
 161
 162 /*!
 163  * @function dispatch_release
 164  *
 165  * @abstract
 166  * Decrement the reference count of a dispatch object.
 167  *
 168  * @discussion
 169  * A dispatch object is asynchronously deallocated once all references are
 170  * released (i.e. the reference count becomes zero). The system does not
 171  * guarantee that a given client is the last or only reference to a given
 172  * object.
 173  *
 174  * @param object
 175  * The object to release.
 176  * The result of passing NULL in this parameter is undefined.
 177  */
 178 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 179 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 180 void
 181 dispatch_release(dispatch_object_t object);
 182 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 183 #undef dispatch_release
 184 #define dispatch_release(object) ({ dispatch_object_t _o = (object); \
 185                 _dispatch_object_validate(_o); [_o release]; })
 186 #endif
 187
 188 /*!
 189  * @function dispatch_get_context
 190  *
 191  * @abstract
 192  * Returns the application defined context of the object.
 193  *
 194  * @param object
 195  * The result of passing NULL in this parameter is undefined.
 196  *
 197  * @result
 198  * The context of the object; may be NULL.
 199  */
 200 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 201 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
 202 DISPATCH_NOTHROW
 203 void *
 204 dispatch_get_context(dispatch_object_t object);
 205
 206 /*!
 207  * @function dispatch_set_context
 208  *
 209  * @abstract
 210  * Associates an application defined context with the object.
 211  *
 212  * @param object
 213  * The result of passing NULL in this parameter is undefined.
 214  *
 215  * @param context
 216  * The new client defined context for the object. This may be NULL.
 217  *
 218  */
 219 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 220 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 221 void
 222 dispatch_set_context(dispatch_object_t object, void *context);
 223
 224 /*!
 225  * @function dispatch_set_finalizer_f
 226  *
 227  * @abstract
 228  * Set the finalizer function for a dispatch object.
 229  *
 230  * @param
 231  * The dispatch object to modify.
 232  * The result of passing NULL in this parameter is undefined.
 233  *
 234  * @param
 235  * The finalizer function pointer.
 236  *
 237  * @discussion
 238  * A dispatch object's finalizer will be invoked on the object's target queue
 239  * after all references to the object have been released. This finalizer may be
 240  * used by the application to release any resources associated with the object,
 241  * such as freeing the object's context.
 242  * The context parameter passed to the finalizer function is the current
 243  * context of the dispatch object at the time the finalizer call is made.
 244  */
 245 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 246 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 247 void
 248 dispatch_set_finalizer_f(dispatch_object_t object,
 249         dispatch_function_t finalizer);
 250
 251 /*!
 252  * @function dispatch_suspend
 253  *
 254  * @abstract
 255  * Suspends the invocation of blocks on a dispatch object.
 256  *
 257  * @discussion
 258  * A suspended object will not invoke any blocks associated with it. The
 259  * suspension of an object will occur after any running block associated with
 260  * the object completes.
 261  *
 262  * Calls to dispatch_suspend() must be balanced with calls
 263  * to dispatch_resume().
 264  *
 265  * @param object
 266  * The object to be suspended.
 267  * The result of passing NULL in this parameter is undefined.
 268  */
 269 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 270 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 271 void
 272 dispatch_suspend(dispatch_object_t object);
 273
 274 /*!
 275  * @function dispatch_resume
 276  *
 277  * @abstract
 278  * Resumes the invocation of blocks on a dispatch object.
 279  *
 280  * @param object
 281  * The object to be resumed.
 282  * The result of passing NULL in this parameter is undefined.
 283  */
 284 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 285 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 286 void
 287 dispatch_resume(dispatch_object_t object);
 288
 289 __END_DECLS
 290
 291 #endif