dispatch/queue.h

   1 /*
   2  * Copyright (c) 2008-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_QUEUE__
  22 #define __DISPATCH_QUEUE__
  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 #if __has_include(<sys/qos.h>)
  30 #include <sys/qos.h>
  31 #endif
  32
  33 DISPATCH_ASSUME_NONNULL_BEGIN
  34
  35 /*!
  36  * @header
  37  *
  38  * Dispatch is an abstract model for expressing concurrency via simple but
  39  * powerful API.
  40  *
  41  * At the core, dispatch provides serial FIFO queues to which blocks may be
  42  * submitted. Blocks submitted to these dispatch queues are invoked on a pool
  43  * of threads fully managed by the system. No guarantee is made regarding
  44  * which thread a block will be invoked on; however, it is guaranteed that only
  45  * one block submitted to the FIFO dispatch queue will be invoked at a time.
  46  *
  47  * When multiple queues have blocks to be processed, the system is free to
  48  * allocate additional threads to invoke the blocks concurrently. When the
  49  * queues become empty, these threads are automatically released.
  50  */
  51
  52 /*!
  53  * @typedef dispatch_queue_t
  54  *
  55  * @abstract
  56  * Dispatch queues invoke blocks submitted to them serially in FIFO order. A
  57  * queue will only invoke one block at a time, but independent queues may each
  58  * invoke their blocks concurrently with respect to each other.
  59  *
  60  * @discussion
  61  * Dispatch queues are lightweight objects to which blocks may be submitted.
  62  * The system manages a pool of threads which process dispatch queues and
  63  * invoke blocks submitted to them.
  64  *
  65  * Conceptually a dispatch queue may have its own thread of execution, and
  66  * interaction between queues is highly asynchronous.
  67  *
  68  * Dispatch queues are reference counted via calls to dispatch_retain() and
  69  * dispatch_release(). Pending blocks submitted to a queue also hold a
  70  * reference to the queue until they have finished. Once all references to a
  71  * queue have been released, the queue will be deallocated by the system.
  72  */
  73 DISPATCH_DECL(dispatch_queue);
  74
  75 __BEGIN_DECLS
  76
  77 /*!
  78  * @function dispatch_async
  79  *
  80  * @abstract
  81  * Submits a block for asynchronous execution on a dispatch queue.
  82  *
  83  * @discussion
  84  * The dispatch_async() function is the fundamental mechanism for submitting
  85  * blocks to a dispatch queue.
  86  *
  87  * Calls to dispatch_async() always return immediately after the block has
  88  * been submitted, and never wait for the block to be invoked.
  89  *
  90  * The target queue determines whether the block will be invoked serially or
  91  * concurrently with respect to other blocks submitted to that same queue.
  92  * Serial queues are processed concurrently with respect to each other.
  93  *
  94  * @param queue
  95  * The target dispatch queue to which the block is submitted.
  96  * The system will hold a reference on the target queue until the block
  97  * has finished.
  98  * The result of passing NULL in this parameter is undefined.
  99  *
 100  * @param block
 101  * The block to submit to the target dispatch queue. This function performs
 102  * Block_copy() and Block_release() on behalf of callers.
 103  * The result of passing NULL in this parameter is undefined.
 104  */
 105 #ifdef __BLOCKS__
 106 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 107 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 108 void
 109 dispatch_async(dispatch_queue_t queue, dispatch_block_t block);
 110 #endif
 111
 112 /*!
 113  * @function dispatch_async_f
 114  *
 115  * @abstract
 116  * Submits a function for asynchronous execution on a dispatch queue.
 117  *
 118  * @discussion
 119  * See dispatch_async() for details.
 120  *
 121  * @param queue
 122  * The target dispatch queue to which the function is submitted.
 123  * The system will hold a reference on the target queue until the function
 124  * has returned.
 125  * The result of passing NULL in this parameter is undefined.
 126  *
 127  * @param context
 128  * The application-defined context parameter to pass to the function.
 129  *
 130  * @param work
 131  * The application-defined function to invoke on the target queue. The first
 132  * parameter passed to this function is the context provided to
 133  * dispatch_async_f().
 134  * The result of passing NULL in this parameter is undefined.
 135  */
 136 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 137 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 138 void
 139 dispatch_async_f(dispatch_queue_t queue,
 140         void *_Nullable context,
 141         dispatch_function_t work);
 142
 143 /*!
 144  * @function dispatch_sync
 145  *
 146  * @abstract
 147  * Submits a block for synchronous execution on a dispatch queue.
 148  *
 149  * @discussion
 150  * Submits a block to a dispatch queue like dispatch_async(), however
 151  * dispatch_sync() will not return until the block has finished.
 152  *
 153  * Calls to dispatch_sync() targeting the current queue will result
 154  * in dead-lock. Use of dispatch_sync() is also subject to the same
 155  * multi-party dead-lock problems that may result from the use of a mutex.
 156  * Use of dispatch_async() is preferred.
 157  *
 158  * Unlike dispatch_async(), no retain is performed on the target queue. Because
 159  * calls to this function are synchronous, the dispatch_sync() "borrows" the
 160  * reference of the caller.
 161  *
 162  * As an optimization, dispatch_sync() invokes the block on the current
 163  * thread when possible.
 164  *
 165  * @param queue
 166  * The target dispatch queue to which the block is submitted.
 167  * The result of passing NULL in this parameter is undefined.
 168  *
 169  * @param block
 170  * The block to be invoked on the target dispatch queue.
 171  * The result of passing NULL in this parameter is undefined.
 172  */
 173 #ifdef __BLOCKS__
 174 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 175 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 176 void
 177 dispatch_sync(dispatch_queue_t queue, DISPATCH_NOESCAPE dispatch_block_t block);
 178 #endif
 179
 180 /*!
 181  * @function dispatch_sync_f
 182  *
 183  * @abstract
 184  * Submits a function for synchronous execution on a dispatch queue.
 185  *
 186  * @discussion
 187  * See dispatch_sync() for details.
 188  *
 189  * @param queue
 190  * The target dispatch queue to which the function is submitted.
 191  * The result of passing NULL in this parameter is undefined.
 192  *
 193  * @param context
 194  * The application-defined context parameter to pass to the function.
 195  *
 196  * @param work
 197  * The application-defined function to invoke on the target queue. The first
 198  * parameter passed to this function is the context provided to
 199  * dispatch_sync_f().
 200  * The result of passing NULL in this parameter is undefined.
 201  */
 202 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 203 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 204 void
 205 dispatch_sync_f(dispatch_queue_t queue,
 206         void *_Nullable context,
 207         dispatch_function_t work);
 208
 209 /*!
 210  * @function dispatch_apply
 211  *
 212  * @abstract
 213  * Submits a block to a dispatch queue for multiple invocations.
 214  *
 215  * @discussion
 216  * Submits a block to a dispatch queue for multiple invocations. This function
 217  * waits for the task block to complete before returning. If the target queue
 218  * is concurrent, the block may be invoked concurrently, and it must therefore
 219  * be reentrant safe.
 220  *
 221  * Each invocation of the block will be passed the current index of iteration.
 222  *
 223  * @param iterations
 224  * The number of iterations to perform.
 225  *
 226  * @param queue
 227  * The target dispatch queue to which the block is submitted.
 228  * The result of passing NULL in this parameter is undefined.
 229  *
 230  * @param block
 231  * The block to be invoked the specified number of iterations.
 232  * The result of passing NULL in this parameter is undefined.
 233  */
 234 #ifdef __BLOCKS__
 235 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 236 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NOTHROW
 237 void
 238 dispatch_apply(size_t iterations, dispatch_queue_t queue,
 239                 DISPATCH_NOESCAPE void (^block)(size_t));
 240 #endif
 241
 242 /*!
 243  * @function dispatch_apply_f
 244  *
 245  * @abstract
 246  * Submits a function to a dispatch queue for multiple invocations.
 247  *
 248  * @discussion
 249  * See dispatch_apply() for details.
 250  *
 251  * @param iterations
 252  * The number of iterations to perform.
 253  *
 254  * @param queue
 255  * The target dispatch queue to which the function is submitted.
 256  * The result of passing NULL in this parameter is undefined.
 257  *
 258  * @param context
 259  * The application-defined context parameter to pass to the function.
 260  *
 261  * @param work
 262  * The application-defined function to invoke on the target queue. The first
 263  * parameter passed to this function is the context provided to
 264  * dispatch_apply_f(). The second parameter passed to this function is the
 265  * current index of iteration.
 266  * The result of passing NULL in this parameter is undefined.
 267  */
 268 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 269 DISPATCH_EXPORT DISPATCH_NONNULL4 DISPATCH_NOTHROW
 270 void
 271 dispatch_apply_f(size_t iterations, dispatch_queue_t queue,
 272         void *_Nullable context,
 273         void (*work)(void *_Nullable, size_t));
 274
 275 /*!
 276  * @function dispatch_get_current_queue
 277  *
 278  * @abstract
 279  * Returns the queue on which the currently executing block is running.
 280  *
 281  * @discussion
 282  * Returns the queue on which the currently executing block is running.
 283  *
 284  * When dispatch_get_current_queue() is called outside of the context of a
 285  * submitted block, it will return the default concurrent queue.
 286  *
 287  * Recommended for debugging and logging purposes only:
 288  * The code must not make any assumptions about the queue returned, unless it
 289  * is one of the global queues or a queue the code has itself created.
 290  * The code must not assume that synchronous execution onto a queue is safe
 291  * from deadlock if that queue is not the one returned by
 292  * dispatch_get_current_queue().
 293  *
 294  * When dispatch_get_current_queue() is called on the main thread, it may
 295  * or may not return the same value as dispatch_get_main_queue(). Comparing
 296  * the two is not a valid way to test whether code is executing on the
 297  * main thread (see dispatch_assert_queue() and dispatch_assert_queue_not()).
 298  *
 299  * This function is deprecated and will be removed in a future release.
 300  *
 301  * @result
 302  * Returns the current queue.
 303  */
 304 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)
 305 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 306 dispatch_queue_t
 307 dispatch_get_current_queue(void);
 308
 309 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 310 DISPATCH_EXPORT struct dispatch_queue_s _dispatch_main_q;
 311
 312 /*!
 313  * @function dispatch_get_main_queue
 314  *
 315  * @abstract
 316  * Returns the default queue that is bound to the main thread.
 317  *
 318  * @discussion
 319  * In order to invoke blocks submitted to the main queue, the application must
 320  * call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the main
 321  * thread.
 322  *
 323  * @result
 324  * Returns the main queue. This queue is created automatically on behalf of
 325  * the main thread before main() is called.
 326  */
 327 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_CONST DISPATCH_NOTHROW
 328 dispatch_queue_t
 329 dispatch_get_main_queue(void)
 330 {
 331         return DISPATCH_GLOBAL_OBJECT(dispatch_queue_t, _dispatch_main_q);
 332 }
 333
 334 /*!
 335  * @typedef dispatch_queue_priority_t
 336  * Type of dispatch_queue_priority
 337  *
 338  * @constant DISPATCH_QUEUE_PRIORITY_HIGH
 339  * Items dispatched to the queue will run at high priority,
 340  * i.e. the queue will be scheduled for execution before
 341  * any default priority or low priority queue.
 342  *
 343  * @constant DISPATCH_QUEUE_PRIORITY_DEFAULT
 344  * Items dispatched to the queue will run at the default
 345  * priority, i.e. the queue will be scheduled for execution
 346  * after all high priority queues have been scheduled, but
 347  * before any low priority queues have been scheduled.
 348  *
 349  * @constant DISPATCH_QUEUE_PRIORITY_LOW
 350  * Items dispatched to the queue will run at low priority,
 351  * i.e. the queue will be scheduled for execution after all
 352  * default priority and high priority queues have been
 353  * scheduled.
 354  *
 355  * @constant DISPATCH_QUEUE_PRIORITY_BACKGROUND
 356  * Items dispatched to the queue will run at background priority, i.e. the queue
 357  * will be scheduled for execution after all higher priority queues have been
 358  * scheduled and the system will run items on this queue on a thread with
 359  * background status as per setpriority(2) (i.e. disk I/O is throttled and the
 360  * thread's scheduling priority is set to lowest value).
 361  */
 362 #define DISPATCH_QUEUE_PRIORITY_HIGH 2
 363 #define DISPATCH_QUEUE_PRIORITY_DEFAULT 0
 364 #define DISPATCH_QUEUE_PRIORITY_LOW (-2)
 365 #define DISPATCH_QUEUE_PRIORITY_BACKGROUND INT16_MIN
 366
 367 typedef long dispatch_queue_priority_t;
 368
 369 /*!
 370  * @typedef dispatch_qos_class_t
 371  * Alias for qos_class_t type.
 372  */
 373 #if __has_include(<sys/qos.h>)
 374 typedef qos_class_t dispatch_qos_class_t;
 375 #else
 376 typedef unsigned int dispatch_qos_class_t;
 377 #endif
 378
 379 /*!
 380  * @function dispatch_get_global_queue
 381  *
 382  * @abstract
 383  * Returns a well-known global concurrent queue of a given quality of service
 384  * class.
 385  *
 386  * @discussion
 387  * The well-known global concurrent queues may not be modified. Calls to
 388  * dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc., will
 389  * have no effect when used with queues returned by this function.
 390  *
 391  * @param identifier
 392  * A quality of service class defined in qos_class_t or a priority defined in
 393  * dispatch_queue_priority_t.
 394  *
 395  * It is recommended to use quality of service class values to identify the
 396  * well-known global concurrent queues:
 397  *  - QOS_CLASS_USER_INTERACTIVE
 398  *  - QOS_CLASS_USER_INITIATED
 399  *  - QOS_CLASS_DEFAULT
 400  *  - QOS_CLASS_UTILITY
 401  *  - QOS_CLASS_BACKGROUND
 402  *
 403  * The global concurrent queues may still be identified by their priority,
 404  * which map to the following QOS classes:
 405  *  - DISPATCH_QUEUE_PRIORITY_HIGH:         QOS_CLASS_USER_INITIATED
 406  *  - DISPATCH_QUEUE_PRIORITY_DEFAULT:      QOS_CLASS_DEFAULT
 407  *  - DISPATCH_QUEUE_PRIORITY_LOW:          QOS_CLASS_UTILITY
 408  *  - DISPATCH_QUEUE_PRIORITY_BACKGROUND:   QOS_CLASS_BACKGROUND
 409  *
 410  * @param flags
 411  * Reserved for future use. Passing any value other than zero may result in
 412  * a NULL return value.
 413  *
 414  * @result
 415  * Returns the requested global queue or NULL if the requested global queue
 416  * does not exist.
 417  */
 418 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 419 DISPATCH_EXPORT DISPATCH_CONST DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 420 dispatch_queue_t
 421 dispatch_get_global_queue(long identifier, unsigned long flags);
 422
 423 /*!
 424  * @typedef dispatch_queue_attr_t
 425  *
 426  * @abstract
 427  * Attribute for dispatch queues.
 428  */
 429 DISPATCH_DECL(dispatch_queue_attr);
 430
 431 /*!
 432  * @const DISPATCH_QUEUE_SERIAL
 433  *
 434  * @discussion A dispatch queue that invokes blocks serially in FIFO order.
 435  */
 436 #define DISPATCH_QUEUE_SERIAL NULL
 437
 438 /*!
 439  * @const DISPATCH_QUEUE_SERIAL_INACTIVE
 440  *
 441  * @discussion
 442  * A dispatch queue that invokes blocks serially in FIFO order, and that is
 443  * created initially inactive. See dispatch_queue_attr_make_initially_inactive().
 444  */
 445 #define DISPATCH_QUEUE_SERIAL_INACTIVE \
 446                 dispatch_queue_attr_make_initially_inactive(DISPATCH_QUEUE_SERIAL)
 447
 448 /*!
 449  * @const DISPATCH_QUEUE_CONCURRENT
 450  *
 451  * @discussion A dispatch queue that may invoke blocks concurrently and supports
 452  * barrier blocks submitted with the dispatch barrier API.
 453  */
 454 #define DISPATCH_QUEUE_CONCURRENT \
 455                 DISPATCH_GLOBAL_OBJECT(dispatch_queue_attr_t, \
 456                 _dispatch_queue_attr_concurrent)
 457 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
 458 DISPATCH_EXPORT
 459 struct dispatch_queue_attr_s _dispatch_queue_attr_concurrent;
 460
 461 /*!
 462  * @const DISPATCH_QUEUE_CONCURRENT_INACTIVE
 463  *
 464  * @discussion
 465  * A dispatch queue that may invoke blocks concurrently and supports barrier
 466  * blocks submitted with the dispatch barrier API, and that is created initially
 467  * inactive. See dispatch_queue_attr_make_initially_inactive().
 468  */
 469 #define DISPATCH_QUEUE_CONCURRENT_INACTIVE \
 470                 dispatch_queue_attr_make_initially_inactive(DISPATCH_QUEUE_CONCURRENT)
 471
 472 /*!
 473  * @function dispatch_queue_attr_make_initially_inactive
 474  *
 475  * @abstract
 476  * Returns an attribute value which may be provided to dispatch_queue_create()
 477  * or dispatch_queue_create_with_target(), in order to make the created queue
 478  * initially inactive.
 479  *
 480  * @discussion
 481  * Dispatch queues may be created in an inactive state. Queues in this state
 482  * have to be activated before any blocks associated with them will be invoked.
 483  *
 484  * A queue in inactive state cannot be deallocated, dispatch_activate() must be
 485  * called before the last reference to a queue created with this attribute is
 486  * released.
 487  *
 488  * The target queue of a queue in inactive state can be changed using
 489  * dispatch_set_target_queue(). Change of target queue is no longer permitted
 490  * once an initially inactive queue has been activated.
 491  *
 492  * @param attr
 493  * A queue attribute value to be combined with the initially inactive attribute.
 494  *
 495  * @return
 496  * Returns an attribute value which may be provided to dispatch_queue_create()
 497  * and dispatch_queue_create_with_target().
 498  * The new value combines the attributes specified by the 'attr' parameter with
 499  * the initially inactive attribute.
 500  */
 501 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 502 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 503 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
 504 dispatch_queue_attr_t
 505 dispatch_queue_attr_make_initially_inactive(
 506                 dispatch_queue_attr_t _Nullable attr);
 507
 508 /*!
 509  * @const DISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL
 510  *
 511  * @discussion
 512  * A dispatch queue created with this attribute invokes blocks serially in FIFO
 513  * order, and surrounds execution of any block submitted asynchronously to it
 514  * with the equivalent of a individual Objective-C <code>@autoreleasepool</code>
 515  * scope.
 516  *
 517  * See dispatch_queue_attr_make_with_autorelease_frequency().
 518  */
 519 #define DISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL \
 520                 dispatch_queue_attr_make_with_autorelease_frequency(\
 521                                 DISPATCH_QUEUE_SERIAL, DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM)
 522
 523 /*!
 524  * @const DISPATCH_QUEUE_CONCURRENT_WITH_AUTORELEASE_POOL
 525  *
 526  * @discussion
 527  * A dispatch queue created with this attribute may invokes blocks concurrently
 528  * and supports barrier blocks submitted with the dispatch barrier API. It also
 529  * surrounds execution of any block submitted asynchronously to it with the
 530  * equivalent of a individual Objective-C <code>@autoreleasepool</code>
 531  *
 532  * See dispatch_queue_attr_make_with_autorelease_frequency().
 533  */
 534 #define DISPATCH_QUEUE_CONCURRENT_WITH_AUTORELEASE_POOL \
 535                 dispatch_queue_attr_make_with_autorelease_frequency(\
 536                                 DISPATCH_QUEUE_CONCURRENT, DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM)
 537
 538 /*!
 539  * @typedef dispatch_autorelease_frequency_t
 540  * Values to pass to the dispatch_queue_attr_make_with_autorelease_frequency()
 541  * function.
 542  *
 543  * @const DISPATCH_AUTORELEASE_FREQUENCY_INHERIT
 544  * Dispatch queues with this autorelease frequency inherit the behavior from
 545  * their target queue. This is the default behavior for manually created queues.
 546  *
 547  * @const DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM
 548  * Dispatch queues with this autorelease frequency push and pop an autorelease
 549  * pool around the execution of every block that was submitted to it
 550  * asynchronously.
 551  * @see dispatch_queue_attr_make_with_autorelease_frequency().
 552  *
 553  * @const DISPATCH_AUTORELEASE_FREQUENCY_NEVER
 554  * Dispatch queues with this autorelease frequency never set up an individual
 555  * autorelease pool around the execution of a block that is submitted to it
 556  * asynchronously. This is the behavior of the global concurrent queues.
 557  */
 558 DISPATCH_ENUM(dispatch_autorelease_frequency, unsigned long,
 559         DISPATCH_AUTORELEASE_FREQUENCY_INHERIT
 560                         DISPATCH_ENUM_AVAILABLE(OSX, 10.12)
 561                         DISPATCH_ENUM_AVAILABLE(IOS, 10.0)
 562                         DISPATCH_ENUM_AVAILABLE(TVOS, 10.0)
 563                         DISPATCH_ENUM_AVAILABLE(WATCHOS, 3.0) = 0,
 564         DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM
 565                         DISPATCH_ENUM_AVAILABLE(OSX, 10.12)
 566                         DISPATCH_ENUM_AVAILABLE(IOS, 10.0)
 567                         DISPATCH_ENUM_AVAILABLE(TVOS, 10.0)
 568                         DISPATCH_ENUM_AVAILABLE(WATCHOS, 3.0) = 1,
 569         DISPATCH_AUTORELEASE_FREQUENCY_NEVER
 570                         DISPATCH_ENUM_AVAILABLE(OSX, 10.12)
 571                         DISPATCH_ENUM_AVAILABLE(IOS, 10.0)
 572                         DISPATCH_ENUM_AVAILABLE(TVOS, 10.0)
 573                         DISPATCH_ENUM_AVAILABLE(WATCHOS, 3.0) = 2,
 574 );
 575
 576 /*!
 577  * @function dispatch_queue_attr_make_with_autorelease_frequency
 578  *
 579  * @abstract
 580  * Returns a dispatch queue attribute value with the autorelease frequency
 581  * set to the specified value.
 582  *
 583  * @discussion
 584  * When a queue uses the per-workitem autorelease frequency (either directly
 585  * or inherithed from its target queue), any block submitted asynchronously to
 586  * this queue (via dispatch_async(), dispatch_barrier_async(),
 587  * dispatch_group_notify(), etc...) is executed as if surrounded by a individual
 588  * Objective-C <code>@autoreleasepool</code> scope.
 589  *
 590  * Autorelease frequency has no effect on blocks that are submitted
 591  * synchronously to a queue (via dispatch_sync(), dispatch_barrier_sync()).
 592  *
 593  * The global concurrent queues have the DISPATCH_AUTORELEASE_FREQUENCY_NEVER
 594  * behavior. Manually created dispatch queues use
 595  * DISPATCH_AUTORELEASE_FREQUENCY_INHERIT by default.
 596  *
 597  * Queues created with this attribute cannot change target queues after having
 598  * been activated. See dispatch_set_target_queue() and dispatch_activate().
 599  *
 600  * @param attr
 601  * A queue attribute value to be combined with the specified autorelease
 602  * frequency or NULL.
 603  *
 604  * @param frequency
 605  * The requested autorelease frequency.
 606  *
 607  * @return
 608  * Returns an attribute value which may be provided to dispatch_queue_create()
 609  * or NULL if an invalid autorelease frequency was requested.
 610  * This new value combines the attributes specified by the 'attr' parameter and
 611  * the chosen autorelease frequency.
 612  */
 613 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 614 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 615 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
 616 dispatch_queue_attr_t
 617 dispatch_queue_attr_make_with_autorelease_frequency(
 618                 dispatch_queue_attr_t _Nullable attr,
 619                 dispatch_autorelease_frequency_t frequency);
 620
 621 /*!
 622  * @function dispatch_queue_attr_make_with_qos_class
 623  *
 624  * @abstract
 625  * Returns an attribute value which may be provided to dispatch_queue_create()
 626  * or dispatch_queue_create_with_target(), in order to assign a QOS class and
 627  * relative priority to the queue.
 628  *
 629  * @discussion
 630  * When specified in this manner, the QOS class and relative priority take
 631  * precedence over those inherited from the dispatch queue's target queue (if
 632  * any) as long that does not result in a lower QOS class and relative priority.
 633  *
 634  * The global queue priorities map to the following QOS classes:
 635  *  - DISPATCH_QUEUE_PRIORITY_HIGH:         QOS_CLASS_USER_INITIATED
 636  *  - DISPATCH_QUEUE_PRIORITY_DEFAULT:      QOS_CLASS_DEFAULT
 637  *  - DISPATCH_QUEUE_PRIORITY_LOW:          QOS_CLASS_UTILITY
 638  *  - DISPATCH_QUEUE_PRIORITY_BACKGROUND:   QOS_CLASS_BACKGROUND
 639  *
 640  * Example:
 641  * <code>
 642  *      dispatch_queue_t queue;
 643  *      dispatch_queue_attr_t attr;
 644  *      attr = dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL,
 645  *                      QOS_CLASS_UTILITY, 0);
 646  *      queue = dispatch_queue_create("com.example.myqueue", attr);
 647  * </code>
 648  *
 649  * @param attr
 650  * A queue attribute value to be combined with the QOS class, or NULL.
 651  *
 652  * @param qos_class
 653  * A QOS class value:
 654  *  - QOS_CLASS_USER_INTERACTIVE
 655  *  - QOS_CLASS_USER_INITIATED
 656  *  - QOS_CLASS_DEFAULT
 657  *  - QOS_CLASS_UTILITY
 658  *  - QOS_CLASS_BACKGROUND
 659  * Passing any other value results in NULL being returned.
 660  *
 661  * @param relative_priority
 662  * A relative priority within the QOS class. This value is a negative
 663  * offset from the maximum supported scheduler priority for the given class.
 664  * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY
 665  * results in NULL being returned.
 666  *
 667  * @return
 668  * Returns an attribute value which may be provided to dispatch_queue_create()
 669  * and dispatch_queue_create_with_target(), or NULL if an invalid QOS class was
 670  * requested.
 671  * The new value combines the attributes specified by the 'attr' parameter and
 672  * the new QOS class and relative priority.
 673  */
 674 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 675 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
 676 dispatch_queue_attr_t
 677 dispatch_queue_attr_make_with_qos_class(dispatch_queue_attr_t _Nullable attr,
 678                 dispatch_qos_class_t qos_class, int relative_priority);
 679
 680 /*!
 681  * @const DISPATCH_TARGET_QUEUE_DEFAULT
 682  * @discussion Constant to pass to the dispatch_queue_create_with_target(),
 683  * dispatch_set_target_queue() and dispatch_source_create() functions to
 684  * indicate that the default target queue for the object type in question
 685  * should be used.
 686  */
 687 #define DISPATCH_TARGET_QUEUE_DEFAULT NULL
 688
 689 /*!
 690  * @function dispatch_queue_create_with_target
 691  *
 692  * @abstract
 693  * Creates a new dispatch queue with a specified target queue.
 694  *
 695  * @discussion
 696  * Dispatch queues created with the DISPATCH_QUEUE_SERIAL or a NULL attribute
 697  * invoke blocks serially in FIFO order.
 698  *
 699  * Dispatch queues created with the DISPATCH_QUEUE_CONCURRENT attribute may
 700  * invoke blocks concurrently (similarly to the global concurrent queues, but
 701  * potentially with more overhead), and support barrier blocks submitted with
 702  * the dispatch barrier API, which e.g. enables the implementation of efficient
 703  * reader-writer schemes.
 704  *
 705  * When a dispatch queue is no longer needed, it should be released with
 706  * dispatch_release(). Note that any pending blocks submitted to a queue will
 707  * hold a reference to that queue. Therefore a queue will not be deallocated
 708  * until all pending blocks have finished.
 709  *
 710  * When using a dispatch queue attribute @a attr specifying a QoS class (derived
 711  * from the result of dispatch_queue_attr_make_with_qos_class()), passing the
 712  * result of dispatch_get_global_queue() in @a target will ignore the QoS class
 713  * of that global queue and will use the global queue with the QoS class
 714  * specified by attr instead.
 715  *
 716  * Queues created with dispatch_queue_create_with_target() cannot have their
 717  * target queue changed, unless created inactive (See
 718  * dispatch_queue_attr_make_initially_inactive()), in which case the target
 719  * queue can be changed until the newly created queue is activated with
 720  * dispatch_activate().
 721  *
 722  * @param label
 723  * A string label to attach to the queue.
 724  * This parameter is optional and may be NULL.
 725  *
 726  * @param attr
 727  * A predefined attribute such as DISPATCH_QUEUE_SERIAL,
 728  * DISPATCH_QUEUE_CONCURRENT, or the result of a call to
 729  * a dispatch_queue_attr_make_with_* function.
 730  *
 731  * @param target
 732  * The target queue for the newly created queue. The target queue is retained.
 733  * If this parameter is DISPATCH_TARGET_QUEUE_DEFAULT, sets the queue's target
 734  * queue to the default target queue for the given queue type.
 735  *
 736  * @result
 737  * The newly created dispatch queue.
 738  */
 739 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 740 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 741 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 742 DISPATCH_NOTHROW
 743 dispatch_queue_t
 744 dispatch_queue_create_with_target(const char *_Nullable label,
 745         dispatch_queue_attr_t _Nullable attr, dispatch_queue_t _Nullable target)
 746         DISPATCH_ALIAS_V2(dispatch_queue_create_with_target);
 747
 748 /*!
 749  * @function dispatch_queue_create
 750  *
 751  * @abstract
 752  * Creates a new dispatch queue to which blocks may be submitted.
 753  *
 754  * @discussion
 755  * Dispatch queues created with the DISPATCH_QUEUE_SERIAL or a NULL attribute
 756  * invoke blocks serially in FIFO order.
 757  *
 758  * Dispatch queues created with the DISPATCH_QUEUE_CONCURRENT attribute may
 759  * invoke blocks concurrently (similarly to the global concurrent queues, but
 760  * potentially with more overhead), and support barrier blocks submitted with
 761  * the dispatch barrier API, which e.g. enables the implementation of efficient
 762  * reader-writer schemes.
 763  *
 764  * When a dispatch queue is no longer needed, it should be released with
 765  * dispatch_release(). Note that any pending blocks submitted to a queue will
 766  * hold a reference to that queue. Therefore a queue will not be deallocated
 767  * until all pending blocks have finished.
 768  *
 769  * Passing the result of the dispatch_queue_attr_make_with_qos_class() function
 770  * to the attr parameter of this function allows a quality of service class and
 771  * relative priority to be specified for the newly created queue.
 772  * The quality of service class so specified takes precedence over the quality
 773  * of service class of the newly created dispatch queue's target queue (if any)
 774  * as long that does not result in a lower QOS class and relative priority.
 775  *
 776  * When no quality of service class is specified, the target queue of a newly
 777  * created dispatch queue is the default priority global concurrent queue.
 778  *
 779  * @param label
 780  * A string label to attach to the queue.
 781  * This parameter is optional and may be NULL.
 782  *
 783  * @param attr
 784  * A predefined attribute such as DISPATCH_QUEUE_SERIAL,
 785  * DISPATCH_QUEUE_CONCURRENT, or the result of a call to
 786  * a dispatch_queue_attr_make_with_* function.
 787  *
 788  * @result
 789  * The newly created dispatch queue.
 790  */
 791 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 792 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 793 DISPATCH_NOTHROW
 794 dispatch_queue_t
 795 dispatch_queue_create(const char *_Nullable label,
 796                 dispatch_queue_attr_t _Nullable attr);
 797
 798 /*!
 799  * @const DISPATCH_CURRENT_QUEUE_LABEL
 800  * @discussion Constant to pass to the dispatch_queue_get_label() function to
 801  * retrieve the label of the current queue.
 802  */
 803 #define DISPATCH_CURRENT_QUEUE_LABEL NULL
 804
 805 /*!
 806  * @function dispatch_queue_get_label
 807  *
 808  * @abstract
 809  * Returns the label of the given queue, as specified when the queue was
 810  * created, or the empty string if a NULL label was specified.
 811  *
 812  * Passing DISPATCH_CURRENT_QUEUE_LABEL will return the label of the current
 813  * queue.
 814  *
 815  * @param queue
 816  * The queue to query, or DISPATCH_CURRENT_QUEUE_LABEL.
 817  *
 818  * @result
 819  * The label of the queue.
 820  */
 821 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 822 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 823 const char *
 824 dispatch_queue_get_label(dispatch_queue_t _Nullable queue);
 825
 826 /*!
 827  * @function dispatch_queue_get_qos_class
 828  *
 829  * @abstract
 830  * Returns the QOS class and relative priority of the given queue.
 831  *
 832  * @discussion
 833  * If the given queue was created with an attribute value returned from
 834  * dispatch_queue_attr_make_with_qos_class(), this function returns the QOS
 835  * class and relative priority specified at that time; for any other attribute
 836  * value it returns a QOS class of QOS_CLASS_UNSPECIFIED and a relative
 837  * priority of 0.
 838  *
 839  * If the given queue is one of the global queues, this function returns its
 840  * assigned QOS class value as documented under dispatch_get_global_queue() and
 841  * a relative priority of 0; in the case of the main queue it returns the QOS
 842  * value provided by qos_class_main() and a relative priority of 0.
 843  *
 844  * @param queue
 845  * The queue to query.
 846  *
 847  * @param relative_priority_ptr
 848  * A pointer to an int variable to be filled with the relative priority offset
 849  * within the QOS class, or NULL.
 850  *
 851  * @return
 852  * A QOS class value:
 853  *      - QOS_CLASS_USER_INTERACTIVE
 854  *      - QOS_CLASS_USER_INITIATED
 855  *      - QOS_CLASS_DEFAULT
 856  *      - QOS_CLASS_UTILITY
 857  *      - QOS_CLASS_BACKGROUND
 858  *      - QOS_CLASS_UNSPECIFIED
 859  */
 860 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 861 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 862 dispatch_qos_class_t
 863 dispatch_queue_get_qos_class(dispatch_queue_t queue,
 864                 int *_Nullable relative_priority_ptr);
 865
 866 /*!
 867  * @function dispatch_set_target_queue
 868  *
 869  * @abstract
 870  * Sets the target queue for the given object.
 871  *
 872  * @discussion
 873  * An object's target queue is responsible for processing the object.
 874  *
 875  * When no quality of service class and relative priority is specified for a
 876  * dispatch queue at the time of creation, a dispatch queue's quality of service
 877  * class is inherited from its target queue. The dispatch_get_global_queue()
 878  * function may be used to obtain a target queue of a specific quality of
 879  * service class, however the use of dispatch_queue_attr_make_with_qos_class()
 880  * is recommended instead.
 881  *
 882  * Blocks submitted to a serial queue whose target queue is another serial
 883  * queue will not be invoked concurrently with blocks submitted to the target
 884  * queue or to any other queue with that same target queue.
 885  *
 886  * The result of introducing a cycle into the hierarchy of target queues is
 887  * undefined.
 888  *
 889  * A dispatch source's target queue specifies where its event handler and
 890  * cancellation handler blocks will be submitted.
 891  *
 892  * A dispatch I/O channel's target queue specifies where where its I/O
 893  * operations are executed. If the channel's target queue's priority is set to
 894  * DISPATCH_QUEUE_PRIORITY_BACKGROUND, then the I/O operations performed by
 895  * dispatch_io_read() or dispatch_io_write() on that queue will be
 896  * throttled when there is I/O contention.
 897  *
 898  * For all other dispatch object types, the only function of the target queue
 899  * is to determine where an object's finalizer function is invoked.
 900  *
 901  * In general, changing the target queue of an object is an asynchronous
 902  * operation that doesn't take effect immediately, and doesn't affect blocks
 903  * already associated with the specified object.
 904  *
 905  * However, if an object is inactive at the time dispatch_set_target_queue() is
 906  * called, then the target queue change takes effect immediately, and will
 907  * affect blocks already associated with the specified object. After an
 908  * initially inactive object has been activated, calling
 909  * dispatch_set_target_queue() results in an assertion and the process being
 910  * terminated.
 911  *
 912  * If a dispatch queue is active and targeted by other dispatch objects,
 913  * changing its target queue results in undefined behavior.
 914  *
 915  * @param object
 916  * The object to modify.
 917  * The result of passing NULL in this parameter is undefined.
 918  *
 919  * @param queue
 920  * The new target queue for the object. The queue is retained, and the
 921  * previous target queue, if any, is released.
 922  * If queue is DISPATCH_TARGET_QUEUE_DEFAULT, set the object's target queue
 923  * to the default target queue for the given object type.
 924  */
 925 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 926 DISPATCH_EXPORT DISPATCH_NOTHROW
 927 void
 928 dispatch_set_target_queue(dispatch_object_t object,
 929                 dispatch_queue_t _Nullable queue);
 930
 931 /*!
 932  * @function dispatch_main
 933  *
 934  * @abstract
 935  * Execute blocks submitted to the main queue.
 936  *
 937  * @discussion
 938  * This function "parks" the main thread and waits for blocks to be submitted
 939  * to the main queue. This function never returns.
 940  *
 941  * Applications that call NSApplicationMain() or CFRunLoopRun() on the
 942  * main thread do not need to call dispatch_main().
 943  */
 944 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 945 DISPATCH_EXPORT DISPATCH_NOTHROW DISPATCH_NORETURN
 946 void
 947 dispatch_main(void);
 948
 949 /*!
 950  * @function dispatch_after
 951  *
 952  * @abstract
 953  * Schedule a block for execution on a given queue at a specified time.
 954  *
 955  * @discussion
 956  * Passing DISPATCH_TIME_NOW as the "when" parameter is supported, but not as
 957  * optimal as calling dispatch_async() instead. Passing DISPATCH_TIME_FOREVER
 958  * is undefined.
 959  *
 960  * @param when
 961  * A temporal milestone returned by dispatch_time() or dispatch_walltime().
 962  *
 963  * @param queue
 964  * A queue to which the given block will be submitted at the specified time.
 965  * The result of passing NULL in this parameter is undefined.
 966  *
 967  * @param block
 968  * The block of code to execute.
 969  * The result of passing NULL in this parameter is undefined.
 970  */
 971 #ifdef __BLOCKS__
 972 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 973 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 974 void
 975 dispatch_after(dispatch_time_t when,
 976         dispatch_queue_t queue,
 977         dispatch_block_t block);
 978 #endif
 979
 980 /*!
 981  * @function dispatch_after_f
 982  *
 983  * @abstract
 984  * Schedule a function for execution on a given queue at a specified time.
 985  *
 986  * @discussion
 987  * See dispatch_after() for details.
 988  *
 989  * @param when
 990  * A temporal milestone returned by dispatch_time() or dispatch_walltime().
 991  *
 992  * @param queue
 993  * A queue to which the given function will be submitted at the specified time.
 994  * The result of passing NULL in this parameter is undefined.
 995  *
 996  * @param context
 997  * The application-defined context parameter to pass to the function.
 998  *
 999  * @param work
1000  * The application-defined function to invoke on the target queue. The first
1001  * parameter passed to this function is the context provided to
1002  * dispatch_after_f().
1003  * The result of passing NULL in this parameter is undefined.
1004  */
1005 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
1006 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW
1007 void
1008 dispatch_after_f(dispatch_time_t when,
1009         dispatch_queue_t queue,
1010         void *_Nullable context,
1011         dispatch_function_t work);
1012
1013 /*!
1014  * @functiongroup Dispatch Barrier API
1015  * The dispatch barrier API is a mechanism for submitting barrier blocks to a
1016  * dispatch queue, analogous to the dispatch_async()/dispatch_sync() API.
1017  * It enables the implementation of efficient reader/writer schemes.
1018  * Barrier blocks only behave specially when submitted to queues created with
1019  * the DISPATCH_QUEUE_CONCURRENT attribute; on such a queue, a barrier block
1020  * will not run until all blocks submitted to the queue earlier have completed,
1021  * and any blocks submitted to the queue after a barrier block will not run
1022  * until the barrier block has completed.
1023  * When submitted to a a global queue or to a queue not created with the
1024  * DISPATCH_QUEUE_CONCURRENT attribute, barrier blocks behave identically to
1025  * blocks submitted with the dispatch_async()/dispatch_sync() API.
1026  */
1027
1028 /*!
1029  * @function dispatch_barrier_async
1030  *
1031  * @abstract
1032  * Submits a barrier block for asynchronous execution on a dispatch queue.
1033  *
1034  * @discussion
1035  * Submits a block to a dispatch queue like dispatch_async(), but marks that
1036  * block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues).
1037  *
1038  * See dispatch_async() for details.
1039  *
1040  * @param queue
1041  * The target dispatch queue to which the block is submitted.
1042  * The system will hold a reference on the target queue until the block
1043  * has finished.
1044  * The result of passing NULL in this parameter is undefined.
1045  *
1046  * @param block
1047  * The block to submit to the target dispatch queue. This function performs
1048  * Block_copy() and Block_release() on behalf of callers.
1049  * The result of passing NULL in this parameter is undefined.
1050  */
1051 #ifdef __BLOCKS__
1052 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
1053 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
1054 void
1055 dispatch_barrier_async(dispatch_queue_t queue, dispatch_block_t block);
1056 #endif
1057
1058 /*!
1059  * @function dispatch_barrier_async_f
1060  *
1061  * @abstract
1062  * Submits a barrier function for asynchronous execution on a dispatch queue.
1063  *
1064  * @discussion
1065  * Submits a function to a dispatch queue like dispatch_async_f(), but marks
1066  * that function as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
1067  * queues).
1068  *
1069  * See dispatch_async_f() for details.
1070  *
1071  * @param queue
1072  * The target dispatch queue to which the function is submitted.
1073  * The system will hold a reference on the target queue until the function
1074  * has returned.
1075  * The result of passing NULL in this parameter is undefined.
1076  *
1077  * @param context
1078  * The application-defined context parameter to pass to the function.
1079  *
1080  * @param work
1081  * The application-defined function to invoke on the target queue. The first
1082  * parameter passed to this function is the context provided to
1083  * dispatch_barrier_async_f().
1084  * The result of passing NULL in this parameter is undefined.
1085  */
1086 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
1087 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
1088 void
1089 dispatch_barrier_async_f(dispatch_queue_t queue,
1090         void *_Nullable context,
1091         dispatch_function_t work);
1092
1093 /*!
1094  * @function dispatch_barrier_sync
1095  *
1096  * @abstract
1097  * Submits a barrier block for synchronous execution on a dispatch queue.
1098  *
1099  * @discussion
1100  * Submits a block to a dispatch queue like dispatch_sync(), but marks that
1101  * block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues).
1102  *
1103  * See dispatch_sync() for details.
1104  *
1105  * @param queue
1106  * The target dispatch queue to which the block is submitted.
1107  * The result of passing NULL in this parameter is undefined.
1108  *
1109  * @param block
1110  * The block to be invoked on the target dispatch queue.
1111  * The result of passing NULL in this parameter is undefined.
1112  */
1113 #ifdef __BLOCKS__
1114 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
1115 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
1116 void
1117 dispatch_barrier_sync(dispatch_queue_t queue,
1118                 DISPATCH_NOESCAPE dispatch_block_t block);
1119 #endif
1120
1121 /*!
1122  * @function dispatch_barrier_sync_f
1123  *
1124  * @abstract
1125  * Submits a barrier function for synchronous execution on a dispatch queue.
1126  *
1127  * @discussion
1128  * Submits a function to a dispatch queue like dispatch_sync_f(), but marks that
1129  * fuction as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues).
1130  *
1131  * See dispatch_sync_f() for details.
1132  *
1133  * @param queue
1134  * The target dispatch queue to which the function is submitted.
1135  * The result of passing NULL in this parameter is undefined.
1136  *
1137  * @param context
1138  * The application-defined context parameter to pass to the function.
1139  *
1140  * @param work
1141  * The application-defined function to invoke on the target queue. The first
1142  * parameter passed to this function is the context provided to
1143  * dispatch_barrier_sync_f().
1144  * The result of passing NULL in this parameter is undefined.
1145  */
1146 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
1147 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
1148 void
1149 dispatch_barrier_sync_f(dispatch_queue_t queue,
1150         void *_Nullable context,
1151         dispatch_function_t work);
1152
1153 /*!
1154  * @functiongroup Dispatch queue-specific contexts
1155  * This API allows different subsystems to associate context to a shared queue
1156  * without risk of collision and to retrieve that context from blocks executing
1157  * on that queue or any of its child queues in the target queue hierarchy.
1158  */
1159
1160 /*!
1161  * @function dispatch_queue_set_specific
1162  *
1163  * @abstract
1164  * Associates a subsystem-specific context with a dispatch queue, for a key
1165  * unique to the subsystem.
1166  *
1167  * @discussion
1168  * The specified destructor will be invoked with the context on the default
1169  * priority global concurrent queue when a new context is set for the same key,
1170  * or after all references to the queue have been released.
1171  *
1172  * @param queue
1173  * The dispatch queue to modify.
1174  * The result of passing NULL in this parameter is undefined.
1175  *
1176  * @param key
1177  * The key to set the context for, typically a pointer to a static variable
1178  * specific to the subsystem. Keys are only compared as pointers and never
1179  * dereferenced. Passing a string constant directly is not recommended.
1180  * The NULL key is reserved and attempts to set a context for it are ignored.
1181  *
1182  * @param context
1183  * The new subsystem-specific context for the object. This may be NULL.
1184  *
1185  * @param destructor
1186  * The destructor function pointer. This may be NULL and is ignored if context
1187  * is NULL.
1188  */
1189 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
1190 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
1191 void
1192 dispatch_queue_set_specific(dispatch_queue_t queue, const void *key,
1193         void *_Nullable context, dispatch_function_t _Nullable destructor);
1194
1195 /*!
1196  * @function dispatch_queue_get_specific
1197  *
1198  * @abstract
1199  * Returns the subsystem-specific context associated with a dispatch queue, for
1200  * a key unique to the subsystem.
1201  *
1202  * @discussion
1203  * Returns the context for the specified key if it has been set on the specified
1204  * queue.
1205  *
1206  * @param queue
1207  * The dispatch queue to query.
1208  * The result of passing NULL in this parameter is undefined.
1209  *
1210  * @param key
1211  * The key to get the context for, typically a pointer to a static variable
1212  * specific to the subsystem. Keys are only compared as pointers and never
1213  * dereferenced. Passing a string constant directly is not recommended.
1214  *
1215  * @result
1216  * The context for the specified key or NULL if no context was found.
1217  */
1218 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
1219 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_PURE DISPATCH_WARN_RESULT
1220 DISPATCH_NOTHROW
1221 void *_Nullable
1222 dispatch_queue_get_specific(dispatch_queue_t queue, const void *key);
1223
1224 /*!
1225  * @function dispatch_get_specific
1226  *
1227  * @abstract
1228  * Returns the current subsystem-specific context for a key unique to the
1229  * subsystem.
1230  *
1231  * @discussion
1232  * When called from a block executing on a queue, returns the context for the
1233  * specified key if it has been set on the queue, otherwise returns the result
1234  * of dispatch_get_specific() executed on the queue's target queue or NULL
1235  * if the current queue is a global concurrent queue.
1236  *
1237  * @param key
1238  * The key to get the context for, typically a pointer to a static variable
1239  * specific to the subsystem. Keys are only compared as pointers and never
1240  * dereferenced. Passing a string constant directly is not recommended.
1241  *
1242  * @result
1243  * The context for the specified key or NULL if no context was found.
1244  */
1245 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
1246 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
1247 void *_Nullable
1248 dispatch_get_specific(const void *key);
1249
1250 /*!
1251  * @functiongroup Dispatch assertion API
1252  *
1253  * This API asserts at runtime that code is executing in (or out of) the context
1254  * of a given queue. It can be used to check that a block accessing a resource
1255  * does so from the proper queue protecting the resource. It also can be used
1256  * to verify that a block that could cause a deadlock if run on a given queue
1257  * never executes on that queue.
1258  */
1259
1260 /*!
1261  * @function dispatch_assert_queue
1262  *
1263  * @abstract
1264  * Verifies that the current block is executing on a given dispatch queue.
1265  *
1266  * @discussion
1267  * Some code expects to be run on a specific dispatch queue. This function
1268  * verifies that that expectation is true.
1269  *
1270  * If the currently executing block was submitted to the specified queue or to
1271  * any queue targeting it (see dispatch_set_target_queue()), this function
1272  * returns.
1273  *
1274  * If the currently executing block was submitted with a synchronous API
1275  * (dispatch_sync(), dispatch_barrier_sync(), ...), the context of the
1276  * submitting block is also evaluated (recursively).
1277  * If a synchronously submitting block is found that was itself submitted to
1278  * the specified queue or to any queue targeting it, this function returns.
1279  *
1280  * Otherwise this function asserts: it logs an explanation to the system log and
1281  * terminates the application.
1282  *
1283  * Passing the result of dispatch_get_main_queue() to this function verifies
1284  * that the current block was submitted to the main queue, or to a queue
1285  * targeting it, or is running on the main thread (in any context).
1286  *
1287  * When dispatch_assert_queue() is called outside of the context of a
1288  * submitted block (for example from the context of a thread created manually
1289  * with pthread_create()) then this function will also assert and terminate
1290  * the application.
1291  *
1292  * The variant dispatch_assert_queue_debug() is compiled out when the
1293  * preprocessor macro NDEBUG is defined. (See also assert(3)).
1294  *
1295  * @param queue
1296  * The dispatch queue that the current block is expected to run on.
1297  * The result of passing NULL in this parameter is undefined.
1298  */
1299 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
1300 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
1301 DISPATCH_EXPORT DISPATCH_NONNULL1
1302 void
1303 dispatch_assert_queue(dispatch_queue_t queue)
1304         DISPATCH_ALIAS_V2(dispatch_assert_queue);
1305
1306 /*!
1307  * @function dispatch_assert_queue_barrier
1308  *
1309  * @abstract
1310  * Verifies that the current block is executing on a given dispatch queue,
1311  * and that the block acts as a barrier on that queue.
1312  *
1313  * @discussion
1314  * This behaves exactly like dispatch_assert_queue(), with the additional check
1315  * that the current block acts as a barrier on the specified queue, which is
1316  * always true if the specified queue is serial (see DISPATCH_BLOCK_BARRIER or
1317  * dispatch_barrier_async() for details).
1318  *
1319  * The variant dispatch_assert_queue_barrier_debug() is compiled out when the
1320  * preprocessor macro NDEBUG is defined. (See also assert()).
1321  *
1322  * @param queue
1323  * The dispatch queue that the current block is expected to run as a barrier on.
1324  * The result of passing NULL in this parameter is undefined.
1325  */
1326 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
1327 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
1328 DISPATCH_EXPORT DISPATCH_NONNULL1
1329 void
1330 dispatch_assert_queue_barrier(dispatch_queue_t queue);
1331
1332 /*!
1333  * @function dispatch_assert_queue_not
1334  *
1335  * @abstract
1336  * Verifies that the current block is not executing on a given dispatch queue.
1337  *
1338  * @discussion
1339  * This function is the equivalent of dispatch_queue_assert() with the test for
1340  * equality inverted. That means that it will terminate the application when
1341  * dispatch_queue_assert() would return, and vice-versa. See discussion there.
1342  *
1343  * The variant dispatch_assert_queue_not_debug() is compiled out when the
1344  * preprocessor macro NDEBUG is defined. (See also assert(3)).
1345  *
1346  * @param queue
1347  * The dispatch queue that the current block is expected not to run on.
1348  * The result of passing NULL in this parameter is undefined.
1349  */
1350 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
1351 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
1352 DISPATCH_EXPORT DISPATCH_NONNULL1
1353 void
1354 dispatch_assert_queue_not(dispatch_queue_t queue)
1355         DISPATCH_ALIAS_V2(dispatch_assert_queue_not);
1356
1357 #ifdef NDEBUG
1358 #define dispatch_assert_queue_debug(q) ((void)(0 && (q)))
1359 #define dispatch_assert_queue_barrier_debug(q) ((void)(0 && (q)))
1360 #define dispatch_assert_queue_not_debug(q) ((void)(0 && (q)))
1361 #else
1362 #define dispatch_assert_queue_debug(q) dispatch_assert_queue(q)
1363 #define dispatch_assert_queue_barrier_debug(q) dispatch_assert_queue_barrier(q)
1364 #define dispatch_assert_queue_not_debug(q) dispatch_assert_queue_not(q)
1365 #endif
1366
1367 __END_DECLS
1368
1369 DISPATCH_ASSUME_NONNULL_END
1370
1371 #endif