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) && !defined(__DISPATCH_BUILDING_DISPATCH__)
  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 #ifdef __BLOCKS__
 103 /*!
 104  * @typedef dispatch_block_t
 105  *
 106  * @abstract
 107  * The type of blocks submitted to dispatch queues, which take no arguments
 108  * and have no return value.
 109  *
 110  * @discussion
 111  * When not building with Objective-C ARC, a block object allocated on or
 112  * copied to the heap must be released with a -[release] message or the
 113  * Block_release() function.
 114  *
 115  * The declaration of a block literal allocates storage on the stack.
 116  * Therefore, this is an invalid construct:
 117  * <code>
 118  * dispatch_block_t block;
 119  * if (x) {
 120  *     block = ^{ printf("true\n"); };
 121  * } else {
 122  *     block = ^{ printf("false\n"); };
 123  * }
 124  * block(); // unsafe!!!
 125  * </code>
 126  *
 127  * What is happening behind the scenes:
 128  * <code>
 129  * if (x) {
 130  *     struct Block __tmp_1 = ...; // setup details
 131  *     block = &__tmp_1;
 132  * } else {
 133  *     struct Block __tmp_2 = ...; // setup details
 134  *     block = &__tmp_2;
 135  * }
 136  * </code>
 137  *
 138  * As the example demonstrates, the address of a stack variable is escaping the
 139  * scope in which it is allocated. That is a classic C bug.
 140  *
 141  * Instead, the block literal must be copied to the heap with the Block_copy()
 142  * function or by sending it a -[copy] message.
 143  */
 144 typedef void (^dispatch_block_t)(void);
 145 #endif // __BLOCKS__
 146
 147 __BEGIN_DECLS
 148
 149 /*!
 150  * @function dispatch_retain
 151  *
 152  * @abstract
 153  * Increment the reference count of a dispatch object.
 154  *
 155  * @discussion
 156  * Calls to dispatch_retain() must be balanced with calls to
 157  * dispatch_release().
 158  *
 159  * @param object
 160  * The object to retain.
 161  * The result of passing NULL in this parameter is undefined.
 162  */
 163 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 164 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 165 void
 166 dispatch_retain(dispatch_object_t object);
 167 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 168 #undef dispatch_retain
 169 #define dispatch_retain(object) ({ dispatch_object_t _o = (object); \
 170                 _dispatch_object_validate(_o); (void)[_o retain]; })
 171 #endif
 172
 173 /*!
 174  * @function dispatch_release
 175  *
 176  * @abstract
 177  * Decrement the reference count of a dispatch object.
 178  *
 179  * @discussion
 180  * A dispatch object is asynchronously deallocated once all references are
 181  * released (i.e. the reference count becomes zero). The system does not
 182  * guarantee that a given client is the last or only reference to a given
 183  * object.
 184  *
 185  * @param object
 186  * The object to release.
 187  * The result of passing NULL in this parameter is undefined.
 188  */
 189 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 190 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 191 void
 192 dispatch_release(dispatch_object_t object);
 193 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 194 #undef dispatch_release
 195 #define dispatch_release(object) ({ dispatch_object_t _o = (object); \
 196                 _dispatch_object_validate(_o); [_o release]; })
 197 #endif
 198
 199 /*!
 200  * @function dispatch_get_context
 201  *
 202  * @abstract
 203  * Returns the application defined context of the object.
 204  *
 205  * @param object
 206  * The result of passing NULL in this parameter is undefined.
 207  *
 208  * @result
 209  * The context of the object; may be NULL.
 210  */
 211 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 212 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
 213 DISPATCH_NOTHROW
 214 void *
 215 dispatch_get_context(dispatch_object_t object);
 216
 217 /*!
 218  * @function dispatch_set_context
 219  *
 220  * @abstract
 221  * Associates an application defined context with the object.
 222  *
 223  * @param object
 224  * The result of passing NULL in this parameter is undefined.
 225  *
 226  * @param context
 227  * The new client defined context for the object. This may be NULL.
 228  *
 229  */
 230 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 231 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 232 void
 233 dispatch_set_context(dispatch_object_t object, void *context);
 234
 235 /*!
 236  * @function dispatch_set_finalizer_f
 237  *
 238  * @abstract
 239  * Set the finalizer function for a dispatch object.
 240  *
 241  * @param object
 242  * The dispatch object to modify.
 243  * The result of passing NULL in this parameter is undefined.
 244  *
 245  * @param finalizer
 246  * The finalizer function pointer.
 247  *
 248  * @discussion
 249  * A dispatch object's finalizer will be invoked on the object's target queue
 250  * after all references to the object have been released. This finalizer may be
 251  * used by the application to release any resources associated with the object,
 252  * such as freeing the object's context.
 253  * The context parameter passed to the finalizer function is the current
 254  * context of the dispatch object at the time the finalizer call is made.
 255  */
 256 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 257 DISPATCH_EXPORT DISPATCH_NOTHROW //DISPATCH_NONNULL1
 258 void
 259 dispatch_set_finalizer_f(dispatch_object_t object,
 260                 dispatch_function_t finalizer);
 261
 262 /*!
 263  * @function dispatch_suspend
 264  *
 265  * @abstract
 266  * Suspends the invocation of blocks on a dispatch object.
 267  *
 268  * @discussion
 269  * A suspended object will not invoke any blocks associated with it. The
 270  * suspension of an object will occur after any running block associated with
 271  * the object completes.
 272  *
 273  * Calls to dispatch_suspend() must be balanced with calls
 274  * to dispatch_resume().
 275  *
 276  * @param object
 277  * The object to be suspended.
 278  * The result of passing NULL in this parameter is undefined.
 279  */
 280 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 281 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 282 void
 283 dispatch_suspend(dispatch_object_t object);
 284
 285 /*!
 286  * @function dispatch_resume
 287  *
 288  * @abstract
 289  * Resumes the invocation of blocks on a dispatch object.
 290  *
 291  * @param object
 292  * The object to be resumed.
 293  * The result of passing NULL in this parameter is undefined.
 294  */
 295 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 296 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 297 void
 298 dispatch_resume(dispatch_object_t object);
 299
 300 #ifdef __BLOCKS__
 301 /*!
 302  * @function dispatch_wait
 303  *
 304  * @abstract
 305  * Wait synchronously for an object or until the specified timeout has elapsed.
 306  *
 307  * @discussion
 308  * Type-generic macro that maps to dispatch_block_wait, dispatch_group_wait or
 309  * dispatch_semaphore_wait, depending on the type of the first argument.
 310  * See documentation for these functions for more details.
 311  * This function is unavailable for any other object type.
 312  *
 313  * @param object
 314  * The object to wait on.
 315  * The result of passing NULL in this parameter is undefined.
 316  *
 317  * @param timeout
 318  * When to timeout (see dispatch_time). As a convenience, there are the
 319  * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
 320  *
 321  * @result
 322  * Returns zero on success or non-zero on error (i.e. timed out).
 323  */
 324 DISPATCH_UNAVAILABLE
 325 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 326 long
 327 dispatch_wait(void *object, dispatch_time_t timeout);
 328 #if __has_extension(c_generic_selections)
 329 #define dispatch_wait(object, timeout) \
 330                 _Generic((object), \
 331                         dispatch_block_t:dispatch_block_wait, \
 332                         dispatch_group_t:dispatch_group_wait, \
 333                         dispatch_semaphore_t:dispatch_semaphore_wait \
 334                 )((object),(timeout))
 335 #endif
 336
 337 /*!
 338  * @function dispatch_notify
 339  *
 340  * @abstract
 341  * Schedule a notification block to be submitted to a queue when the execution
 342  * of a specified object has completed.
 343  *
 344  * @discussion
 345  * Type-generic macro that maps to dispatch_block_notify or
 346  * dispatch_group_notify, depending on the type of the first argument.
 347  * See documentation for these functions for more details.
 348  * This function is unavailable for any other object type.
 349  *
 350  * @param object
 351  * The object to observe.
 352  * The result of passing NULL in this parameter is undefined.
 353  *
 354  * @param queue
 355  * The queue to which the supplied notification block will be submitted when
 356  * the observed object completes.
 357  *
 358  * @param notification_block
 359  * The block to submit when the observed object completes.
 360  */
 361 DISPATCH_UNAVAILABLE
 362 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 363 void
 364 dispatch_notify(void *object, dispatch_object_t queue,
 365                 dispatch_block_t notification_block);
 366 #if __has_extension(c_generic_selections)
 367 #define dispatch_notify(object, queue, notification_block) \
 368                 _Generic((object), \
 369                         dispatch_block_t:dispatch_block_notify, \
 370                         dispatch_group_t:dispatch_group_notify \
 371                 )((object),(queue), (notification_block))
 372 #endif
 373
 374 /*!
 375  * @function dispatch_cancel
 376  *
 377  * @abstract
 378  * Cancel the specified object.
 379  *
 380  * @discussion
 381  * Type-generic macro that maps to dispatch_block_cancel or
 382  * dispatch_source_cancel, depending on the type of the first argument.
 383  * See documentation for these functions for more details.
 384  * This function is unavailable for any other object type.
 385  *
 386  * @param object
 387  * The object to cancel.
 388  * The result of passing NULL in this parameter is undefined.
 389  */
 390 DISPATCH_UNAVAILABLE
 391 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 392 void
 393 dispatch_cancel(void *object);
 394 #if __has_extension(c_generic_selections)
 395 #define dispatch_cancel(object) \
 396                 _Generic((object), \
 397                         dispatch_block_t:dispatch_block_cancel, \
 398                         dispatch_source_t:dispatch_source_cancel \
 399                 )((object))
 400 #endif
 401
 402 /*!
 403  * @function dispatch_testcancel
 404  *
 405  * @abstract
 406  * Test whether the specified object has been canceled
 407  *
 408  * @discussion
 409  * Type-generic macro that maps to dispatch_block_testcancel or
 410  * dispatch_source_testcancel, depending on the type of the first argument.
 411  * See documentation for these functions for more details.
 412  * This function is unavailable for any other object type.
 413  *
 414  * @param object
 415  * The object to test.
 416  * The result of passing NULL in this parameter is undefined.
 417  *
 418  * @result
 419  * Non-zero if canceled and zero if not canceled.
 420  */
 421 DISPATCH_UNAVAILABLE
 422 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 423 DISPATCH_NOTHROW
 424 long
 425 dispatch_testcancel(void *object);
 426 #if __has_extension(c_generic_selections)
 427 #define dispatch_testcancel(object) \
 428                 _Generic((object), \
 429                         dispatch_block_t:dispatch_block_testcancel, \
 430                         dispatch_source_t:dispatch_source_testcancel \
 431                 )((object))
 432 #endif
 433 #endif // __BLOCKS__
 434
 435 /*!
 436  * @function dispatch_debug
 437  *
 438  * @abstract
 439  * Programmatically log debug information about a dispatch object.
 440  *
 441  * @discussion
 442  * Programmatically log debug information about a dispatch object. By default,
 443  * the log output is sent to syslog at notice level. In the debug version of
 444  * the library, the log output is sent to a file in /var/tmp.
 445  * The log output destination can be configured via the LIBDISPATCH_LOG
 446  * environment variable, valid values are: YES, NO, syslog, stderr, file.
 447  *
 448  * This function is deprecated and will be removed in a future release.
 449  * Objective-C callers may use -debugDescription instead.
 450  *
 451  * @param object
 452  * The object to introspect.
 453  *
 454  * @param message
 455  * The message to log above and beyond the introspection.
 456  */
 457 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
 458 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
 459 __attribute__((__format__(printf,2,3)))
 460 void
 461 dispatch_debug(dispatch_object_t object, const char *message, ...);
 462
 463 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
 464 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
 465 __attribute__((__format__(printf,2,0)))
 466 void
 467 dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
 468
 469 __END_DECLS
 470
 471 #endif