Dispatch Queue

An object that manages the execution of tasks serially or concurrently on your app's main thread or on a background thread.

Overview

Dispatch queues are FIFO queues to which your application can submit tasks in the form of block objects. Dispatch queues execute tasks either serially or concurrently. Work submitted to dispatch queues executes on a pool of threads managed by the system. Except for the dispatch queue representing your app's main thread, the system makes no guarantees about which thread it uses to execute a task.

You schedule work items synchronously or asynchronously. When you schedule a work item synchronously, your code waits until that item finishes execution. When you schedule a work item asynchronously, your code continues executing while the work item runs elsewhere.

Dispatch queues provide minimal support for autoreleased objects by default. System APIs may return autoreleased objects to your code. For example, NSError objects are often autoreleased. If you see memory pressure increase because of autoreleased objects created in your blocks, consider adding autorelease pools to those blocks to relieve the pressure. You can also configure the default autorelease behavior of any custom dispatch queues using the dispatch_queue_attr_make_with_autorelease_frequency function at creation time.

Avoiding Excessive Thread Creation

When designing tasks for concurrent execution, do not call methods that block the current thread of execution. When a task scheduled by a concurrent dispatch queue blocks a thread, the system creates additional threads to run other queued concurrent tasks. If too many tasks block, the system may run out of threads for your app.

Another way that apps consume too many threads is by creating too many private concurrent dispatch queues. Because each dispatch queue consumes thread resources, creating additional concurrent dispatch queues exacerbates the thread consumption problem. Instead of creating private concurrent queues, submit tasks to one of the global concurrent dispatch queues. For serial tasks, set the target of your serial queue to one of the global concurrent queues. That way, you can maintain the serialized behavior of the queue while minimizing the number of separate queues creating threads.

Topics

Creating a Dispatch Queue

dispatch_get_main_queue

Returns the serial dispatch queue associated with the application’s main thread.

dispatch_get_global_queue

Returns a system-defined global concurrent queue with the specified quality-of-service class.

dispatch_queue_create

Creates a new dispatch queue to which you can submit blocks.

dispatch_queue_create_with_target

Creates a new dispatch queue to which you can submit blocks.

DISPATCH_QUEUE_SERIAL

A dispatch queue that executes blocks serially in FIFO order.

DISPATCH_QUEUE_CONCURRENT

A dispatch queue that executes blocks concurrently.

dispatch_queue_t

A lightweight object to which your application submits blocks for subsequent execution.

dispatch_queue_main_t

A dispatch queue that is bound to the app's main thread and executes tasks serially on that thread.

dispatch_queue_global_t

A dispatch queue that executes tasks concurrently using threads from the global thread pool.

dispatch_queue_serial_t

A dispatch queue that executes tasks serially in first-in, first-out (FIFO) order.

dispatch_queue_concurrent_t

A dispatch queue that executes tasks concurrently and in any order, respecting any barriers that may be in place.

Configuring Queue Execution Parameters

dispatch_queue_attr_t

Attributes describing the behaviors of a dispatch queue.

dispatch_queue_attr_make_with_qos_class

Returns attributes suitable for creating a dispatch queue with the desired quality-of-service information.

dispatch_queue_get_qos_class

Returns the quality-of-service class for the specified queue.

dispatch_qos_class_t

Quality-of-service classes that specify the priorities for executing tasks.

dispatch_queue_attr_make_initially_inactive

Returns an attribute that configures a dispatch queue as initially inactive.

dispatch_queue_attr_make_with_autorelease_frequency

Returns an attribute that specifies how the dispatch queue manages autorelease pools for the blocks it executes.

dispatch_autorelease_frequency_t

Constants indicating the frequency with which a dispatch queue creates autorelease pools for its tasks.

Executing Tasks Asynchronously

dispatch_async

Submits a block for asynchronous execution on a dispatch queue and returns immediately.

dispatch_async_f

Submits an application-defined function for asynchronous execution on a dispatch queue and returns immediately.

dispatch_after

Enqueues a block for execution at the specified time.

dispatch_after_f

Enqueues an application-defined function for execution at the specified time.

dispatch_function_t

The prototype of functions submitted to dispatch queues.

dispatch_block_t

The prototype of blocks submitted to dispatch queues, which take no arguments and have no return value.

Executing Tasks Synchronously

dispatch_sync

Submits a block object for execution and returns after that block finishes executing.

dispatch_sync_f

Submits an application-defined function for synchronous execution on a dispatch queue.

Executing a Task Only Once

dispatch_once

Executes a block object only once for the lifetime of an application.

dispatch_once_f

Executes an application-defined function only once for the lifetime of an application.

dispatch_once_t

A predicate for use with the dispatch_once function.

Executing a Task in Parallel

dispatch_apply

Submits a single block to the dispatch queue and causes the block to be executed the specified number of times.

dispatch_apply_f

Submits a single function to the dispatch queue and causes the function to be executed the specified number of times.

Managing Queue Attributes

dispatch_queue_get_label

Returns the label you assigned to the dispatch queue at creation time.

DISPATCH_CURRENT_QUEUE_LABEL

Pass this constant to the dispatch_queue_get_label function to retrieve the label of the current queue.

dispatch_set_target_queue

Specifies the dispatch queue on which to perform work associated with the current object.

Getting and Setting Contextual Data

dispatch_get_specific

Returns the value for the key associated with the current dispatch queue.

dispatch_queue_set_specific

Sets the key/value data for the specified dispatch queue.

dispatch_queue_get_specific

Gets the value for the key associated with the specified dispatch queue.

Managing the Main Dispatch Queue

dispatch_main

Executes blocks submitted to the main queue.

See Also

Queues and Tasks

dispatch_get_main_queue

Returns the serial dispatch queue associated with the application’s main thread.

dispatch_get_global_queue

Returns a system-defined global concurrent queue with the specified quality-of-service class.

Dispatch Work Item

The work you want to perform, encapsulated in a way that lets you attach a completion handle or execution dependencies.

Dispatch Group

A group of tasks that you monitor as a single unit.