Class

NSOperationQueue

A queue that regulates the execution of operations.

Declaration

@interface NSOperationQueue : NSObject

Overview

An operation queue executes its queued NSOperation objects based on their priority and readiness. After being added to an operation queue, an operation remains in its queue until it reports that it is finished with its task. You can’t directly remove an operation from a queue after it has been added.

For more information about using operation queues, see Concurrency Programming Guide.

Determining Execution Order

Operations within a queue are organized according to their readiness, priority level, and interoperation dependencies, and are executed accordingly. If all of the queued operations have the same queuePriority and are ready to execute when they are put in the queue—that is, their ready property returns YES—they’re executed in the order in which they were submitted to the queue. Otherwise, the operation queue always executes the one with the highest priority relative to the other ready operations.

However, you should never rely on queue semantics to ensure a specific execution order of operations, because changes in the readiness of an operation can change the resulting execution order. Interoperation dependencies provide an absolute execution order for operations, even if those operations are located in different operation queues. An operation object is not considered ready to execute until all of its dependent operations have finished executing.

For details on how to set priority levels and dependencies, see Managing Dependencies in NSOperation.

Canceling Operations

Finishing its task doesn’t necessarily mean that the operation performed that task to completion; an operation can also be canceled. Canceling an operation object leaves the object in the queue but notifies the object that it should stop its task as quickly as possible. For currently executing operations, this means that the operation object’s work code must check the cancellation state, stop what it is doing, and mark itself as finished. For operations that are queued but not yet executing, the queue must still call the operation object’s start method so that it can processes the cancellation event and mark itself as finished.

For more information about operation cancellation, see Responding to the Cancel Command in NSOperation.

KVO-Compliant Properties

The NSOperationQueue class is key-value coding (KVC) and key-value observing (KVO) compliant. You can observe these properties as desired to control other parts of your application. To observe the properties, use the following key paths:

Although you can attach observers to these properties, you shouldn’t use Cocoa bindings to bind them to elements of your application’s user interface. Code associated with your user interface typically must execute only in your app’s main thread. However, KVO notifications associated with an operation queue may occur in any thread.

For more information about key-value observing and how to attach observers to an object, see Key-Value Observing Programming Guide.

Thread Safety

It is safe to use a single NSOperationQueue object from multiple threads without creating additional locks to synchronize access to that object.

Operation queues use the Dispatch framework to initiate the execution of their operations. As a result, operations are always executed on a separate thread, regardless of whether they are designated as synchronous or asynchronous.

Topics

Accessing Specific Operation Queues

mainQueue

Returns the operation queue associated with the main thread.

currentQueue

Returns the operation queue that launched the current operation.

Managing Operations in the Queue

addOperation:

Adds the specified operation to the receiver.

addOperations:waitUntilFinished:

Adds the specified operations to the queue.

addOperationWithBlock:

Wraps the specified block in an operation and adds it to the receiver.

operations

The operations currently in the queue.

operationCount

The number of operations currently in the queue.

cancelAllOperations

Cancels all queued and executing operations.

waitUntilAllOperationsAreFinished

Blocks the current thread until all of the receiver’s queued and executing operations finish executing.

Managing the Execution of Operations

qualityOfService

The default service level to apply to operations executed using the queue.

maxConcurrentOperationCount

The maximum number of queued operations that can execute at the same time.

NSOperationQueueDefaultMaxConcurrentOperationCount

The default maximum number of operations to be executed concurrently in a queue.

Suspending Execution

suspended

A Boolean value indicating whether the queue is actively scheduling operations for execution.

Configuring the Queue

name

The name of the operation queue.

underlyingQueue

The dispatch queue used to execute operations.

Relationships

Inherits From

See Also

Operations

NSOperation

An abstract class that represents the code and data associated with a single task.

NSBlockOperation

An operation that manages the concurrent execution of one or more blocks.

NSInvocationOperation

An operation that manages the execution of a single encapsulated task specified as an invocation.