Up

NSOperation class reference

Authors

Gregory Casamento (greg.casamento@gmail.com)
Richard Frith-Macdonald (rfm@gnu.org)

Date: Generated at 2023-12-20 19:35:39 -0500

Copyright: (C) 2008-2022 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSBlockOperation class
  2. Software documentation for the NSOperation class
  3. Software documentation for the NSOperationQueue class

Software documentation for the NSBlockOperation class

NSBlockOperation : NSOperation

Declared in:
Foundation/NSOperation.h
Availability: MacOS-X 10.5.0

Description forthcoming.
Method summary

blockOperationWithBlock: 

+ (instancetype) blockOperationWithBlock: (GSBlockOperationBlock)block;
Availability: MacOS-X 10.5.0

Description forthcoming.

addExecutionBlock: 

- (void) addExecutionBlock: (GSBlockOperationBlock)block;
Availability: MacOS-X 10.5.0

Description forthcoming.

executionBlocks 

- (NSArray*) executionBlocks;
Availability: MacOS-X 10.5.0

Description forthcoming.

Software documentation for the NSOperation class

NSOperation : NSObject

Declared in:
Foundation/NSOperation.h
Availability: MacOS-X 10.5.0

Description forthcoming.
Method summary

addDependency: 

- (void) addDependency: (NSOperation*)op;
Availability: MacOS-X 10.5.0

Adds a dependency to the receiver.
The receiver is not considered ready to execute until all of its dependencies have finished executing.
You must not add a particular object to the receiver more than once.
You must not create loops of dependencies (this would cause deadlock).

cancel 

- (void) cancel;
Availability: MacOS-X 10.5.0

Marks the operation as cancelled (causes subsequent calls to the -isCancelled method to return YES).
This does not directly cause the receiver to stop executing... it is the responsibility of the receiver to call -isCancelled while executing and act accordingly.
If an operation in a queue is cancelled before it starts executing, it will be removed from the queue (though not necessarily immediately).
Calling this method on an object which has already finished executing has no effect.

completionBlock 

- (GSOperationCompletionBlock) completionBlock;
Availability: MacOS-X 10.6.0

Returns the block that will be executed after the operation finishes.

dependencies 

- (NSArray*) dependencies;
Availability: MacOS-X 10.5.0

Returns all the dependencies of the receiver in the order in which they were added.

isCancelled 

- (BOOL) isCancelled;
Availability: MacOS-X 10.5.0

This method should return YES if the -cancel method has been called.
NB. a cancelled operation may still be executing.

isConcurrent 

- (BOOL) isConcurrent;
Availability: MacOS-X 10.5.0

This method returns YES if the receiver handles its own environment or threading rather than expecting to run in an evironment set up elsewhere (eg, by an NSOperationQueue instance).
The default implementation returns NO.

isExecuting 

- (BOOL) isExecuting;
Availability: MacOS-X 10.5.0

This method should return YES if the receiver is currently executing its -main method (even if -cancel has been called).

isFinished 

- (BOOL) isFinished;
Availability: MacOS-X 10.5.0

This method should return YES if the receiver has finished executing its -main method (irrespective of whether the execution completed due to cancellation, failure, or success).

isReady 

- (BOOL) isReady;
Availability: MacOS-X 10.5.0

This method should return YES when the receiver is ready to begin executing. That is, the receiver must have no dependencies which have not finished executing.
Also returns YES if the operation has been cancelled (even if there are unfinished dependencies).
An executing or finished operation is also considered to be ready.

main 

- (void) main;
Availability: MacOS-X 10.5.0

Subclasses must override this method.
This is the method which actually performs the operation... the default implementation does nothing.
You MUST ensure that your implemention of -main does not raise any exception or call [NSThread +exit] as either of these will terminate the operation prematurely resulting in the operation never reaching the -isFinished state.
If you are writing a concurrent subclass, you should override -start instead of (or as well as) the -main method.

queuePriority 

- (NSOperationQueuePriority) queuePriority;
Availability: MacOS-X 10.5.0

Returns the priority set using the -setQueuePriority: method, or NSOperationQueuePriorityNormal if no priority has been set.

removeDependency: 

- (void) removeDependency: (NSOperation*)op;
Availability: MacOS-X 10.5.0

Removes a dependency from the receiver.

setCompletionBlock: 

- (void) setCompletionBlock: (GSOperationCompletionBlock)aBlock;
Availability: MacOS-X 10.6.0

Sets the block that will be executed when the operation has finished.

setQueuePriority: 

- (void) setQueuePriority: (NSOperationQueuePriority)priority;
Availability: MacOS-X 10.5.0

Sets the priority for the receiver. If the value supplied is not one of the predefined queue priorities, it is converted into the next available defined value moving towards NSOperationQueuePriorityNormal.

setThreadPriority: 

- (void) setThreadPriority: (double)prio;
Availability: MacOS-X 10.6.0

Sets the thread priority to be used while executing then -main method. The priority change is implemented in the -start method, so if you are replacing -start you are responsible for managing this.
The valid range is 0.0 to 1.0

start 

- (void) start;
Availability: MacOS-X 10.5.0

This method is called to start execution of the receiver.

For concurrent operations, the subclass must override this method to set up the environment for the operation to execute, must execute the -main method, must ensure that -isExecuting and -isFinished return the correct values, and must manually call key-value-observing methods to notify observers of the state of those two properties.
The subclass implementation must NOT call the superclass implementation.

For non-concurrent operations, the default implementation of this method performs all the work of setting up environment etc, and the subclass only needs to override the -main method.


threadPriority 

- (double) threadPriority;
Availability: MacOS-X 10.6.0

Returns the thread priority to be used executing the -main method. The default is 0.5

waitUntilFinished 

- (void) waitUntilFinished;
Availability: MacOS-X 10.6.0

This method blocks the current thread until the receiver finishes.
Care must be taken to avoid deadlock... you must not call this method from the same thread that the receiver started in.

Software documentation for the NSOperationQueue class

NSOperationQueue : NSObject

Declared in:
Foundation/NSOperation.h
Availability: MacOS-X 10.5.0

Description forthcoming.
Method summary

currentQueue 

+ (id) currentQueue;
Availability: MacOS-X 10.6.0

If called from within the -main method of an operation which is currently being executed by a queue, this returns the queue instance in use.

mainQueue 

+ (id) mainQueue;
Availability: MacOS-X 10.6.0

Returns the default queue on the main thread.

addOperation: 

- (void) addOperation: (NSOperation*)op;
Availability: MacOS-X 10.5.0

Adds an operation to the receiver.

addOperationWithBlock: 

- (void) addOperationWithBlock: (GSBlockOperationBlock)block;
Availability: MacOS-X 10.6.0

This method wraps a block in an operation and adds it to the queue.

addOperations: waitUntilFinished: 

- (void) addOperations: (NSArray*)ops waitUntilFinished: (BOOL)shouldWait;
Availability: MacOS-X 10.6.0

Adds multiple operations to the receiver and (optionally) waits for all the operations in the queue to finish.

cancelAllOperations 

- (void) cancelAllOperations;
Availability: MacOS-X 10.5.0

Cancels all outstanding operations in the queue.

isSuspended 

- (BOOL) isSuspended;
Availability: MacOS-X 10.5.0

Returns a flag indicating whether the queue is currently suspended.

maxConcurrentOperationCount 

- (NSInteger) maxConcurrentOperationCount;
Availability: MacOS-X 10.5.0

Returns the value set using the -setMaxConcurrentOperationCount: method, or NSOperationQueueDefaultMaxConcurrentOperationCount if none has been set.

name 

- (NSString*) name;
Availability: MacOS-X 10.6.0

Return the name of this operation queue.

operationCount 

- (NSUInteger) operationCount;
Availability: MacOS-X 10.6.0

Return the number of operations in the queue at an instant.

operations 

- (NSArray*) operations;
Availability: MacOS-X 10.5.0

Returns all the operations in the queue at an instant.

setMaxConcurrentOperationCount: 

- (void) setMaxConcurrentOperationCount: (NSInteger)cnt;
Availability: MacOS-X 10.5.0

Sets the number of concurrent operations permitted.
The default (NSOperationQueueDefaultMaxConcurrentOperationCount) means that the queue should decide how many it does based on system load etc.

setName: 

- (void) setName: (NSString*)s;
Availability: MacOS-X 10.6.0

Sets the name for this operation queue.

setSuspended: 

- (void) setSuspended: (BOOL)flag;
Availability: MacOS-X 10.5.0

Marks the receiver as suspended... while suspended an operation queue will not start any more operations.

waitUntilAllOperationsAreFinished 

- (void) waitUntilAllOperationsAreFinished;
Availability: MacOS-X 10.5.0

Waits until all operations in the queue have finished (or been cancelled and removed from the queue).


Up