NSOperationQueue [API]

渣英语，如有翻译错误的地方，还请指正，谢谢。

继承关系 NSObject ->NSOperationQueue

输入声明 @import Foundation;

 

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.

NSOperationQueue类是管理NSOperation对象执行的集合。在被加入到一个队列之后，操作仍然保留着，直到他被明确的取消或者操作结束。在操作队列中（但是还未执行）根据它们本身的优先级和操作对象的依赖关系依次执行。一个应用程序可以创建多个操作队列并提交操作。

 

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.

相互操作管理根据操作的绝对执行次序执行，即使那些操作位于不同的操作队列中。在所有从属的操作完成执行以前，操作对象不被认为可以执行。 准备执行的操作中，操作队列总是执行相较于其它操作优先级最高的操作。关于如何选择和设置优先级和关联性，请参看 NSOperation Class Reference

 

You cannot directly remove an operation from a queue after it has beenadded.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 tocompletion.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方法，以便它能处理取消事件和标记完成。

 

 

笔记

Canceling an operation causes the operation to ignore any dependencies it may have.This behavior makes it possible for the queue to execute the operation’s 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.

取消一个操作会引起这个操作忽略任何它应该有的依赖性。 这个行为使得这个队列尽快 执行这个操作的start方法。start方法会依次的使这个操作变成完成阶段以便把它从这个队列中一移走。

 

Operation queues usually provide the threads used to run their operations.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 asynchronous or synchronous operations.

操作队列通常提供所使用的线程来运行它们的操作。操作队列使用libdispatch类库(也称GCD)启动执行操作。因此，操作总是在一个单独的线程上执行，不管它们是同步还是异步。

 

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

更多关于操作队列使用的信息，查看 Concurrency Programming Guide。

 

 

KVO-相关属性

 

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

NSOperationQueue类符合键-值编码(KVC)和监视器(KVO)。你能通过观察这些属性来控制你的应用的其他部分。观察这些属性，使用下列的键值路径：

• operations - read-only  (操作)
• operationCount - read-only (操作数)  
• maxConcurrentOperationCount - readable and writable  (最大操作数)
• suspended - readable and writable  (暂停)
• name - readable and writable (名称)

 

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.

虽然你可以使用观察者这些属相，你也不应该使用Cocoa bindings去绑定应用的用户界面的元素。代码和用户界面通常必须在应用程序的主线程中执行。然而，KVO通知相关操作队列可以在任何线程中执行。

 

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

关于更多观察者的信息和如何给对象添加观察者，参看Key-Value Observing Programming Guide。

 

Multicore Considerations

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

object.

它安全的使用一个单独的NSOperationQueue对象从多个线程在不产生附加的锁定器的情况下访问对象。

 

Additional Operation Queue Behaviors（额外的操作队列行为）

An operation queue executes its queued operation objects based on their priority and readiness.If all of the queued operation objects have the same priority and are ready to execute when they are put in the queue—that is, their 

isReady method returns YES—they are executed in the order in which they were submitted to the queue.However, you should never rely on queue semantics to ensure a specific execution order of operation objects.Changes in the readiness of an operation can change the resulting execution order.If you need operations to execute in a specific order, use operation-level dependencies as defined by the NSOperationclass.

操作队列执行它的队列中的操作对象基于它们的优先级和准备状态。如果队列中的所有操作都有相同的优先级和准备状态，当执行加入队列时—即实现isReady方法并返回YES—它们依次执行加入队列的命令。然而，你不应该依赖队列语义去确保特定的操作对象的执行顺序。改变操作的准备状态可以改变最终执行顺序。如果你需要操作在一个特殊的顺序上执行，使用 NSOperation类确定操作级别的依赖关系。

 

 

 

Getting Specific Operation Queues（获取特定的操作队列）

 

+ currentQueue

 

Returns the operation queue that launched the current operation.

开启当前的操作队列并返回这个操作队列。

 

声明

+ (NSOperationQueue *)currentQueue

 

Return Value（返回值）

The operation queue that started the operation or nil if the queue could not be determined.

当这个操作队列开启的时候，队列不能确定，就返回这个操作或nil。

 

Discussion（讨论）

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.

可以在运行操作对象的的时候使用此方法以获取开启操作队列的引用。从外部调用该方法，在运行操作的时候会返回nil。

 

Availability（有效性）

Available in iOS 4.0 and later.在iOS 4.0以后有效。

 

+ mainQueue

 

Returns the operation queue associated with the main thread.

返回与主线程相关联操作队列。

 

Declaration（声明）

+ (NSOperationQueue *)mainQueue

 

 

Return Value（返回值） 

 

The default operation queue bound to the main thread.

默认与操作队列绑定的主线程。

 

Discussion（讨论）

The returned queue executes one operation at a time on the app’s main thread. The execution of operations on the main thread is interleaved with the other tasks that must execute on the main thread, such as the servicing of events and the updating of an app’s user interface. The queue executes those operations in the run loop common modes, as represented by the NSRunLoopCommonModes constant. The value of the underlyingQueue property for the queue is the dispatch queue for the main thread; this property cannot be set to another value.

返回的操作队列在应用的主线程上执行一次操作。在主线程上执行的操作是与其他必须执行的任务交叉的，比如服务事件和应用程序的用户界面的更新。队列进入运行循环(run loop)模式下执行这些操作，由NSRunLoopCommonModes常数表示。underlyingQueue属性的值是主线程的调度队列；此属性不能设置为另一个值。

 

Availability（适用性）

Available in iOS 4.0 and later. iOS 4.0以后适用。

 

Managing Operations in the Queue（操作队列的管理）

 

- addOperation:

Adds the specified operation object to the receiver.

将特定的操作对象添加到队列中。

 

Declaration（声明）

- (void)addOperation:(NSOperation *)operation

 

 

Parameters（参数） 

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.

                    将要添加到队列中的操作对象。在内存管理的应用程序中，该对象保留在操作队列。在垃圾回收的应用程序中，队列强引用这个对象。 

 

Discussion（讨论）

 

Once added, the specified operation remains in the queue until it finishes executing.

一旦添加，指定的operation将保留在队列中，直到它执行完成。

 

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.

操作对象每次最多在一个队列中，当这个操作已经在另一个队列中，这个方法会抛出NSInvalidArgumentException异常参数。同样如果这个操作正在执行或已经执行完毕，这个方法会抛出 NSInvalidArgumentException异常参数。

 

Availability（适用性）

Available in iOS 2.0 and later.iOS 2.0以后适用。 

 

See Also（另参考）

cancel (NSOperation)

isExecuting (NSOperation)

 

 

- addOperations:waitUntilFinished:

Adds the specified array of operations to the queue.

将指定的操作数组添加到队列中。

Declaration（声明）

- (void)addOperations:(NSArray<NSOperation *> *)ops waitUntilFinished:(BOOL)wait

 

Parameters（参数）

ops：The array of NSOperation objects that you want to add to the receiver.

         接收机中要添加的NSOperation对象数组。

wait：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.

          如果是YES，则当前线程阻塞，直到所有制定的操作执行完成。如果是NO，则该操作添加到队列中并立即控制返回到调用方。

 

Discussion（讨论）

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.

操作对象最多只能在一个队列中，且这个操作当前处在执行或完成状态时不能添加。如果在ops参数中的任何操作符合错误条件，将会返回NSInvalidArgumentException异常参数。

 

Once added, the specified operation remains in the queue until its isFinished method returns YES.

一旦添加，指定的operation仍然在队列中直到它的isFinished方法返回YES。

 

Availability（适用性） 

 

Available in iOS 4.0 and later.iOS 4.0以后适用。 

         

 

- addOperationWithBlock:

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

将block形式的操作添加到队列中。

Declaration（声明）

- (void)addOperationWithBlock:(void (^)(void))block

 

Parameters（参数）

block：The block to execute from the operation object. The block should take no parameters and have no return value.

            操作对象执行的block代码块。这个block没有参数和返回值。

 

Discussion（讨论） 

 

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 determine its type information.

这个方法首先将一个单独的block的操作对象添加到接收器上。你不能尝试对新创建的操作对象引用或确定它的类型信息。

 

Availability（适用性） 

 

Available in iOS 4.0 and later.iOS 4.0以后。 

 

See Also（另参考）

cancel (NSOperation)

isExecuting (NSOperation)

 

operations 

Property（属性）

An array of the operations currently in the queue. (read-only)

当前队列的操作数组。（只读）

 

Declaration（声明）

@property(readonly, copy) NSArray <__kindofNSOperation *> *operations

 

Discussion（讨论）

 

The array in this property contains zero or more NSOperation objects in the order in which they were added to the queue. This order does not necessarily reflect the order in which those operations will be executed.

这个属性的数组中包含0到多个 NSOperation对象，它们按顺序添加到队列中。这个顺序并不一定反应这些操作的执行顺序。 

 

You can use this property to access the operations queued at any given moment. Operations remain queued until they finish their task. Therefore, the array may contain operations that are executing or waiting to be executed. The list may also contain operations that were executing when the array was initially retrieved but have subsequently finished.

你可以使用这个属性在任何时候访问这个操作队列。操作一直在队列当中直到完成任务。所以，该数组可能包含正在执行或等待执行的操作。这个列表还包含数组初始检索时执行但之后完成的操作。

 

You may monitor changes to the value of this property using key-value observing. Configure an observer to monitor the operations key path of the operation queue.

你可以使用key-value observing 来监控该属性值的变化。设置一个观察者来监控操作队列中的operations的key。 

 

 

Availability

Available in iOS 2.0 and later. 

 

operationCount 

Property（属性）

The number of operations currently in the queue. (read-only)

当前队列的操作数。（只读）

 

Declaration（声明） 

@property(readonly) NSUInteger operationCount

 

Discussion（讨论）

 

Because the number of operations in the queue changes as those operations finish executing, the value returned by this property reflects the instantaneous number of operations at the time the property was accessed. By the time you use the value, the actual number of operations may be different. As a result, do not use this value for object enumerations or other precise calculations.

由于在队列中的操作数随着操作执行完成而改变，此属性的返回值是属性被访问时的瞬时值。当你使用这个值时，实际的操作数可能是不同的。所以，不要将这个值用于对象的枚举或其他的精确的计算。

 

You may monitor changes to the value of this property using key-value observing. Configure an observer to monitor the operationCount key path of the operation queue.

你可以使用来key-value observing监控这个属性的值的改变，设置一个观察者来监听操作队列中的operationCount 的key。

 

Availability

Available in iOS 4.0 and later.

 

- cancelAllOperations

Cancels all queued and executing operations.

取消所有队列以及它们的操作。

 

Declaration（声明）

- (void)cancelAllOperations

 

Discussion（讨论）

 

This method calls the cancel method on all operations currently in the queue.

这个方法调用了所有队列中的操作的 cancel 方法。 

 

Canceling the operations does not automatically remove them from the queue or stop those that are currently executing. For operations that are queued and waiting execution, the queue must still attempt to execute the operation before recognizing that it is canceled and moving it to the finished state. For operations that are already executing, the operation object itself must check for cancellation and stop what it is doing so that it can move to the finished state. In both cases, a finished (or canceled) operation is still given a chance to execute its completion block before it is removed from the queue.

取消该操作不会自动从队列中删除或停止当前正在执行的操作。对于正在排队等待执行的操作，该队列仍然需要尝试执行该操作直到确定这个操作被取消并移动到完成状态时。对于正在执行的操作，为了可以将它移动到完成状态，操作对象必须检查自身是否取消并停止执行。在这两种情况下，一个完成（或取消）的操作仍有机会在他被队列移除前执行完代码块。

 

Availability

Available in iOS 2.0 and later.

 

See Also

cancel (NSOperation)

 

- waitUntilAllOperationsAreFinished

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

阻塞当前线程，直到所有接收器的队列和执行操作都完成操作。

Declaration（声明）

- (void)waitUntilAllOperationsAreFinished

 

Discussion（讨论） 

 

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.

如果在队列没有操作，则这个方法立即放回。

 

Availability

Available in iOS 2.0 and later.

 

Managing the Execution of Operations(操作执行的管理)

qualityOfService 

Property（属性）

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

申请这个队列中操作执行的默认服务等级。

Declaration（声明）

@property NSQualityOfService qualityOfService

 

Discussion（讨论）

 

This property specifies the service level applied to operation objects added to the queue. If the operation object has an explicit service level set, that value is used instead. The default value of this property depends on how you created the queue. For queues you create yourself, the default value is NSOperationQualityOfServiceBackground. For the queue returned by the mainQueue method, the default value is NSOperationQualityOfServiceUserInteractive and cannot be changed.

这个属性是用于将操作对象添加到队列中的服务等级。如果这个操作对象有一个明确的服务等级集合，这个值将被使用。这个属性的默认值取决于如何创建队列。当自定义的队列，默认值是 NSOperationQualityOfServiceBackground。队列通过 mainQueue方法返回，默认值为NSOperationQualityOfServiceUserInteractive，这个默认值无法改变。

 

Service levels affect the priority with which operation objects are given access to system resources such as CPU time, network resources, disk resources, and so on. Operations with a higher quality of service level are given greater priority over system resources so that they may perform their task more quickly. You use service levels to ensure that operations responding to explicit user requests are given priority over less critical work.

服务等级会影响操作对象的优先级和操作对象访问系统资源，比如CPU处理时间，网络资源，磁盘资源等。拥有更高的服务级别的操作被赋予更高的优先级，以便使其更快的完成任务。你使用服务级别来保证当前用户请求操作的优先级高于不重要的工作。

 

Availability

Available in iOS 8.0 and later.

 

maxConcurrentOperationCount 

Property（属性）

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

队列中同时执行的操作最大数目。

Declaration（声明）

@property NSInteger maxConcurrentOperationCount

 

Discussion（讨论）

The value in this property affects only the operations that the current queue has executing at the same time. Other operation queues 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. Specifying the value NSOperationQueueDefaultMaxConcurrentOperationCount(which is recommended) causes the system to set the maximum number of operations based on system conditions.

减少同时执行的操作数目并不会影响任何操作的当前执行状态。所指定的值 NSOperationQueueDefaultMaxConcurrentOperationCount(建议)使系统在系统状态下设置更多操作。

 

The default value of this property is NSOperationQueueDefaultMaxConcurrentOperationCount. You may monitor changes to the value of this property using key-value observing. Configure an observer to monitor the maxConcurrentOperationCount key path of the operation queue.

这个属性的默认值是 NSOperationQueueDefaultMaxConcurrentOperationCount。你可以使用key-value observing来检测该属性的值的变化。设置观察者来观察操作队列中的maxConcurrentOperationCount的key值。

 

Availability

Available in iOS 2.0 and later.

 

Suspending Operations（暂停操作）

suspended

 Property（属性）

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

一个布尔值，该值表示这个队列是否活跃的安排操作执行。

Declaration（声明）

@property(getter=isSuspended) BOOL suspended

Discussion

 

When the value of this property is NO, the queue actively starts operations that are in the queue and ready to execute. Setting this property to YES prevents the queue from starting any queued operations, but already executing operations continue to execute. You may continue to add operations to a queue that is suspended but those operations are not scheduled for execution until you change this property to NO.

当这个属性的值是NO时，这个队列是活跃的开启队列中准备好的操作执行。这个属性设置为YES，可以阻止这个队列开启队列中的任何操作，但是已经执行的操作将继续执行。你依然可以往这个暂停的队列中添加操作，但是这些操作不会执行，直到将这个属性改为NO。

 

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.

当执行完成时，操作将从队列中移除。然而，为了执行完成，操作必须先开启。因为暂停的队列不会开启任何新的操作，当前不执行的队列中不会删除任何操作（包括已取消的操作）。

 

You may monitor changes to the value of this property using key-value observing. Configure an observer to monitor the suspended key path of the operation queue.

你可以使用key-value observing监控这个属性，观察suspended的key值。

 

The default value of this property is NO.

默认值是 NO。

 

Availability

Available in iOS 8.0 and later.

 

Configuring the Queue（队列配置）

underlyingQueue 

Property（属性）

The dispatch queue used to execute operations.

调度队列的常用执行操作。

Declaration

@property(assign) dispatch_queue_t underlyingQueue

 

Discussion

The default value of this property is nil. You can set the value of this property to an existing dispatch queue to have enqueued operations interspersed with blocks submitted to that dispatch queue.

这个属性的默认值是nil。你可以设置这个属性到现有的调度队列。。。

 

The value of this property should only be set if there are no operations in the queue; setting the value of this property when operationCount is not equal to 0 raises an NSInvalidArgumentException. The value of this property must not be the value returned by dispatch_get_main_queue. The quality-of-service level set for the underlying dispatch queue overrides any value set for the operation queue's qualityOfService property.

如果队列中没有操作，这个属性应该设置为这个值；当operationCount不等于0时，设置这个属性的值为NSInvalidArgumentException。这个属性的值不必返回dispatch_get_main_queue。服务质量等级设置在调度队列下面重写这个操作队列的qualityOfService属性任何值。

 

Availability

Available in iOS 8.0 and later.

 

 

name

 Property（属性）

The name of the operation queue.

操作队列的名称。

 

Declaration

@property(copy) NSString *name

Discussion

 

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.

这个名称为你的操作队列在运行时的识别提供了一种方法。当你在调试或分析你的代码的时候也可以作为一种用来提供额外关系的一种工具。

 

The default value of this property is “NSOperationQueue <id>”, where <id> is the memory address of the operation queue. You may monitor changes to the value of this property using key-value observing. Configure an observer to monitor the name key path of the operation queue.

这个属性的默认值是 “NSOperationQueue <id>”，<id>是操作队列的内存地址。你也可以使用 key-value observing来监视这个属性。设置监视器来监控name的key。

 

Availability

Available in iOS 4.0 and later.

 

Constants（常量）

Concurrent Operation Constants

Constant indicating the number of supported concurrent operations.

这个常量表示所支持同时执行操作的数量。

Declaration

enum { 

     NSOperationQueueDefaultMaxConcurrentOperationCount=-1

};

 

Constants

NSOperationQueueDefaultMaxConcurrentOperationCount

 

The default maximum number of operations is determined dynamically by the NSOperationQueue object based on current system conditions.

同时操作的默认最大数是基于当前系统条件的NSOperationQueue对象动态确定的。

•  
• Available in iOS 2.0 through iOS 8.4.
•