zig

queue.h (68139B) - Raw

---

 /*
  * Copyright (c) 2008-2014 Apple Inc. All rights reserved.
  *
  * @APPLE_APACHE_LICENSE_HEADER_START@
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
  * @APPLE_APACHE_LICENSE_HEADER_END@
  */
 
 #ifndef __DISPATCH_QUEUE__
 #define __DISPATCH_QUEUE__
 
 #ifndef __DISPATCH_INDIRECT__
 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
 #include <dispatch/base.h> // for HeaderDoc
 #endif
 
 DISPATCH_ASSUME_NONNULL_BEGIN
 DISPATCH_ASSUME_ABI_SINGLE_BEGIN
 
 /*!
  * @header
  *
  * Dispatch is an abstract model for expressing concurrency via simple but
  * powerful API.
  *
  * At the core, dispatch provides serial FIFO queues to which blocks may be
  * submitted. Blocks submitted to these dispatch queues are invoked on a pool
  * of threads fully managed by the system. No guarantee is made regarding
  * which thread a block will be invoked on; however, it is guaranteed that only
  * one block submitted to the FIFO dispatch queue will be invoked at a time.
  *
  * When multiple queues have blocks to be processed, the system is free to
  * allocate additional threads to invoke the blocks concurrently. When the
  * queues become empty, these threads are automatically released.
  */
 
 /*!
  * @typedef dispatch_queue_t
  *
  * @abstract
  * Dispatch queues invoke workitems submitted to them.
  *
  * @discussion
  * Dispatch queues come in many flavors, the most common one being the dispatch
  * serial queue (See dispatch_queue_serial_t).
  *
  * The system manages a pool of threads which process dispatch queues and invoke
  * workitems submitted to them.
  *
  * Conceptually a dispatch queue may have its own thread of execution, and
  * interaction between queues is highly asynchronous.
  *
  * Dispatch queues are reference counted via calls to dispatch_retain() and
  * dispatch_release(). Pending workitems submitted to a queue also hold a
  * reference to the queue until they have finished. Once all references to a
  * queue have been released, the queue will be deallocated by the system.
  */
 DISPATCH_DECL_FACTORY_CLASS_SWIFT(dispatch_queue, DispatchQueue);
 
 /*!
  * @typedef dispatch_queue_global_t
  *
  * @abstract
  * Dispatch global concurrent queues are an abstraction around the system thread
  * pool which invokes workitems that are submitted to dispatch queues.
  *
  * @discussion
  * Dispatch global concurrent queues provide buckets of priorities on top of the
  * thread pool the system manages. The system will decide how many threads
  * to allocate to this pool depending on demand and system load. In particular,
  * the system tries to maintain a good level of concurrency for this resource,
  * and will create new threads when too many existing worker threads block in
  * system calls.
  *
  * The global concurrent queues are a shared resource and as such it is the
  * responsiblity of every user of this resource to not submit an unbounded
  * amount of work to this pool, especially work that may block, as this can
  * cause the system to spawn very large numbers of threads (aka. thread
  * explosion).
  *
  * Work items submitted to the global concurrent queues have no ordering
  * guarantee with respect to the order of submission, and workitems submitted
  * to these queues may be invoked concurrently.
  *
  * Dispatch global concurrent queues are well-known global objects that are
  * returned by dispatch_get_global_queue(). These objects cannot be modified.
  * Calls to dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc.,
  * will have no effect when used with queues of this type.
  */
 DISPATCH_DECL_SUBCLASS(dispatch_queue_global, dispatch_queue);
 
 /*!
  * @typedef dispatch_queue_serial_executor_t
  *
  * @abstract
  * An abstract class of dispatch queues which conform to the serial executor
  * protocol.
  *
  * @discussion
  * A serial executor in Swift Concurrency represents a mutual exclusion context.
  * Queues with a singular owner, which invoke only one workItem at a time
  * provide such a mutual exclusion context and are serial executors.
  *
  * Subclasses of this abstract class can be therefore be setup as Custom
  * Executors for Swift Actors.
  *
  * See dispatch_queue_serial_t and dispatch_workloop_t.
  */
 API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), watchos(10.0))
 DISPATCH_DECL_SUBCLASS_SWIFT(dispatch_queue_serial_executor, dispatch_queue, _DispatchSerialExecutorQueue);
 
 /*!
  * @typedef dispatch_queue_serial_t
  *
  * @abstract
  * Dispatch serial queues invoke workitems submitted to them serially in FIFO
  * order.
  *
  * @discussion
  * Dispatch serial queues are lightweight objects to which workitems may be
  * submitted to be invoked in FIFO order. A serial queue will only invoke one
  * workitem at a time, but independent serial queues may each invoke their work
  * items concurrently with respect to each other.
  *
  * Serial queues can target each other (See dispatch_set_target_queue()). The
  * serial queue at the bottom of a queue hierarchy provides an exclusion
  * context: at most one workitem submitted to any of the queues in such
  * a hiearchy will run at any given time.
  *
  * Such hierarchies provide a natural construct to organize an application
  * subsystem around.
  *
  * Serial queues are created by passing a dispatch queue attribute derived from
  * DISPATCH_QUEUE_SERIAL to dispatch_queue_create_with_target().
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_DECL_SERIAL_EXECUTOR_SWIFT(dispatch_queue_serial, DispatchSerialQueue);
 
 /*!
  * @typedef dispatch_queue_main_t
  *
  * @abstract
  * The type of the default queue that is bound to the main thread.
  *
  * @discussion
  * The main queue is a serial queue (See dispatch_queue_serial_t) which is bound
  * to the main thread of an application.
  *
  * In order to invoke workitems submitted to the main queue, the application
  * must call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the
  * main thread.
  *
  * The main queue is a well known global object that is made automatically on
  * behalf of the main thread during process initialization and is returned by
  * dispatch_get_main_queue(). This object cannot be modified.  Calls to
  * dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc., will
  * have no effect when used on the main queue.
  */
 DISPATCH_DECL_SUBCLASS(dispatch_queue_main, dispatch_queue_serial);
 
 /*!
  * @typedef dispatch_queue_concurrent_t
  *
  * @abstract
  * Dispatch concurrent queues invoke workitems submitted to them concurrently,
  * and admit a notion of barrier workitems.
  *
  * @discussion
  * Dispatch concurrent queues are lightweight objects to which regular and
  * barrier workitems may be submited. Barrier workitems are invoked in
  * exclusion of any other kind of workitem in FIFO order.
  *
  * Regular workitems can be invoked concurrently for the same concurrent queue,
  * in any order. However, regular workitems will not be invoked before any
  * barrier workitem submited ahead of them has been invoked.
  *
  * In other words, if a serial queue is equivalent to a mutex in the Dispatch
  * world, a concurrent queue is equivalent to a reader-writer lock, where
  * regular items are readers and barriers are writers.
  *
  * Concurrent queues are created by passing a dispatch queue attribute derived
  * from DISPATCH_QUEUE_CONCURRENT to dispatch_queue_create_with_target().
  *
  * Caveat:
  * Dispatch concurrent queues at this time do not implement priority inversion
  * avoidance when lower priority regular workitems (readers) are being invoked
  * and are preventing a higher priority barrier (writer) from being invoked.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_DECL_SUBCLASS_SWIFT(dispatch_queue_concurrent, dispatch_queue, DispatchConcurrentQueue);
 
 __BEGIN_DECLS
 
 /*!
  * @function dispatch_async
  *
  * @abstract
  * Submits a block for asynchronous execution on a dispatch queue.
  *
  * @discussion
  * The dispatch_async() function is the fundamental mechanism for submitting
  * blocks to a dispatch queue.
  *
  * Calls to dispatch_async() always return immediately after the block has
  * been submitted, and never wait for the block to be invoked.
  *
  * The target queue determines whether the block will be invoked serially or
  * concurrently with respect to other blocks submitted to that same queue.
  * Serial queues are processed concurrently with respect to each other.
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The system will hold a reference on the target queue until the block
  * has finished.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param block
  * The block to submit to the target dispatch queue. This function performs
  * Block_copy() and Block_release() on behalf of callers.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_async(dispatch_queue_t queue, dispatch_block_t block);
 #endif
 
 /*!
  * @function dispatch_async_f
  *
  * @abstract
  * Submits a function for asynchronous execution on a dispatch queue.
  *
  * @discussion
  * See dispatch_async() for details.
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The system will hold a reference on the target queue until the function
  * has returned.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_async_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.async(self:execute:)")
 void
 dispatch_async_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);
 
 /*!
  * @function dispatch_sync
  *
  * @abstract
  * Submits a block for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a workitem to a dispatch queue like dispatch_async(), however
  * dispatch_sync() will not return until the workitem has finished.
  *
  * Work items submitted to a queue with dispatch_sync() do not observe certain
  * queue attributes of that queue when invoked (such as autorelease frequency
  * and QOS class).
  *
  * Calls to dispatch_sync() targeting the current queue will result
  * in dead-lock. Use of dispatch_sync() is also subject to the same
  * multi-party dead-lock problems that may result from the use of a mutex.
  * Use of dispatch_async() is preferred.
  *
  * Unlike dispatch_async(), no retain is performed on the target queue. Because
  * calls to this function are synchronous, the dispatch_sync() "borrows" the
  * reference of the caller.
  *
  * As an optimization, dispatch_sync() invokes the workitem on the thread which
  * submitted the workitem, except when the passed queue is the main queue or
  * a queue targetting it (See dispatch_queue_main_t,
  * dispatch_set_target_queue()).
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param block
  * The block to be invoked on the target dispatch queue.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 DISPATCH_SWIFT_NAME(DispatchQueue.sync(self:execute:))
 void
 dispatch_sync(dispatch_queue_t queue, DISPATCH_NOESCAPE dispatch_block_t block);
 #endif
 
 /*!
  * @function dispatch_sync_f
  *
  * @abstract
  * Submits a function for synchronous execution on a dispatch queue.
  *
  * @discussion
  * See dispatch_sync() for details.
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_sync_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.sync(self:execute:)")
 void
 dispatch_sync_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);
 
 /*!
  * @function dispatch_async_and_wait
  *
  * @abstract
  * Submits a block for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a workitem to a dispatch queue like dispatch_async(), however
  * dispatch_async_and_wait() will not return until the workitem has finished.
  *
  * Like functions of the dispatch_sync family, dispatch_async_and_wait() is
  * subject to dead-lock (See dispatch_sync() for details).
  *
  * However, dispatch_async_and_wait() differs from functions of the
  * dispatch_sync family in two fundamental ways: how it respects queue
  * attributes and how it chooses the execution context invoking the workitem.
  *
  * <b>Differences with dispatch_sync()</b>
  *
  * Work items submitted to a queue with dispatch_async_and_wait() observe all
  * queue attributes of that queue when invoked (including autorelease frequency
  * or QOS class).
  *
  * When the runtime has brought up a thread to invoke the asynchronous workitems
  * already submitted to the specified queue, that servicing thread will also be
  * used to execute synchronous work submitted to the queue with
  * dispatch_async_and_wait().
  *
  * However, if the runtime has not brought up a thread to service the specified
  * queue (because it has no workitems enqueued, or only synchronous workitems),
  * then dispatch_async_and_wait() will invoke the workitem on the calling thread,
  * similar to the behaviour of functions in the dispatch_sync family.
  *
  * As an exception, if the queue the work is submitted to doesn't target
  * a global concurrent queue (for example because it targets the main queue),
  * then the workitem will never be invoked by the thread calling
  * dispatch_async_and_wait().
  *
  * In other words, dispatch_async_and_wait() is similar to submitting
  * a dispatch_block_create()d workitem to a queue and then waiting on it, as
  * shown in the code example below. However, dispatch_async_and_wait() is
  * significantly more efficient when a new thread is not required to execute
  * the workitem (as it will use the stack of the submitting thread instead of
  * requiring heap allocations).
  *
  * <code>
  *     dispatch_block_t b = dispatch_block_create(0, block);
  *     dispatch_async(queue, b);
  *     dispatch_block_wait(b, DISPATCH_TIME_FOREVER);
  *     Block_release(b);
  * </code>
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param block
  * The block to be invoked on the target dispatch queue.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 DISPATCH_SWIFT_NAME(DispatchQueue.asyncAndWait(self:execute:))
 void
 dispatch_async_and_wait(dispatch_queue_t queue,
 		DISPATCH_NOESCAPE dispatch_block_t block);
 #endif
 
 /*!
  * @function dispatch_async_and_wait_f
  *
  * @abstract
  * Submits a function for synchronous execution on a dispatch queue.
  *
  * @discussion
  * See dispatch_async_and_wait() for details.
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_async_and_wait_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.asyncAndWait(self:execute:)")
 void
 dispatch_async_and_wait_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);
 
 
 #if defined(__APPLE__) && \
 		(defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && \
 		__IPHONE_OS_VERSION_MIN_REQUIRED < __IPHONE_7_0) || \
 		(defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && \
 		__MAC_OS_X_VERSION_MIN_REQUIRED < __MAC_10_9)
 #define DISPATCH_APPLY_AUTO_AVAILABLE 0
 #define DISPATCH_APPLY_QUEUE_ARG_NULLABILITY _Nonnull
 #else
 #define DISPATCH_APPLY_AUTO_AVAILABLE 1
 #define DISPATCH_APPLY_QUEUE_ARG_NULLABILITY _Nullable
 #endif
 
 /*!
  * @constant DISPATCH_APPLY_AUTO
  *
  * @abstract
  * Constant to pass to dispatch_apply() or dispatch_apply_f() to request that
  * the system automatically use worker threads that match the configuration of
  * the current thread as closely as possible.
  *
  * @discussion
  * When submitting a block for parallel invocation, passing this constant as the
  * queue argument will automatically use the global concurrent queue that
  * matches the Quality of Service of the caller most closely.
  *
  * No assumptions should be made about which global concurrent queue will
  * actually be used.
  *
  * Using this constant deploys backward to macOS 10.9, iOS 7.0 and any tvOS or
  * watchOS version.
  */
 #if DISPATCH_APPLY_AUTO_AVAILABLE
 #define DISPATCH_APPLY_AUTO ((dispatch_queue_t _Nonnull)0)
 #endif
 
 /*!
  * @function dispatch_apply
  *
  * @abstract
  * Submits a block to a dispatch queue for parallel invocation.
  *
  * @discussion
  * Submits a block to a dispatch queue for parallel invocation. This function
  * waits for the task block to complete before returning. If the specified queue
  * is concurrent, the block may be invoked concurrently, and it must therefore
  * be reentrant safe.
  *
  * Each invocation of the block will be passed the current index of iteration.
  *
  * @param iterations
  * The number of iterations to perform.
  *
  * @param queue
  * The dispatch queue to which the block is submitted.
  * The preferred value to pass is DISPATCH_APPLY_AUTO to automatically use
  * a queue appropriate for the calling thread.
  *
  * @param block
  * The block to be invoked the specified number of iterations.
  * The result of passing NULL in this parameter is undefined.
  * This function performs a Block_copy() and Block_release() of the input block
  * on behalf of the callers. To elide the additional block allocation,
  * dispatch_apply_f may be used instead.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_apply(size_t iterations,
 		dispatch_queue_t DISPATCH_APPLY_QUEUE_ARG_NULLABILITY queue,
 		DISPATCH_NOESCAPE void (^block)(size_t iteration));
 #endif
 
 /*!
  * @function dispatch_apply_f
  *
  * @abstract
  * Submits a function to a dispatch queue for parallel invocation.
  *
  * @discussion
  * See dispatch_apply() for details.
  *
  * @param iterations
  * The number of iterations to perform.
  *
  * @param queue
  * The dispatch queue to which the function is submitted.
  * The preferred value to pass is DISPATCH_APPLY_AUTO to automatically use
  * a queue appropriate for the calling thread.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the specified queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_apply_f(). The second parameter passed to this function is the
  * current index of iteration.
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL4 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.concurrentPerform(iterations:execute:).")
 void
 dispatch_apply_f(size_t iterations,
 		dispatch_queue_t DISPATCH_APPLY_QUEUE_ARG_NULLABILITY queue,
 		void *_Nullable context, void (*work)(void *_Nullable context, size_t iteration));
 
 /*!
  * @function dispatch_get_current_queue
  *
  * @abstract
  * Returns the queue on which the currently executing block is running.
  *
  * @discussion
  * Returns the queue on which the currently executing block is running.
  *
  * When dispatch_get_current_queue() is called outside of the context of a
  * submitted block, it will return the default concurrent queue.
  *
  * Recommended for debugging and logging purposes only:
  * The code must not make any assumptions about the queue returned, unless it
  * is one of the global queues or a queue the code has itself created.
  * The code must not assume that synchronous execution onto a queue is safe
  * from deadlock if that queue is not the one returned by
  * dispatch_get_current_queue().
  *
  * When dispatch_get_current_queue() is called on the main thread, it may
  * or may not return the same value as dispatch_get_main_queue(). Comparing
  * the two is not a valid way to test whether code is executing on the
  * main thread (see dispatch_assert_queue() and dispatch_assert_queue_not()).
  *
  * This function is deprecated and will be removed in a future release.
  *
  * @result
  * Returns the current queue.
  */
 API_DEPRECATED("unsupported interface", macos(10.6,10.9), ios(4.0,6.0))
 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 dispatch_queue_t
 dispatch_get_current_queue(void);
 
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT
 struct dispatch_queue_s _dispatch_main_q;
 
 /*!
  * @function dispatch_get_main_queue
  *
  * @abstract
  * Returns the default queue that is bound to the main thread.
  *
  * @discussion
  * In order to invoke blocks submitted to the main queue, the application must
  * call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the main
  * thread.
  *
  * The main queue is meant to be used in application context to interact with
  * the main thread and the main runloop.
  *
  * Because the main queue doesn't behave entirely like a regular serial queue,
  * it may have unwanted side-effects when used in processes that are not UI apps
  * (daemons). For such processes, the main queue should be avoided.
  *
  * @see dispatch_queue_main_t
  *
  * @result
  * Returns the main queue. This queue is created automatically on behalf of
  * the main thread before main() is called.
  */
 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_CONST DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use getter:DispatchQueue.main()")
 dispatch_queue_main_t
 dispatch_get_main_queue(void)
 {
 	return DISPATCH_GLOBAL_OBJECT(dispatch_queue_main_t, _dispatch_main_q);
 }
 
 /*!
  * @typedef dispatch_queue_priority_t
  * Type of dispatch_queue_priority
  *
  * @constant DISPATCH_QUEUE_PRIORITY_HIGH
  * Items dispatched to the queue will run at high priority,
  * i.e. the queue will be scheduled for execution before
  * any default priority or low priority queue.
  *
  * @constant DISPATCH_QUEUE_PRIORITY_DEFAULT
  * Items dispatched to the queue will run at the default
  * priority, i.e. the queue will be scheduled for execution
  * after all high priority queues have been scheduled, but
  * before any low priority queues have been scheduled.
  *
  * @constant DISPATCH_QUEUE_PRIORITY_LOW
  * Items dispatched to the queue will run at low priority,
  * i.e. the queue will be scheduled for execution after all
  * default priority and high priority queues have been
  * scheduled.
  *
  * @constant DISPATCH_QUEUE_PRIORITY_BACKGROUND
  * Items dispatched to the queue will run at background priority, i.e. the queue
  * will be scheduled for execution after all higher priority queues have been
  * scheduled and the system will run items on this queue on a thread with
  * background status as per setpriority(2) (i.e. disk I/O is throttled and the
  * thread's scheduling priority is set to lowest value).
  */
 #define DISPATCH_QUEUE_PRIORITY_HIGH 2
 #define DISPATCH_QUEUE_PRIORITY_DEFAULT 0
 #define DISPATCH_QUEUE_PRIORITY_LOW (-2)
 #define DISPATCH_QUEUE_PRIORITY_BACKGROUND INT16_MIN
 
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.GlobalQueuePriority")
 typedef long dispatch_queue_priority_t;
 
 /*!
  * @function dispatch_get_global_queue
  *
  * @abstract
  * Returns a well-known global concurrent queue of a given quality of service
  * class.
  *
  * @discussion
  * See dispatch_queue_global_t.
  *
  * @param identifier
  * A quality of service class defined in qos_class_t or a priority defined in
  * dispatch_queue_priority_t.
  *
  * It is recommended to use quality of service class values to identify the
  * well-known global concurrent queues:
  *  - QOS_CLASS_USER_INTERACTIVE
  *  - QOS_CLASS_USER_INITIATED
  *  - QOS_CLASS_DEFAULT
  *  - QOS_CLASS_UTILITY
  *  - QOS_CLASS_BACKGROUND
  *
  * The global concurrent queues may still be identified by their priority,
  * which map to the following QOS classes:
  *  - DISPATCH_QUEUE_PRIORITY_HIGH:         QOS_CLASS_USER_INITIATED
  *  - DISPATCH_QUEUE_PRIORITY_DEFAULT:      QOS_CLASS_DEFAULT
  *  - DISPATCH_QUEUE_PRIORITY_LOW:          QOS_CLASS_UTILITY
  *  - DISPATCH_QUEUE_PRIORITY_BACKGROUND:   QOS_CLASS_BACKGROUND
  *
  * @param flags
  * Reserved for future use. Passing any value other than zero may result in
  * a NULL return value.
  *
  * @result
  * Returns the requested global queue or NULL if the requested global queue
  * does not exist.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_CONST DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 dispatch_queue_global_t
 dispatch_get_global_queue(intptr_t identifier, uintptr_t flags);
 
 /*!
  * @typedef dispatch_queue_attr_t
  *
  * @abstract
  * Attribute for dispatch queues.
  */
 DISPATCH_REFINED_FOR_SWIFT
 DISPATCH_DECL(dispatch_queue_attr);
 
 /*!
  * @const DISPATCH_QUEUE_SERIAL
  *
  * @discussion
  * An attribute that can be used to create a dispatch queue that invokes blocks
  * serially in FIFO order.
  *
  * See dispatch_queue_serial_t.
  */
 #define DISPATCH_QUEUE_SERIAL NULL
 
 /*!
  * @const DISPATCH_QUEUE_SERIAL_INACTIVE
  *
  * @discussion
  * An attribute that can be used to create a dispatch queue that invokes blocks
  * serially in FIFO order, and that is initially inactive.
  *
  * See dispatch_queue_attr_make_initially_inactive().
  */
 #define DISPATCH_QUEUE_SERIAL_INACTIVE \
 		dispatch_queue_attr_make_initially_inactive(DISPATCH_QUEUE_SERIAL)
 
 /*!
  * @const DISPATCH_QUEUE_CONCURRENT
  *
  * @discussion
  * An attribute that can be used to create a dispatch queue that may invoke
  * blocks concurrently and supports barrier blocks submitted with the dispatch
  * barrier API.
  *
  * See dispatch_queue_concurrent_t.
  */
 #define DISPATCH_QUEUE_CONCURRENT \
 		DISPATCH_GLOBAL_OBJECT(dispatch_queue_attr_t, \
 		_dispatch_queue_attr_concurrent)
 API_AVAILABLE(macos(10.7), ios(4.3))
 DISPATCH_EXPORT
 struct dispatch_queue_attr_s _dispatch_queue_attr_concurrent;
 
 /*!
  * @const DISPATCH_QUEUE_CONCURRENT_INACTIVE
  *
  * @discussion
  * An attribute that can be used to create a dispatch queue that may invoke
  * blocks concurrently and supports barrier blocks submitted with the dispatch
  * barrier API, and that is initially inactive.
  *
  * See dispatch_queue_attr_make_initially_inactive().
  */
 #define DISPATCH_QUEUE_CONCURRENT_INACTIVE \
 		dispatch_queue_attr_make_initially_inactive(DISPATCH_QUEUE_CONCURRENT)
 
 /*!
  * @function dispatch_queue_attr_make_initially_inactive
  *
  * @abstract
  * Returns an attribute value which may be provided to dispatch_queue_create()
  * or dispatch_queue_create_with_target(), in order to make the created queue
  * initially inactive.
  *
  * @discussion
  * Dispatch queues may be created in an inactive state. Queues in this state
  * have to be activated before any blocks associated with them will be invoked.
  *
  * A queue in inactive state cannot be deallocated, dispatch_activate() must be
  * called before the last reference to a queue created with this attribute is
  * released.
  *
  * The target queue of a queue in inactive state can be changed using
  * dispatch_set_target_queue(). Change of target queue is no longer permitted
  * once an initially inactive queue has been activated.
  *
  * @param attr
  * A queue attribute value to be combined with the initially inactive attribute.
  *
  * @return
  * Returns an attribute value which may be provided to dispatch_queue_create()
  * and dispatch_queue_create_with_target().
  * The new value combines the attributes specified by the 'attr' parameter with
  * the initially inactive attribute.
  */
 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 dispatch_queue_attr_t
 dispatch_queue_attr_make_initially_inactive(
 		dispatch_queue_attr_t _Nullable attr);
 
 /*!
  * @const DISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL
  *
  * @discussion
  * A dispatch queue created with this attribute invokes blocks serially in FIFO
  * order, and surrounds execution of any block submitted asynchronously to it
  * with the equivalent of a individual Objective-C <code>@autoreleasepool</code>
  * scope.
  *
  * See dispatch_queue_attr_make_with_autorelease_frequency().
  */
 #define DISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL \
 		dispatch_queue_attr_make_with_autorelease_frequency(\
 				DISPATCH_QUEUE_SERIAL, DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM)
 
 /*!
  * @const DISPATCH_QUEUE_CONCURRENT_WITH_AUTORELEASE_POOL
  *
  * @discussion
  * A dispatch queue created with this attribute may invokes blocks concurrently
  * and supports barrier blocks submitted with the dispatch barrier API. It also
  * surrounds execution of any block submitted asynchronously to it with the
  * equivalent of a individual Objective-C <code>@autoreleasepool</code>
  *
  * See dispatch_queue_attr_make_with_autorelease_frequency().
  */
 #define DISPATCH_QUEUE_CONCURRENT_WITH_AUTORELEASE_POOL \
 		dispatch_queue_attr_make_with_autorelease_frequency(\
 				DISPATCH_QUEUE_CONCURRENT, DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM)
 
 /*!
  * @typedef dispatch_autorelease_frequency_t
  * Values to pass to the dispatch_queue_attr_make_with_autorelease_frequency()
  * function.
  *
  * @const DISPATCH_AUTORELEASE_FREQUENCY_INHERIT
  * Dispatch queues with this autorelease frequency inherit the behavior from
  * their target queue. This is the default behavior for manually created queues.
  *
  * @const DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM
  * Dispatch queues with this autorelease frequency push and pop an autorelease
  * pool around the execution of every block that was submitted to it
  * asynchronously.
  * @see dispatch_queue_attr_make_with_autorelease_frequency().
  *
  * @const DISPATCH_AUTORELEASE_FREQUENCY_NEVER
  * Dispatch queues with this autorelease frequency never set up an individual
  * autorelease pool around the execution of a block that is submitted to it
  * asynchronously. This is the behavior of the global concurrent queues.
  */
 DISPATCH_REFINED_FOR_SWIFT
 DISPATCH_ENUM(dispatch_autorelease_frequency, unsigned long,
 	DISPATCH_AUTORELEASE_FREQUENCY_INHERIT DISPATCH_ENUM_API_AVAILABLE(
 			macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 			DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.AutoreleaseFrequency.inherit") = 0,
 	DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM DISPATCH_ENUM_API_AVAILABLE(
 			macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 			DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.AutoreleaseFrequency.workItem") = 1,
 	DISPATCH_AUTORELEASE_FREQUENCY_NEVER DISPATCH_ENUM_API_AVAILABLE(
 			macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 			DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.AutoreleaseFrequency.never") = 2,
 );
 
 /*!
  * @function dispatch_queue_attr_make_with_autorelease_frequency
  *
  * @abstract
  * Returns a dispatch queue attribute value with the autorelease frequency
  * set to the specified value.
  *
  * @discussion
  * When a queue uses the per-workitem autorelease frequency (either directly
  * or inherited from its target queue), any block submitted asynchronously to
  * this queue (via dispatch_async(), dispatch_barrier_async(),
  * dispatch_group_notify(), etc...) is executed as if surrounded by a individual
  * Objective-C <code>@autoreleasepool</code> scope.
  *
  * Autorelease frequency has no effect on blocks that are submitted
  * synchronously to a queue (via dispatch_sync(), dispatch_barrier_sync()).
  *
  * The global concurrent queues have the DISPATCH_AUTORELEASE_FREQUENCY_NEVER
  * behavior. Manually created dispatch queues use
  * DISPATCH_AUTORELEASE_FREQUENCY_INHERIT by default.
  *
  * Queues created with this attribute cannot change target queues after having
  * been activated. See dispatch_set_target_queue() and dispatch_activate().
  *
  * @param attr
  * A queue attribute value to be combined with the specified autorelease
  * frequency or NULL.
  *
  * @param frequency
  * The requested autorelease frequency.
  *
  * @return
  * Returns an attribute value which may be provided to dispatch_queue_create()
  * or NULL if an invalid autorelease frequency was requested.
  * This new value combines the attributes specified by the 'attr' parameter and
  * the chosen autorelease frequency.
  */
 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 dispatch_queue_attr_t
 dispatch_queue_attr_make_with_autorelease_frequency(
 		dispatch_queue_attr_t _Nullable attr,
 		dispatch_autorelease_frequency_t frequency);
 
 /*!
  * @function dispatch_queue_attr_make_with_qos_class
  *
  * @abstract
  * Returns an attribute value which may be provided to dispatch_queue_create()
  * or dispatch_queue_create_with_target(), in order to assign a QOS class and
  * relative priority to the queue.
  *
  * @discussion
  * When specified in this manner, the QOS class and relative priority take
  * precedence over those inherited from the dispatch queue's target queue (if
  * any) as long that does not result in a lower QOS class and relative priority.
  *
  * The global queue priorities map to the following QOS classes:
  *  - DISPATCH_QUEUE_PRIORITY_HIGH:         QOS_CLASS_USER_INITIATED
  *  - DISPATCH_QUEUE_PRIORITY_DEFAULT:      QOS_CLASS_DEFAULT
  *  - DISPATCH_QUEUE_PRIORITY_LOW:          QOS_CLASS_UTILITY
  *  - DISPATCH_QUEUE_PRIORITY_BACKGROUND:   QOS_CLASS_BACKGROUND
  *
  * Example:
  * <code>
  *	dispatch_queue_t queue;
  *	dispatch_queue_attr_t attr;
  *	attr = dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL,
  *			QOS_CLASS_UTILITY, 0);
  *	queue = dispatch_queue_create("com.example.myqueue", attr);
  * </code>
  *
  * The QOS class and relative priority set this way on a queue have no effect on
  * blocks that are submitted synchronously to a queue (via dispatch_sync(),
  * dispatch_barrier_sync()).
  *
  * @param attr
  * A queue attribute value to be combined with the QOS class, or NULL.
  *
  * @param qos_class
  * A QOS class value:
  *  - QOS_CLASS_USER_INTERACTIVE
  *  - QOS_CLASS_USER_INITIATED
  *  - QOS_CLASS_DEFAULT
  *  - QOS_CLASS_UTILITY
  *  - QOS_CLASS_BACKGROUND
  * Passing any other value results in NULL being returned.
  *
  * @param relative_priority
  * A relative priority within the QOS class. This value is a negative
  * offset from the maximum supported scheduler priority for the given class.
  * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY
  * results in NULL being returned.
  *
  * @return
  * Returns an attribute value which may be provided to dispatch_queue_create()
  * and dispatch_queue_create_with_target(), or NULL if an invalid QOS class was
  * requested.
  * The new value combines the attributes specified by the 'attr' parameter and
  * the new QOS class and relative priority.
  */
 API_AVAILABLE(macos(10.10), ios(8.0))
 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 dispatch_queue_attr_t
 dispatch_queue_attr_make_with_qos_class(dispatch_queue_attr_t _Nullable attr,
 		dispatch_qos_class_t qos_class, int relative_priority);
 
 /*!
  * @const DISPATCH_TARGET_QUEUE_DEFAULT
  * @discussion Constant to pass to the dispatch_queue_create_with_target(),
  * dispatch_set_target_queue() and dispatch_source_create() functions to
  * indicate that the default target queue for the object type in question
  * should be used.
  */
 #define DISPATCH_TARGET_QUEUE_DEFAULT NULL
 
 /*!
  * @function dispatch_queue_create_with_target
  *
  * @abstract
  * Creates a new dispatch queue with a specified target queue.
  *
  * @discussion
  * Dispatch queues created with the DISPATCH_QUEUE_SERIAL or a NULL attribute
  * invoke blocks serially in FIFO order.
  *
  * Dispatch queues created with the DISPATCH_QUEUE_CONCURRENT attribute may
  * invoke blocks concurrently (similarly to the global concurrent queues, but
  * potentially with more overhead), and support barrier blocks submitted with
  * the dispatch barrier API, which e.g. enables the implementation of efficient
  * reader-writer schemes.
  *
  * When a dispatch queue is no longer needed, it should be released with
  * dispatch_release(). Note that any pending blocks submitted asynchronously to
  * a queue will hold a reference to that queue. Therefore a queue will not be
  * deallocated until all pending blocks have finished.
  *
  * When using a dispatch queue attribute @a attr specifying a QoS class (derived
  * from the result of dispatch_queue_attr_make_with_qos_class()), passing the
  * result of dispatch_get_global_queue() in @a target will ignore the QoS class
  * of that global queue and will use the global queue with the QoS class
  * specified by attr instead.
  *
  * Queues created with dispatch_queue_create_with_target() cannot have their
  * target queue changed, unless created inactive (See
  * dispatch_queue_attr_make_initially_inactive()), in which case the target
  * queue can be changed until the newly created queue is activated with
  * dispatch_activate().
  *
  * @param label
  * A string label to attach to the queue.
  * This parameter is optional and may be NULL.
  *
  * @param attr
  * A predefined attribute such as DISPATCH_QUEUE_SERIAL,
  * DISPATCH_QUEUE_CONCURRENT, or the result of a call to
  * a dispatch_queue_attr_make_with_* function.
  *
  * @param target
  * The target queue for the newly created queue. The target queue is retained.
  * If this parameter is DISPATCH_TARGET_QUEUE_DEFAULT, sets the queue's target
  * queue to the default target queue for the given queue type.
  *
  * @result
  * The newly created dispatch queue.
  */
 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT DISPATCH_SWIFT_NAME(DispatchQueue.init(__label:attr:queue:))
 dispatch_queue_t
 dispatch_queue_create_with_target(const char *_Nullable DISPATCH_UNSAFE_INDEXABLE label,
 		dispatch_queue_attr_t _Nullable attr, dispatch_queue_t _Nullable target)
 		DISPATCH_ALIAS_V2(dispatch_queue_create_with_target);
 
 /*!
  * @function dispatch_queue_create
  *
  * @abstract
  * Creates a new dispatch queue to which blocks may be submitted.
  *
  * @discussion
  * Dispatch queues created with the DISPATCH_QUEUE_SERIAL or a NULL attribute
  * invoke blocks serially in FIFO order.
  *
  * Dispatch queues created with the DISPATCH_QUEUE_CONCURRENT attribute may
  * invoke blocks concurrently (similarly to the global concurrent queues, but
  * potentially with more overhead), and support barrier blocks submitted with
  * the dispatch barrier API, which e.g. enables the implementation of efficient
  * reader-writer schemes.
  *
  * When a dispatch queue is no longer needed, it should be released with
  * dispatch_release(). Note that any pending blocks submitted asynchronously to
  * a queue will hold a reference to that queue. Therefore a queue will not be
  * deallocated until all pending blocks have finished.
  *
  * Passing the result of the dispatch_queue_attr_make_with_qos_class() function
  * to the attr parameter of this function allows a quality of service class and
  * relative priority to be specified for the newly created queue.
  * The quality of service class so specified takes precedence over the quality
  * of service class of the newly created dispatch queue's target queue (if any)
  * as long that does not result in a lower QOS class and relative priority.
  *
  * When no quality of service class is specified, the target queue of a newly
  * created dispatch queue is the default priority global concurrent queue.
  *
  * Unless explicitly specified via the attribute, queues are created active.
  *
  * @param label
  * A string label to attach to the queue.
  * This parameter is optional and may be NULL.
  *
  * @param attr
  * A predefined attribute such as DISPATCH_QUEUE_SERIAL,
  * DISPATCH_QUEUE_CONCURRENT, or the result of a call to
  * a dispatch_queue_attr_make_with_* function.
  *
  * @result
  * The newly created dispatch queue.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT DISPATCH_SWIFT_NAME(DispatchQueue.init(__label:attr:))
 dispatch_queue_t
 dispatch_queue_create(const char *_Nullable DISPATCH_UNSAFE_INDEXABLE label,
 		dispatch_queue_attr_t _Nullable attr);
 
 /*!
  * @const DISPATCH_CURRENT_QUEUE_LABEL
  * @discussion Constant to pass to the dispatch_queue_get_label() function to
  * retrieve the label of the current queue.
  */
 #define DISPATCH_CURRENT_QUEUE_LABEL NULL
 
 /*!
  * @function dispatch_queue_get_label
  *
  * @abstract
  * Returns the label of the given queue, as specified when the queue was
  * created, or the empty string if a NULL label was specified.
  *
  * Passing DISPATCH_CURRENT_QUEUE_LABEL will return the label of the current
  * queue.
  *
  * @param queue
  * The queue to query, or DISPATCH_CURRENT_QUEUE_LABEL.
  *
  * @result
  * The label of the queue.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 const char *
 dispatch_queue_get_label(dispatch_queue_t _Nullable queue);
 
 /*!
  * @function dispatch_queue_get_qos_class
  *
  * @abstract
  * Returns the QOS class and relative priority of the given queue.
  *
  * @discussion
  * If the given queue was created with an attribute value returned from
  * dispatch_queue_attr_make_with_qos_class(), this function returns the QOS
  * class and relative priority specified at that time; for any other attribute
  * value it returns a QOS class of QOS_CLASS_UNSPECIFIED and a relative
  * priority of 0.
  *
  * If the given queue is one of the global queues, this function returns its
  * assigned QOS class value as documented under dispatch_get_global_queue() and
  * a relative priority of 0; in the case of the main queue it returns the QOS
  * value provided by qos_class_main() and a relative priority of 0.
  *
  * @param queue
  * The queue to query.
  *
  * @param relative_priority_ptr
  * A pointer to an int variable to be filled with the relative priority offset
  * within the QOS class, or NULL.
  *
  * @return
  * A QOS class value:
  *	- QOS_CLASS_USER_INTERACTIVE
  *	- QOS_CLASS_USER_INITIATED
  *	- QOS_CLASS_DEFAULT
  *	- QOS_CLASS_UTILITY
  *	- QOS_CLASS_BACKGROUND
  *	- QOS_CLASS_UNSPECIFIED
  */
 API_AVAILABLE(macos(10.10), ios(8.0))
 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 dispatch_qos_class_t
 dispatch_queue_get_qos_class(dispatch_queue_t queue,
 		int *_Nullable relative_priority_ptr);
 
 /*!
  * @function dispatch_set_target_queue
  *
  * @abstract
  * Sets the target queue for the given object.
  *
  * @discussion
  * An object's target queue is responsible for processing the object.
  *
  * When no quality of service class and relative priority is specified for a
  * dispatch queue at the time of creation, a dispatch queue's quality of service
  * class is inherited from its target queue. The dispatch_get_global_queue()
  * function may be used to obtain a target queue of a specific quality of
  * service class, however the use of dispatch_queue_attr_make_with_qos_class()
  * is recommended instead.
  *
  * Blocks submitted to a serial queue whose target queue is another serial
  * queue will not be invoked concurrently with blocks submitted to the target
  * queue or to any other queue with that same target queue.
  *
  * The result of introducing a cycle into the hierarchy of target queues is
  * undefined.
  *
  * A dispatch source's target queue specifies where its event handler and
  * cancellation handler blocks will be submitted.
  *
  * A dispatch I/O channel's target queue specifies where where its I/O
  * operations are executed. If the channel's target queue's priority is set to
  * DISPATCH_QUEUE_PRIORITY_BACKGROUND, then the I/O operations performed by
  * dispatch_io_read() or dispatch_io_write() on that queue will be
  * throttled when there is I/O contention.
  *
  * For all other dispatch object types, the only function of the target queue
  * is to determine where an object's finalizer function is invoked.
  *
  * In general, changing the target queue of an object is an asynchronous
  * operation that doesn't take effect immediately, and doesn't affect blocks
  * already associated with the specified object.
  *
  * However, if an object is inactive at the time dispatch_set_target_queue() is
  * called, then the target queue change takes effect immediately, and will
  * affect blocks already associated with the specified object. After an
  * initially inactive object has been activated, calling
  * dispatch_set_target_queue() results in an assertion and the process being
  * terminated.
  *
  * If a dispatch queue is active and targeted by other dispatch objects,
  * changing its target queue results in undefined behavior.  Instead, it is
  * recommended to create dispatch objects in an inactive state, set up the
  * relevant target queues and then activate them.
  *
  * @param object
  * The object to modify.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param queue
  * The new target queue for the object. The queue is retained, and the
  * previous target queue, if any, is released.
  * If queue is DISPATCH_TARGET_QUEUE_DEFAULT, set the object's target queue
  * to the default target queue for the given object type.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NOTHROW
 DISPATCH_SWIFT_NAME(DispatchObject.setTarget(self:queue:))
 void
 dispatch_set_target_queue(dispatch_object_t object,
 		dispatch_queue_t _Nullable queue);
 
 /*!
  * @function dispatch_main
  *
  * @abstract
  * Execute blocks submitted to the main queue.
  *
  * @discussion
  * This function "parks" the main thread and waits for blocks to be submitted
  * to the main queue. This function never returns.
  *
  * Applications that call NSApplicationMain() or CFRunLoopRun() on the
  * main thread do not need to call dispatch_main().
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NOTHROW DISPATCH_NORETURN
 DISPATCH_SWIFT_NAME(dispatchMain())
 void
 dispatch_main(void);
 
 /*!
  * @function dispatch_after
  *
  * @abstract
  * Schedule a block for execution on a given queue at a specified time.
  *
  * @discussion
  * Passing DISPATCH_TIME_NOW as the "when" parameter is supported, but not as
  * optimal as calling dispatch_async() instead. Passing DISPATCH_TIME_FOREVER
  * is undefined.
  *
  * @param when
  * A temporal milestone returned by dispatch_time() or dispatch_walltime().
  *
  * @param queue
  * A queue to which the given block will be submitted at the specified time.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param block
  * The block of code to execute.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_after(dispatch_time_t when, dispatch_queue_t queue,
 		dispatch_block_t block);
 #endif
 
 /*!
  * @function dispatch_after_f
  *
  * @abstract
  * Schedule a function for execution on a given queue at a specified time.
  *
  * @discussion
  * See dispatch_after() for details.
  *
  * @param when
  * A temporal milestone returned by dispatch_time() or dispatch_walltime().
  *
  * @param queue
  * A queue to which the given function will be submitted at the specified time.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_after_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.asyncAfter(self:deadline:qos:flags:execute:)")
 void
 dispatch_after_f(dispatch_time_t when, dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);
 
 /*!
  * @functiongroup Dispatch Barrier API
  * The dispatch barrier API is a mechanism for submitting barrier blocks to a
  * dispatch queue, analogous to the dispatch_async()/dispatch_sync() API.
  * It enables the implementation of efficient reader/writer schemes.
  * Barrier blocks only behave specially when submitted to queues created with
  * the DISPATCH_QUEUE_CONCURRENT attribute; on such a queue, a barrier block
  * will not run until all blocks submitted to the queue earlier have completed,
  * and any blocks submitted to the queue after a barrier block will not run
  * until the barrier block has completed.
  * When submitted to a a global queue or to a queue not created with the
  * DISPATCH_QUEUE_CONCURRENT attribute, barrier blocks behave identically to
  * blocks submitted with the dispatch_async()/dispatch_sync() API.
  */
 
 /*!
  * @function dispatch_barrier_async
  *
  * @abstract
  * Submits a barrier block for asynchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a block to a dispatch queue like dispatch_async(), but marks that
  * block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues).
  *
  * See dispatch_async() for details and "Dispatch Barrier API" for a description
  * of the barrier semantics.
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The system will hold a reference on the target queue until the block
  * has finished.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param block
  * The block to submit to the target dispatch queue. This function performs
  * Block_copy() and Block_release() on behalf of callers.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.7), ios(4.3))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_barrier_async(dispatch_queue_t queue, dispatch_block_t block);
 #endif
 
 /*!
  * @function dispatch_barrier_async_f
  *
  * @abstract
  * Submits a barrier function for asynchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a function to a dispatch queue like dispatch_async_f(), but marks
  * that function as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
  * queues).
  *
  * See dispatch_async_f() for details and "Dispatch Barrier API" for a
  * description of the barrier semantics.
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The system will hold a reference on the target queue until the function
  * has returned.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_barrier_async_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.7), ios(4.3))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.async(self:group:qos:flags:execute:)")
 void
 dispatch_barrier_async_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);
 
 /*!
  * @function dispatch_barrier_sync
  *
  * @abstract
  * Submits a barrier block for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a block to a dispatch queue like dispatch_sync(), but marks that
  * block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues).
  *
  * See dispatch_sync() for details and "Dispatch Barrier API" for a description
  * of the barrier semantics.
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param block
  * The block to be invoked on the target dispatch queue.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.7), ios(4.3))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_barrier_sync(dispatch_queue_t queue,
 		DISPATCH_NOESCAPE dispatch_block_t block);
 #endif
 
 /*!
  * @function dispatch_barrier_sync_f
  *
  * @abstract
  * Submits a barrier function for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a function to a dispatch queue like dispatch_sync_f(), but marks that
  * fuction as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues).
  *
  * See dispatch_sync_f() for details.
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_barrier_sync_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.7), ios(4.3))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.sync(self:flags:execute:)")
 void
 dispatch_barrier_sync_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);
 
 /*!
  * @function dispatch_barrier_async_and_wait
  *
  * @abstract
  * Submits a block for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a block to a dispatch queue like dispatch_async_and_wait(), but marks
  * that block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
  * queues).
  *
  * See "Dispatch Barrier API" for a description of the barrier semantics.
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param work
  * The application-defined block to invoke on the target queue.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift")
 void
 dispatch_barrier_async_and_wait(dispatch_queue_t queue,
 		DISPATCH_NOESCAPE dispatch_block_t block);
 #endif
 
 /*!
  * @function dispatch_barrier_async_and_wait_f
  *
  * @abstract
  * Submits a function for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a function to a dispatch queue like dispatch_async_and_wait_f(), but
  * marks that function as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
  * queues).
  *
  * See "Dispatch Barrier API" for a description of the barrier semantics.
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_barrier_async_and_wait_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift")
 void
 dispatch_barrier_async_and_wait_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);
 
 /*!
  * @functiongroup Dispatch queue-specific contexts
  * This API allows different subsystems to associate context to a shared queue
  * without risk of collision and to retrieve that context from blocks executing
  * on that queue or any of its child queues in the target queue hierarchy.
  */
 
 /*!
  * @function dispatch_queue_set_specific
  *
  * @abstract
  * Associates a subsystem-specific context with a dispatch queue, for a key
  * unique to the subsystem.
  *
  * @discussion
  * The specified destructor will be invoked with the context on the default
  * priority global concurrent queue when a new context is set for the same key,
  * or after all references to the queue have been released.
  *
  * @param queue
  * The dispatch queue to modify.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param key
  * The key to set the context for, typically a pointer to a static variable
  * specific to the subsystem. Keys are only compared as pointers and never
  * dereferenced. Passing a string constant directly is not recommended.
  * The NULL key is reserved and attempts to set a context for it are ignored.
  *
  * @param context
  * The new subsystem-specific context for the object. This may be NULL.
  *
  * @param destructor
  * The destructor function pointer. This may be NULL and is ignored if context
  * is NULL.
  */
 API_AVAILABLE(macos(10.7), ios(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_queue_set_specific(dispatch_queue_t queue, const void *key,
 		void *_Nullable context, dispatch_function_t _Nullable destructor);
 
 /*!
  * @function dispatch_queue_get_specific
  *
  * @abstract
  * Returns the subsystem-specific context associated with a dispatch queue, for
  * a key unique to the subsystem.
  *
  * @discussion
  * Returns the context for the specified key if it has been set on the specified
  * queue.
  *
  * @param queue
  * The dispatch queue to query.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param key
  * The key to get the context for, typically a pointer to a static variable
  * specific to the subsystem. Keys are only compared as pointers and never
  * dereferenced. Passing a string constant directly is not recommended.
  *
  * @result
  * The context for the specified key or NULL if no context was found.
  */
 API_AVAILABLE(macos(10.7), ios(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_PURE DISPATCH_WARN_RESULT
 DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void *_Nullable
 dispatch_queue_get_specific(dispatch_queue_t queue, const void *key);
 
 /*!
  * @function dispatch_get_specific
  *
  * @abstract
  * Returns the current subsystem-specific context for a key unique to the
  * subsystem.
  *
  * @discussion
  * When called from a block executing on a queue, returns the context for the
  * specified key if it has been set on the queue, otherwise returns the result
  * of dispatch_get_specific() executed on the queue's target queue or NULL
  * if the current queue is a global concurrent queue.
  *
  * @param key
  * The key to get the context for, typically a pointer to a static variable
  * specific to the subsystem. Keys are only compared as pointers and never
  * dereferenced. Passing a string constant directly is not recommended.
  *
  * @result
  * The context for the specified key or NULL if no context was found.
  */
 API_AVAILABLE(macos(10.7), ios(5.0))
 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 DISPATCH_REFINED_FOR_SWIFT
 void *_Nullable
 dispatch_get_specific(const void *key);
 
 /*!
  * @functiongroup Dispatch assertion API
  *
  * This API asserts at runtime that code is executing in (or out of) the context
  * of a given queue. It can be used to check that a block accessing a resource
  * does so from the proper queue protecting the resource. It also can be used
  * to verify that a block that could cause a deadlock if run on a given queue
  * never executes on that queue.
  */
 
 /*!
  * @function dispatch_assert_queue
  *
  * @abstract
  * Verifies that the current block is executing on a given dispatch queue.
  *
  * @discussion
  * Some code expects to be run on a specific dispatch queue. This function
  * verifies that that expectation is true.
  *
  * If the currently executing block was submitted to the specified queue or to
  * any queue targeting it (see dispatch_set_target_queue()), this function
  * returns.
  *
  * If the currently executing block was submitted with a synchronous API
  * (dispatch_sync(), dispatch_barrier_sync(), ...), the context of the
  * submitting block is also evaluated (recursively).
  * If a synchronously submitting block is found that was itself submitted to
  * the specified queue or to any queue targeting it, this function returns.
  *
  * Otherwise this function asserts: it logs an explanation to the system log and
  * terminates the application.
  *
  * Passing the result of dispatch_get_main_queue() to this function verifies
  * that the current block was submitted to the main queue, or to a queue
  * targeting it, or is running on the main thread (in any context).
  *
  * When dispatch_assert_queue() is called outside of the context of a
  * submitted block (for example from the context of a thread created manually
  * with pthread_create()) then this function will also assert and terminate
  * the application.
  *
  * The variant dispatch_assert_queue_debug() is compiled out when the
  * preprocessor macro NDEBUG is defined. (See also assert(3)).
  *
  * @param queue
  * The dispatch queue that the current block is expected to run on.
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_assert_queue(dispatch_queue_t queue)
 		DISPATCH_ALIAS_V2(dispatch_assert_queue);
 
 /*!
  * @function dispatch_assert_queue_barrier
  *
  * @abstract
  * Verifies that the current block is executing on a given dispatch queue,
  * and that the block acts as a barrier on that queue.
  *
  * @discussion
  * This behaves exactly like dispatch_assert_queue(), with the additional check
  * that the current block acts as a barrier on the specified queue, which is
  * always true if the specified queue is serial (see DISPATCH_BLOCK_BARRIER or
  * dispatch_barrier_async() for details).
  *
  * The variant dispatch_assert_queue_barrier_debug() is compiled out when the
  * preprocessor macro NDEBUG is defined. (See also assert()).
  *
  * @param queue
  * The dispatch queue that the current block is expected to run as a barrier on.
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_assert_queue_barrier(dispatch_queue_t queue);
 
 /*!
  * @function dispatch_assert_queue_not
  *
  * @abstract
  * Verifies that the current block is not executing on a given dispatch queue.
  *
  * @discussion
  * This function is the equivalent of dispatch_assert_queue() with the test for
  * equality inverted. That means that it will terminate the application when
  * dispatch_assert_queue() would return, and vice-versa. See discussion there.
  *
  * The variant dispatch_assert_queue_not_debug() is compiled out when the
  * preprocessor macro NDEBUG is defined. (See also assert(3)).
  *
  * @param queue
  * The dispatch queue that the current block is expected not to run on.
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1
 DISPATCH_REFINED_FOR_SWIFT
 void
 dispatch_assert_queue_not(dispatch_queue_t queue)
 		DISPATCH_ALIAS_V2(dispatch_assert_queue_not);
 
 #ifdef NDEBUG
 #define dispatch_assert_queue_debug(q) ((void)(0 && (q)))
 #define dispatch_assert_queue_barrier_debug(q) ((void)(0 && (q)))
 #define dispatch_assert_queue_not_debug(q) ((void)(0 && (q)))
 #else
 #define dispatch_assert_queue_debug(q) dispatch_assert_queue(q)
 #define dispatch_assert_queue_barrier_debug(q) dispatch_assert_queue_barrier(q)
 #define dispatch_assert_queue_not_debug(q) dispatch_assert_queue_not(q)
 #endif
 
 /* @function dispatch_allow_send_signals
  *
  * @discussion
  * This function provides the calling process an ability to send signals to
  * it's pthread worker threads created to service incoming work to dispatch,
  * including those which were already created prior to this function call
  * and those who may be created in the future. After a call to this function
  * returns successfully, this ability is retained for the lifetime of the
  * calling process.
  * Regular UNIX calls still need to be used to manipulate signal mask of
  * each individual pthread worker thread to allow delivery of a specific
  * signal to that thread.
  *
  * @param preserve_signum
  * Dispatch and its kernel runtime subsystem manages a pool of pthread
  * worker threads which are reused for handling incoming work to dispatch.
  * The signal number specified here is used internally by this subsystem to
  * preserve sigmask of the pthread worker threads across their reuse.
  *
  * In other words, if a pthread worker thread unblocks delivery of
  * @preserve_signum using regular UNIX calls after a call to this
  * function using the same @preserve_signum returns successfully,
  * that @preserve_signum remains unblocked across that thread's
  * reuse until it is further modified by regular UNIX calls.
  * Therefore, it avoids the need to call regular UNIX calls to
  * unblock delivery of @preserve_signum every time that thread
  * is reused. The specific signal @preserve_signum can be sent
  * to that specific pthread worker thread using pthread_kill().
  *
  * The following code illustrates an expected usage of this API.
  *
  * <code>
  *
  * // Enable sending signals to dispatch pthread worker threads.
  * int ret = dispatch_allow_send_signals(sig);
  * // Validate ret.
  *
  * dispatch_async(q, ^{
  *     // Unblock sig for this worker thread if not already done.
  *     // Such a state could be saved in TSD or globally.
  *     mask = sigmask(sig);
  *     pthread_sigmask(SIG_UNBLOCK, &mask, NULL);
  *     // busy with some work. Can receive signal sig.
  *     // If this worker thread is re-used later, it does not
  *     // not need to call pthread_sigmask again to unblock delivery
  *     // of signal sig.
  * }
  *
  * This function returns 0 upon success and -1 with an errno otherwise.
  * Possible error codes are as below :
  *
  * EINVAL     : @preserve_signum is prohibited and is not allowed to be preserved
  *              across the thread's reuse.
  * ENOTSUP    : The underlying kernel does not support this functionality.
  *
  * </code>
  */
 API_AVAILABLE(macos(14.4), ios(17.4), visionos(1.1))
 API_UNAVAILABLE(tvos, watchos, driverkit)
 DISPATCH_EXPORT
 int
 dispatch_allow_send_signals(int preserve_signum);
 
 __END_DECLS
 
 DISPATCH_ASSUME_ABI_SINGLE_END
 DISPATCH_ASSUME_NONNULL_END
 
 #endif