| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in Mac OS X v10.5 and later. |
| Companion guide | |
| Declared in | NSOperation.h |
| Related sample code |
The NSOperationQueue class regulates the execution of a set of NSOperation objects. After being added to a queue, an operation remains in that queue until it is explicitly canceled or finishes executing its task. Operations within the queue (but not yet executing) are themselves organized according to priority levels and inter-operation object dependencies and are executed accordingly. An application may create multiple operation queues and submit operations to any of them.
Inter-operation 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 operations that are ready to execute, the operation queue always executes the one with the highest priority relative to the other ready operations. For details on how to set priority levels and dependencies, see NSOperation Class Reference.
You cannot directly remove an operation from a queue after it has been added. An operation remains in its queue until it reports that it is finished with its task. Finishing its task does not 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 abort 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.
start method as soon as possible. The start method, in turn, moves the operation to the finished state so that it can be removed from the queue. In Mac OS X v10.5, a canceled operation does not ignore its dependencies, meaning that those dependencies must complete normally before the canceled operation can run and be removed from the queue. Operation queues usually provide the threads used to run their operations. In Mac OS X v10.6 and later, operation queues use the libdispatch library (also known as Grand Central Dispatch) 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 concurrent or non-concurrent operations. In Mac OS X v10.5, however, operations are executed on separate threads only if their isConcurrent method returns NO. If that method returns YES, the operation object is expected to create its own thread (or start some asynchronous operation); the queue does not provide a thread for it.
For more information about using operation queues, see Concurrency Programming Guide.
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. The properties you can observe include the following:
operations - read-only property
operationCount - read-only property
maxConcurrentOperationCount - readable and writable property
suspended - readable and writable property
name - readable and writable property
Although you can attach observers to these properties, you should not 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 application’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.
It is safe to use a single NSOperationQueue object from multiple threads without creating additional locks to synchronize access to that object.
– addOperation:
– addOperations:waitUntilFinished:
– addOperationWithBlock:
– operations
– operationCount
– cancelAllOperations
– waitUntilAllOperationsAreFinished
Returns the operation queue that launched the current operation.
+ (id)currentQueue
The operation queue that started the operation or nil if the queue could not be determined.
You can use this method from within a running operation object to get a reference to the operation queue that started it. Calling this method from outside the context of a running operation typically results in nil being returned.
NSOperation.hReturns the operation queue associated with the main thread.
+ (id)mainQueue
The default operation queue bound to the main thread.
The returned queue executes operations serially on the main thread. The main thread’s run loop controls the execution times of these operations.
NSOperation.hAdds the specified operation object to the receiver.
- (void)addOperation:(NSOperation *)operation
The operation object to be added to the queue. In memory-managed applications, this object is retained by the operation queue. In garbage-collected applications, the queue strongly references the operation object.
Once added, the specified operation remains in the queue until it finishes executing.
An operation object can be in at most one operation queue at a time and this method throws an NSInvalidArgumentException exception if the operation is already in another queue. Similarly, this method throws an NSInvalidArgumentException exception if the operation is currently executing or has already finished executing.
– cancel (NSOperation)– isExecuting (NSOperation)NSOperation.hAdds the specified array of operations to the queue.
- (void)addOperations:(NSArray *)ops waitUntilFinished:(BOOL)wait
The array of NSOperation objects that you want to add to the receiver.
If YES, the current thread is blocked until all of the specified operations finish executing. If NO, the operations are added to the queue and control returns immediately to the caller.
An operation object can be in at most one operation queue at a time and cannot be added if it is currently executing or finished. This method throws an NSInvalidArgumentException exception if any of those error conditions are true for any of the operations in the ops parameter.
Once added, the specified operation remains in the queue until it its isFinished method returns YES.
NSOperation.hWraps the specified block in an operation object and adds it to the receiver.
- (void)addOperationWithBlock:(void (^)(void))block
The block to execute from the operation object. The block should take no parameters and have no return value.
This method adds a single block to the receiver by first wrapping it in an operation object. You should not attempt to get a reference to the newly created operation object or divine its type information.
Once added, the specified operation remains in the queue until it its isFinished method returns YES.
– cancel (NSOperation)– isExecuting (NSOperation)NSOperation.hCancels all queued and executing operations.
- (void)cancelAllOperations
This method sends a cancel message to all operations currently in the queue. Queued operations are cancelled before they begin executing. If an operation is already executing, it is up to that operation to recognize the cancellation and stop what it is doing.
cancel (NSOperation)NSOperation.hReturns a Boolean value indicating whether the receiver is scheduling queued operations for execution.
- (BOOL)isSuspended
NO if operations are being scheduled for execution; otherwise, YES.
If you want to know when the queue’s suspended state changes, configure a KVO observer to observe the suspended key path of the operation queue.
NSOperation.hReturns the maximum number of concurrent operations that the receiver can execute.
- (NSInteger)maxConcurrentOperationCount
The maximum number of concurrent operations set explicitly on the receiver using the setMaxConcurrentOperationCount: method. If no value has been explicitly set, this method returns NSOperationQueueDefaultMaxConcurrentOperationCount by default.
NSOperation.hReturns the name of the receiver.
- (NSString *)name
The name of the receiver.
The default value of this string is “NSOperationQueue <id>”, where <id> is the memory address of the operation queue. If you want to know when a queue’s name changes, configure a KVO observer to observe the name key path of the operation queue.
NSOperation.hReturns the number of operations currently in the queue.
- (NSUInteger)operationCount
The number of operations in the queue.
The value returned by this method reflects the instantaneous number of objects in the queue and changes as operations are completed. As a result, by the time you use the returned value, the actual number of operations may be different. You should therefore use this value only for approximate guidance and should not rely on it for object enumerations or other precise calculations.
NSOperation.hReturns a new array containing the operations currently in the queue.
- (NSArray *)operations
A new array object containing the NSOperation objects in the order in which they were added to the queue.
You can use this method to access the operations queued at any given moment. Operations remain queued until they finish their task. Therefore, the returned array may contain operations that are either executing or waiting to be executed. The list may also contain operations that were executing when the array was initially created but have subsequently finished.
NSOperation.hSets the maximum number of concurrent operations that the receiver can execute.
- (void)setMaxConcurrentOperationCount:(NSInteger)count
The maximum number of concurrent operations. Specify the value NSOperationQueueDefaultMaxConcurrentOperationCount if you want the receiver to choose an appropriate value based on the number of available processors and other relevant factors.
The specified value affects only the receiver and the operations in its queue. Other operation queue objects can also execute their maximum number of operations in parallel.
Reducing the number of concurrent operations does not affect any operations that are currently executing. If you specify the value NSOperationQueueDefaultMaxConcurrentOperationCount (which is recommended), the maximum number of operations can change dynamically based on system conditions.
NSOperation.hAssigns the specified name to the receiver.
- (void)setName:(NSString *)newName
The new name to associate with the receiver.
Names provide a way for you to identify your operation queues at run time. Tools may also use this name to provide additional context during debugging or analysis of your code.
NSOperation.hModifies the execution of pending operations
- (void)setSuspended:(BOOL)suspend
If YES, the queue stops scheduling queued operations for execution. If NO, the queue begins scheduling operations again.
This method suspends or resumes the execution of operations. Suspending a queue prevents that queue from starting additional operations. In other words, operations that are in the queue (or added to the queue later) and are not yet executing are prevented from starting until the queue is resumed. Suspending a queue does not stop operations that are already running.
Operations are removed from the queue only when they finish executing. However, in order to finish executing, an operation must first be started. Because a suspended queue does not start any new operations, it does not remove any operations (including cancelled operations) that are currently queued and not executing.
NSOperation.hBlocks the current thread until all of the receiver’s queued and executing operations finish executing.
- (void)waitUntilAllOperationsAreFinished
When called, this method blocks the current thread and waits for the receiver’s current and queued operations to finish executing. While the current thread is blocked, the receiver continues to launch already queued operations and monitor those that are executing. During this time, the current thread cannot add operations to the queue, but other threads may. Once all of the pending operations are finished, this method returns.
If there are no operations in the queue, this method returns immediately.
NSOperation.hIndicates the number of supported concurrent operations.
enum {
NSOperationQueueDefaultMaxConcurrentOperationCount = -1
};
NSOperationQueueDefaultMaxConcurrentOperationCountThe default maximum number of operations is determined dynamically by the NSOperationQueue object based on current system conditions.
Available in Mac OS X v10.5 and later.
Declared in NSOperation.h.
NSOperation.hLast updated: 2009-08-19
Mac OS X Reference Library Data Management: Event Handling NSOperationQueue Class Reference