#include <dispatch/queue.h> also included by <dispatch/dispatch.h>
Dispatch

dispatch/queue.h

for HeaderDoc
35 functions · 18 macros · 9 typedefs · 2 variables · 1 enum

typedefdispatch_queue_t

@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)

typedefdispatch_queue_global_t

@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)

typedefdispatch_queue_serial_executor_t

DISPATCH_DECL_SUBCLASS_SWIFT(dispatch_queue_serial_executor, dispatch_queue, _DispatchSerialExecutorQueue)

typedefdispatch_queue_serial_t

DISPATCH_DECL_SERIAL_EXECUTOR_SWIFT(dispatch_queue_serial, DispatchSerialQueue)

typedefdispatch_queue_main_t

@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)

typedefdispatch_queue_concurrent_t

DISPATCH_DECL_SUBCLASS_SWIFT(dispatch_queue_concurrent, dispatch_queue, DispatchConcurrentQueue)

functiondispatch_async

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
)
@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.

functiondispatch_async_f

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_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.

functiondispatch_sync

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
)
@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.

functiondispatch_sync_f

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_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.

functiondispatch_async_and_wait

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
)
@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.

functiondispatch_async_and_wait_f

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
)
@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.

macroDISPATCH_APPLY_AUTO_AVAILABLE

#define DISPATCH_APPLY_AUTO_AVAILABLE 1

macroDISPATCH_APPLY_QUEUE_ARG_NULLABILITY

#define DISPATCH_APPLY_QUEUE_ARG_NULLABILITY _Nullable

macroDISPATCH_APPLY_AUTO

@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.
#define DISPATCH_APPLY_AUTO ((dispatch_queue_t _Nonnull)0)

functiondispatch_apply

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)
)
@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.

functiondispatch_apply_f

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_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.

functiondispatch_get_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
)
deprecated
@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.

variable_dispatch_main_q

API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_EXPORT struct dispatch_queue_s _dispatch_main_q

functiondispatch_get_main_queue

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
)
@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.

macroDISPATCH_QUEUE_PRIORITY_HIGH

@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

macroDISPATCH_QUEUE_PRIORITY_DEFAULT

#define DISPATCH_QUEUE_PRIORITY_DEFAULT 0

macroDISPATCH_QUEUE_PRIORITY_LOW

#define DISPATCH_QUEUE_PRIORITY_LOW (-2)

macroDISPATCH_QUEUE_PRIORITY_BACKGROUND

#define DISPATCH_QUEUE_PRIORITY_BACKGROUND INT16_MIN

typedefdispatch_queue_priority_t

typedef long dispatch_queue_priority_t

functiondispatch_get_global_queue

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
)
@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.

typedefdispatch_queue_attr_t

DISPATCH_DECL(dispatch_queue_attr)

macroDISPATCH_QUEUE_SERIAL

@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

macroDISPATCH_QUEUE_SERIAL_INACTIVE

@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)

macroDISPATCH_QUEUE_CONCURRENT

@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)

variable_dispatch_queue_attr_concurrent

API_AVAILABLE(macos(10.7), ios(4.3)) DISPATCH_EXPORT struct dispatch_queue_attr_s _dispatch_queue_attr_concurrent

macroDISPATCH_QUEUE_CONCURRENT_INACTIVE

@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)

functiondispatch_queue_attr_make_initially_inactive

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
)
@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.

macroDISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL

@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)

macroDISPATCH_QUEUE_CONCURRENT_WITH_AUTORELEASE_POOL

@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)

enumdispatch_autorelease_frequency_t

underlying type unsigned long
DISPATCH_AUTORELEASE_FREQUENCY_INHERIT0
DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM1
DISPATCH_AUTORELEASE_FREQUENCY_NEVER2

typedefdispatch_autorelease_frequency_t

typedef enum dispatch_autorelease_frequency_t dispatch_autorelease_frequency_t;

functiondispatch_queue_attr_make_with_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_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.

functiondispatch_queue_attr_make_with_qos_class

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
)
@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.

macroDISPATCH_TARGET_QUEUE_DEFAULT

@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

functiondispatch_queue_create_with_target

DISPATCH_ALIAS_V2(dispatch_queue_create_with_target)
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
)
@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.

functiondispatch_queue_create

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
)
@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.

macroDISPATCH_CURRENT_QUEUE_LABEL

@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

functiondispatch_queue_get_label

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_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.

functiondispatch_queue_get_qos_class

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_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

functiondispatch_set_target_queue

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_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.

functiondispatch_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_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().

functiondispatch_after

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
)
@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.

functiondispatch_after_f

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
)
@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.

functiondispatch_barrier_async

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
)
@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.

functiondispatch_barrier_async_f

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_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.

functiondispatch_barrier_sync

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
)
@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.

functiondispatch_barrier_sync_f

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_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.

functiondispatch_barrier_async_and_wait

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
)
@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.

functiondispatch_barrier_async_and_wait_f

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
)
@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.

functiondispatch_queue_set_specific

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_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.

functiondispatch_queue_get_specific

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_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.

functiondispatch_get_specific

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
)
@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.

functiondispatch_assert_queue

DISPATCH_ALIAS_V2(dispatch_assert_queue)
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
)
@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.

functiondispatch_assert_queue_barrier

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_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.

functiondispatch_assert_queue_not

DISPATCH_ALIAS_V2(dispatch_assert_queue_not)
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
)
@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.

macrodispatch_assert_queue_debug

#define dispatch_assert_queue_debug(q) dispatch_assert_queue(q)

macrodispatch_assert_queue_barrier_debug

#define dispatch_assert_queue_barrier_debug(q) dispatch_assert_queue_barrier(q)

macrodispatch_assert_queue_not_debug

#define dispatch_assert_queue_not_debug(q) dispatch_assert_queue_not(q)

functiondispatch_allow_send_signals

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
)
@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>