/**Interface for NSOperation for GNUStep Copyright (C) 2009,2010 Free Software Foundation, Inc. Written by: Gregory Casamento Written by: Richard Frith-Macdonald Date: 2009,2010 This file is part of the GNUstep Base Library. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA. */ #ifndef __NSOperation_h_GNUSTEP_BASE_INCLUDE #define __NSOperation_h_GNUSTEP_BASE_INCLUDE #import #if OS_API_VERSION(100500, GS_API_LATEST) #if defined(__cplusplus) extern "C" { #endif @class NSMutableArray; enum { NSOperationQueuePriorityVeryLow = -8, NSOperationQueuePriorityLow = -4, NSOperationQueuePriorityNormal = 0, NSOperationQueuePriorityHigh = 4, NSOperationQueuePriorityVeryHigh = 8 }; typedef NSInteger NSOperationQueuePriority; @interface NSOperation : NSObject { #if GS_EXPOSE(NSOperation) @private id _internal; #endif } /** 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).
*/ - (void) addDependency: (NSOperation *)op; /** 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. */ - (void) cancel; /** Returns all the dependencies of the receiver in the order in which they * were added. */ - (NSArray *)dependencies; /** This method should return YES if the -cancel method has been called.
* NB. a cancelled operation may still be executing. */ - (BOOL) isCancelled; /** 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. */ - (BOOL) isConcurrent; /** This method should return YES if the receiver is currently executing its * -main method (even if -cancel has been called). */ - (BOOL) isExecuting; /** 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). */ - (BOOL) isFinished; /** 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. */ - (BOOL) isReady; /** * 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. */ - (void) main; /** Returns the priority set using the -setQueuePriority method, or * NSOperationQueuePriorityNormal if no priority has been set. */ - (NSOperationQueuePriority) queuePriority; /** Removes a dependency from the receiver. */ - (void) removeDependency: (NSOperation *)op; /** 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. */ - (void) setQueuePriority: (NSOperationQueuePriority)priority; #if OS_API_VERSION(100600, GS_API_LATEST) /** 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 */ - (void) setThreadPriority: (double)prio; #endif /** 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. *

*/ - (void) start; #if OS_API_VERSION(100600, GS_API_LATEST) /** Returns the thread priority to be used executing the -main method. * The default is 0.5 */ - (double) threadPriority; /** 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. */ - (void) waitUntilFinished; #endif @end /** * NSOperationQueue */ // Enumerated type for default operation count. enum { NSOperationQueueDefaultMaxConcurrentOperationCount = -1 }; @interface NSOperationQueue : NSObject { #if GS_EXPOSE(NSOperationQueue) @private id _internal; #endif } #if OS_API_VERSION(100600, GS_API_LATEST) /** 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. */ + (id) currentQueue; /** Returns the default queue on the main thread. */ + (id) mainQueue; #endif /** Adds an operation to the receiver. */ - (void) addOperation: (NSOperation *)op; #if OS_API_VERSION(100600, GS_API_LATEST) /** Adds multiple operations to the receiver and (optionally) waits for * all the operations in the queue to finish. */ - (void) addOperations: (NSArray *)ops waitUntilFinished: (BOOL)shouldWait; #endif /** Cancels all outstanding operations in the queue. */ - (void) cancelAllOperations; /** Returns a flag indicating whether the queue is currently suspended. */ - (BOOL) isSuspended; /** Returns the value set using the -setMaxConcurrentOperationCount: * method, or NSOperationQueueDefaultMaxConcurrentOperationCount if * none has been set.
*/ - (NSInteger) maxConcurrentOperationCount; #if OS_API_VERSION(100600, GS_API_LATEST) /** Return the name of this operation queue. */ - (NSString*) name; /** Return the number of operations in the queue at an instant. */ - (NSUInteger) operationCount; #endif /** Returns all the operations in the queue at an instant. */ - (NSArray *) operations; /** 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. */ - (void) setMaxConcurrentOperationCount: (NSInteger)cnt; #if OS_API_VERSION(100600, GS_API_LATEST) /** Sets the name for this operation queue. */ - (void) setName: (NSString*)s; #endif /** Marks the receiver as suspended ... while suspended an operation queue * will not start any more operations. */ - (void) setSuspended: (BOOL)flag; /** Waits until all operations in the queue have finished (or been cancelled * and removed from the queue). */ - (void) waitUntilAllOperationsAreFinished; @end #if defined(__cplusplus) } #endif #endif #endif /* __NSOperation_h_GNUSTEP_BASE_INCLUDE */