dispatch/block.h

   1 /*
   2  * Copyright (c) 2014 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_BLOCK__
  22 #define __DISPATCH_BLOCK__
  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 #ifdef __BLOCKS__
  30
  31 /*!
  32  * @group Dispatch block objects
  33  */
  34
  35 __BEGIN_DECLS
  36
  37 /*!
  38  * @typedef dispatch_block_flags_t
  39  * Flags to pass to the dispatch_block_create* functions.
  40  *
  41  * @const DISPATCH_BLOCK_BARRIER
  42  * Flag indicating that a dispatch block object should act as a barrier block
  43  * when submitted to a DISPATCH_QUEUE_CONCURRENT queue.
  44  * See dispatch_barrier_async() for details.
  45  * This flag has no effect when the dispatch block object is invoked directly.
  46  *
  47  * @const DISPATCH_BLOCK_DETACHED
  48  * Flag indicating that a dispatch block object should execute disassociated
  49  * from current execution context attributes such as QOS class, os_activity_t
  50  * and properties of the current IPC request (if any). If invoked directly, the
  51  * block object will remove these attributes from the calling thread for the
  52  * duration of the block body (before applying attributes assigned to the block
  53  * object, if any). If submitted to a queue, the block object will be executed
  54  * with the attributes of the queue (or any attributes specifically assigned to
  55  * the block object).
  56  *
  57  * @const DISPATCH_BLOCK_ASSIGN_CURRENT
  58  * Flag indicating that a dispatch block object should be assigned the execution
  59  * context attributes that are current at the time the block object is created.
  60  * This applies to attributes such as QOS class, os_activity_t and properties of
  61  * the current IPC request (if any). If invoked directly, the block object will
  62  * apply these attributes to the calling thread for the duration of the block
  63  * body. If the block object is submitted to a queue, this flag replaces the
  64  * default behavior of associating the submitted block instance with the
  65  * execution context attributes that are current at the time of submission.
  66  * If a specific QOS class is assigned with DISPATCH_BLOCK_NO_QOS_CLASS or
  67  * dispatch_block_create_with_qos_class(), that QOS class takes precedence over
  68  * the QOS class assignment indicated by this flag.
  69  *
  70  * @const DISPATCH_BLOCK_NO_QOS_CLASS
  71  * Flag indicating that a dispatch block object should be not be assigned a QOS
  72  * class. If invoked directly, the block object will be executed with the QOS
  73  * class of the calling thread. If the block object is submitted to a queue,
  74  * this replaces the default behavior of associating the submitted block
  75  * instance with the QOS class current at the time of submission.
  76  * This flag is ignored if a specific QOS class is assigned with
  77  * dispatch_block_create_with_qos_class().
  78  *
  79  * @const DISPATCH_BLOCK_INHERIT_QOS_CLASS
  80  * Flag indicating that execution of a dispatch block object submitted to a
  81  * queue should prefer the QOS class assigned to the queue over the QOS class
  82  * assigned to the block (resp. associated with the block at the time of
  83  * submission). The latter will only be used if the queue in question does not
  84  * have an assigned QOS class, as long as doing so does not result in a QOS
  85  * class lower than the QOS class inherited from the queue's target queue.
  86  * This flag is the default when a dispatch block object is submitted to a queue
  87  * for asynchronous execution and has no effect when the dispatch block object
  88  * is invoked directly. It is ignored if DISPATCH_BLOCK_ENFORCE_QOS_CLASS is
  89  * also passed.
  90  *
  91  * @const DISPATCH_BLOCK_ENFORCE_QOS_CLASS
  92  * Flag indicating that execution of a dispatch block object submitted to a
  93  * queue should prefer the QOS class assigned to the block (resp. associated
  94  * with the block at the time of submission) over the QOS class assigned to the
  95  * queue, as long as doing so will not result in a lower QOS class.
  96  * This flag is the default when a dispatch block object is submitted to a queue
  97  * for synchronous execution or when the dispatch block object is invoked
  98  * directly.
  99  */
 100 DISPATCH_ENUM(dispatch_block_flags, unsigned long,
 101         DISPATCH_BLOCK_BARRIER
 102                         DISPATCH_ENUM_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x1,
 103         DISPATCH_BLOCK_DETACHED
 104                         DISPATCH_ENUM_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x2,
 105         DISPATCH_BLOCK_ASSIGN_CURRENT
 106                         DISPATCH_ENUM_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x4,
 107         DISPATCH_BLOCK_NO_QOS_CLASS
 108                         DISPATCH_ENUM_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x8,
 109         DISPATCH_BLOCK_INHERIT_QOS_CLASS
 110                         DISPATCH_ENUM_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x10,
 111         DISPATCH_BLOCK_ENFORCE_QOS_CLASS
 112                         DISPATCH_ENUM_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x20,
 113 );
 114
 115 /*!
 116  * @function dispatch_block_create
 117  *
 118  * @abstract
 119  * Create a new dispatch block object on the heap from an existing block and
 120  * the given flags.
 121  *
 122  * @discussion
 123  * The provided block is Block_copy'ed to the heap and retained by the newly
 124  * created dispatch block object.
 125  *
 126  * The returned dispatch block object is intended to be submitted to a dispatch
 127  * queue with dispatch_async() and related functions, but may also be invoked
 128  * directly. Both operations can be performed an arbitrary number of times but
 129  * only the first completed execution of a dispatch block object can be waited
 130  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 131  *
 132  * If the returned dispatch block object is submitted to a dispatch queue, the
 133  * submitted block instance will be associated with the QOS class current at the
 134  * time of submission, unless one of the following flags assigned a specific QOS
 135  * class (or no QOS class) at the time of block creation:
 136  *  - DISPATCH_BLOCK_ASSIGN_CURRENT
 137  *  - DISPATCH_BLOCK_NO_QOS_CLASS
 138  *  - DISPATCH_BLOCK_DETACHED
 139  * The QOS class the block object will be executed with also depends on the QOS
 140  * class assigned to the queue and which of the following flags was specified or
 141  * defaulted to:
 142  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS (default for asynchronous execution)
 143  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS (default for synchronous execution)
 144  * See description of dispatch_block_flags_t for details.
 145  *
 146  * If the returned dispatch block object is submitted directly to a serial queue
 147  * and is configured to execute with a specific QOS class, the system will make
 148  * a best effort to apply the necessary QOS overrides to ensure that blocks
 149  * submitted earlier to the serial queue are executed at that same QOS class or
 150  * higher.
 151  *
 152  * @param flags
 153  * Configuration flags for the block object.
 154  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 155  * results in NULL being returned.
 156  *
 157  * @param block
 158  * The block to create the dispatch block object from.
 159  *
 160  * @result
 161  * The newly created dispatch block object, or NULL.
 162  * When not building with Objective-C ARC, must be released with a -[release]
 163  * message or the Block_release() function.
 164  */
 165 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 166 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_RETURNS_RETAINED_BLOCK
 167 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 168 dispatch_block_t
 169 dispatch_block_create(dispatch_block_flags_t flags, dispatch_block_t block);
 170
 171 /*!
 172  * @function dispatch_block_create_with_qos_class
 173  *
 174  * @abstract
 175  * Create a new dispatch block object on the heap from an existing block and
 176  * the given flags, and assign it the specified QOS class and relative priority.
 177  *
 178  * @discussion
 179  * The provided block is Block_copy'ed to the heap and retained by the newly
 180  * created dispatch block object.
 181  *
 182  * The returned dispatch block object is intended to be submitted to a dispatch
 183  * queue with dispatch_async() and related functions, but may also be invoked
 184  * directly. Both operations can be performed an arbitrary number of times but
 185  * only the first completed execution of a dispatch block object can be waited
 186  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 187  *
 188  * If invoked directly, the returned dispatch block object will be executed with
 189  * the assigned QOS class as long as that does not result in a lower QOS class
 190  * than what is current on the calling thread.
 191  *
 192  * If the returned dispatch block object is submitted to a dispatch queue, the
 193  * QOS class it will be executed with depends on the QOS class assigned to the
 194  * block, the QOS class assigned to the queue and which of the following flags
 195  * was specified or defaulted to:
 196  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS: default for asynchronous execution
 197  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS: default for synchronous execution
 198  * See description of dispatch_block_flags_t for details.
 199  *
 200  * If the returned dispatch block object is submitted directly to a serial queue
 201  * and is configured to execute with a specific QOS class, the system will make
 202  * a best effort to apply the necessary QOS overrides to ensure that blocks
 203  * submitted earlier to the serial queue are executed at that same QOS class or
 204  * higher.
 205  *
 206  * @param flags
 207  * Configuration flags for the new block object.
 208  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 209  * results in NULL being returned.
 210  *
 211  * @param qos_class
 212  * A QOS class value:
 213  *  - QOS_CLASS_USER_INTERACTIVE
 214  *  - QOS_CLASS_USER_INITIATED
 215  *  - QOS_CLASS_DEFAULT
 216  *  - QOS_CLASS_UTILITY
 217  *  - QOS_CLASS_BACKGROUND
 218  *  - QOS_CLASS_UNSPECIFIED
 219  * Passing QOS_CLASS_UNSPECIFIED is equivalent to specifying the
 220  * DISPATCH_BLOCK_NO_QOS_CLASS flag. Passing any other value results in NULL
 221  * being returned.
 222  *
 223  * @param relative_priority
 224  * A relative priority within the QOS class. This value is a negative
 225  * offset from the maximum supported scheduler priority for the given class.
 226  * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY
 227  * results in NULL being returned.
 228  *
 229  * @param block
 230  * The block to create the dispatch block object from.
 231  *
 232  * @result
 233  * The newly created dispatch block object, or NULL.
 234  * When not building with Objective-C ARC, must be released with a -[release]
 235  * message or the Block_release() function.
 236  */
 237 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 238 DISPATCH_EXPORT DISPATCH_NONNULL4 DISPATCH_RETURNS_RETAINED_BLOCK
 239 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 240 dispatch_block_t
 241 dispatch_block_create_with_qos_class(dispatch_block_flags_t flags,
 242                 dispatch_qos_class_t qos_class, int relative_priority,
 243                 dispatch_block_t block);
 244
 245 /*!
 246  * @function dispatch_block_perform
 247  *
 248  * @abstract
 249  * Create, synchronously execute and release a dispatch block object from the
 250  * specified block and flags.
 251  *
 252  * @discussion
 253  * Behaves identically to the sequence
 254  * <code>
 255  * dispatch_block_t b = dispatch_block_create(flags, block);
 256  * b();
 257  * Block_release(b);
 258  * </code>
 259  * but may be implemented more efficiently internally by not requiring a copy
 260  * to the heap of the specified block or the allocation of a new block object.
 261  *
 262  * @param flags
 263  * Configuration flags for the temporary block object.
 264  * The result of passing a value that is not a bitwise OR of flags from
 265  * dispatch_block_flags_t is undefined.
 266  *
 267  * @param block
 268  * The block to create the temporary block object from.
 269  */
 270 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 271 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
 272 void
 273 dispatch_block_perform(dispatch_block_flags_t flags, dispatch_block_t block);
 274
 275 /*!
 276  * @function dispatch_block_wait
 277  *
 278  * @abstract
 279  * Wait synchronously until execution of the specified dispatch block object has
 280  * completed or until the specified timeout has elapsed.
 281  *
 282  * @discussion
 283  * This function will return immediately if execution of the block object has
 284  * already completed.
 285  *
 286  * It is not possible to wait for multiple executions of the same block object
 287  * with this interface; use dispatch_group_wait() for that purpose. A single
 288  * dispatch block object may either be waited on once and executed once,
 289  * or it may be executed any number of times. The behavior of any other
 290  * combination is undefined. Submission to a dispatch queue counts as an
 291  * execution, even if cancelation (dispatch_block_cancel) means the block's
 292  * code never runs.
 293  *
 294  * The result of calling this function from multiple threads simultaneously
 295  * with the same dispatch block object is undefined, but note that doing so
 296  * would violate the rules described in the previous paragraph.
 297  *
 298  * If this function returns indicating that the specified timeout has elapsed,
 299  * then that invocation does not count as the one allowed wait.
 300  *
 301  * If at the time this function is called, the specified dispatch block object
 302  * has been submitted directly to a serial queue, the system will make a best
 303  * effort to apply the necessary QOS overrides to ensure that the block and any
 304  * blocks submitted earlier to that serial queue are executed at the QOS class
 305  * (or higher) of the thread calling dispatch_block_wait().
 306  *
 307  * @param block
 308  * The dispatch block object to wait on.
 309  * The result of passing NULL or a block object not returned by one of the
 310  * dispatch_block_create* functions is undefined.
 311  *
 312  * @param timeout
 313  * When to timeout (see dispatch_time). As a convenience, there are the
 314  * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
 315  *
 316  * @result
 317  * Returns zero on success (the dispatch block object completed within the
 318  * specified timeout) or non-zero on error (i.e. timed out).
 319  */
 320 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 321 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 322 long
 323 dispatch_block_wait(dispatch_block_t block, dispatch_time_t timeout);
 324
 325 /*!
 326  * @function dispatch_block_notify
 327  *
 328  * @abstract
 329  * Schedule a notification block to be submitted to a queue when the execution
 330  * of a specified dispatch block object has completed.
 331  *
 332  * @discussion
 333  * This function will submit the notification block immediately if execution of
 334  * the observed block object has already completed.
 335  *
 336  * It is not possible to be notified of multiple executions of the same block
 337  * object with this interface, use dispatch_group_notify() for that purpose.
 338  *
 339  * A single dispatch block object may either be observed one or more times
 340  * and executed once, or it may be executed any number of times. The behavior
 341  * of any other combination is undefined. Submission to a dispatch queue
 342  * counts as an execution, even if cancellation (dispatch_block_cancel) means
 343  * the block's code never runs.
 344  *
 345  * If multiple notification blocks are scheduled for a single block object,
 346  * there is no defined order in which the notification blocks will be submitted
 347  * to their associated queues.
 348  *
 349  * @param block
 350  * The dispatch block object to observe.
 351  * The result of passing NULL or a block object not returned by one of the
 352  * dispatch_block_create* functions is undefined.
 353  *
 354  * @param queue
 355  * The queue to which the supplied notification block will be submitted when
 356  * the observed block completes.
 357  *
 358  * @param notification_block
 359  * The notification block to submit when the observed block object completes.
 360  */
 361 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 362 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 363 void
 364 dispatch_block_notify(dispatch_block_t block, dispatch_queue_t queue,
 365                 dispatch_block_t notification_block);
 366
 367 /*!
 368  * @function dispatch_block_cancel
 369  *
 370  * @abstract
 371  * Asynchronously cancel the specified dispatch block object.
 372  *
 373  * @discussion
 374  * Cancellation causes any future execution of the dispatch block object to
 375  * return immediately, but does not affect any execution of the block object
 376  * that is already in progress.
 377  *
 378  * Release of any resources associated with the block object will be delayed
 379  * until execution of the block object is next attempted (or any execution
 380  * already in progress completes).
 381  *
 382  * NOTE: care needs to be taken to ensure that a block object that may be
 383  *       canceled does not capture any resources that require execution of the
 384  *       block body in order to be released (e.g. memory allocated with
 385  *       malloc(3) that the block body calls free(3) on). Such resources will
 386  *       be leaked if the block body is never executed due to cancellation.
 387  *
 388  * @param block
 389  * The dispatch block object to cancel.
 390  * The result of passing NULL or a block object not returned by one of the
 391  * dispatch_block_create* functions is undefined.
 392  */
 393 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 394 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 395 void
 396 dispatch_block_cancel(dispatch_block_t block);
 397
 398 /*!
 399  * @function dispatch_block_testcancel
 400  *
 401  * @abstract
 402  * Tests whether the given dispatch block object has been canceled.
 403  *
 404  * @param block
 405  * The dispatch block object to test.
 406  * The result of passing NULL or a block object not returned by one of the
 407  * dispatch_block_create* functions is undefined.
 408  *
 409  * @result
 410  * Non-zero if canceled and zero if not canceled.
 411  */
 412 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 413 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 414 DISPATCH_NOTHROW
 415 long
 416 dispatch_block_testcancel(dispatch_block_t block);
 417
 418 __END_DECLS
 419
 420 #endif // __BLOCKS__
 421
 422 #endif // __DISPATCH_BLOCK__