gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-04-23 09:04:13 +00:00
Code Issues Projects Releases Packages Wiki Activity

implement and document NSOperation

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@29476 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-MacDonald 2010-02-04 16:47:45 +00:00
parent 21e9e1231f
commit 1c11dee837
3 changed files with 549 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
ChangeLog
View file

@ -1,3 +1,10 @@
2010-02-04 Richard Frith-Macdonald <rfm@gnu.org>
* Headers/Foundation/NSOperation.h:
* Source/NSOperation.m:
Implement and document the NSOperation class.
As OSX 10.6 minus the objc2 specific 'block' methods.
2010-02-04 Richard Frith-Macdonald <rfm@gnu.org>
* Source/NSLock.m: cleanup indentation etc, and apply fix suggested

172
Headers/Foundation/NSOperation.h
View file

@ -1,8 +1,9 @@
/**Interface for NSOperation for GNUStep
Copyright (C) 2009 Free Software Foundation, Inc.
Copyright (C) 2009,2010 Free Software Foundation, Inc.
Written by: Gregory Casamento <greg.casamento@gmail.com>
Date: 2009
Written by: Richard Frith-Macdonald <rfm@gnu.org>
Date: 2009,2010
This file is part of the GNUstep Base Library.
@ -52,31 +53,123 @@ typedef NSInteger NSOperationQueuePriority;
id _internal;
}
// Initialization
- (id) init;
/** Adds a dependency to the receiver.<br />
* The receiver is not considered ready to execute until all of its
* dependencies have finished executing.<br />
* You must not add a particular object to the receiver more than once.<br />
* You must not create loops of dependencies (this would cause deadlock).<br />
*/
- (void) addDependency: (NSOperation *)op;
// Executing the operation
- (void) start;
- (void) main;
// Cancelling the operation
/** Marks the operation as cancelled (causes subsequent calls to the
* -isCancelled method to return YES).<br />
* 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.<br />
* If an operation in a queue is cancelled before it starts executing, it
* will be removed from the queue (though not necessarily immediately).<br />
* Calling this method on an object which has already finished executing
* has no effect.
*/
- (void) cancel;
// Getting the operation status
- (BOOL) isCancelled;
- (BOOL) isExecuting;
- (BOOL) isFinished;
- (BOOL) isConcurrent;
- (BOOL) isReady;
// Managing dependencies
- (void) addDependency: (NSOperation *)op;
- (void) removeDependency: (NSOperation *)op;
/** Returns all the dependencies of the receiver in the order in which they
* were added.
*/
- (NSArray *)dependencies;
// Prioritization
/** This method should return YES if the -cancel method has been called.<br />
* 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).<br />
* 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.<br />
* Also returns YES if the operation has been cancelled (even if there
* are unfinished dependencies).<br />
* An executing or finished operation is also considered to be ready.
*/
- (BOOL) isReady;
/** <override-subclass/>
* This is the method which actually performs the operation ...
* the default implementation does nothing.<br />
* 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.<br />
* The valid range is 0.0 to 1.0
*/
- (void) setThreadPriority: (double)prio;
#endif
/** This method is called to start execution of the receiver.<br />
* <p>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.<br />
* The subclass implementation must NOT call the superclass implementation.
* </p>
* <p>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.
* </p>
*/
- (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.<br />
* 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
@ -96,16 +189,43 @@ enum {
id _internal;
}
// status
/** Adds an operation to the receiver.
*/
- (void) addOperation: (NSOperation *)op;
/** Cancels all outstanding operations in the queue.
*/
- (void) cancelAllOperations;
/** Returns a flag indicating whether the queue is currently suspended.
*/
- (BOOL) isSuspended;
- (void) setSuspended: (BOOL)flag;
/** Returns the value set using the -setMaxConcurrentOperationCount:
* method, or NSOperationQueueDefaultMaxConcurrentOperationCount if
* none has been set.<br />
*/
- (NSInteger) maxConcurrentOperationCount;
/** Returns all the operations currently in the queue.
*/
- (NSArray *) operations;
/** Sets the number of concurrent operations permitted.<br />
* The default (NSOperationQueueDefaultMaxConcurrentOperationCount)
* means that the queue should decide how many it does based on
* system load etc.
*/
- (void) setMaxConcurrentOperationCount: (NSInteger)cnt;
// operations
- (void) addOperation: (NSOperation *) op;
- (NSArray *) operations;
- (void) cancelAllOperations;
/** 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

482
Source/NSOperation.m
View file

@ -1,8 +1,9 @@
/**Implementation for NSOperation for GNUStep
Copyright (C) 2009 Free Software Foundation, Inc.
Copyright (C) 2009,2010 Free Software Foundation, Inc.
Written by: Gregory Casamento <greg.casamento@gmail.com>
Date: 2009
Written by: Richard Frith-Macdonald <rfm@gnu.org>
Date: 2009,2010
This file is part of the GNUstep Base Library.
@ -28,13 +29,20 @@
#import "config.h"
#import "Foundation/NSOperation.h"
#import "Foundation/NSArray.h"
#import "Foundation/NSAutoreleasePool.h"
#import "Foundation/NSEnumerator.h"
#import "Foundation/NSException.h"
#import "Foundation/NSLock.h"
#import "Foundation/NSKeyValueObserving.h"
#import "Foundation/NSThread.h"
#define GSInternal NSOperationInternal
#include "GSInternal.h"
GS_BEGIN_INTERNAL(NSOperation)
NSRecursiveLock *lock;
NSConditionLock *cond;
NSOperationQueuePriority priority;
double threadPriority;
BOOL cancelled;
BOOL concurrent;
BOOL executing;
@ -43,121 +51,402 @@ GS_BEGIN_INTERNAL(NSOperation)
NSMutableArray *dependencies;
GS_END_INTERNAL(NSOperation)
static NSArray *empty = nil;
@implementation NSOperation : NSObject
+ (BOOL) automaticallyNotifiesObserversForKey: (NSString*)theKey
{
/* Handle all KVO manually
*/
return NO;
}
+ (void) initialize
{
empty = [NSArray new];
}
- (void) addDependency: (NSOperation *)op
{
if (NO == [op isKindOfClass: [self class]])
{
[NSException raise: NSInvalidArgumentException
format: @"[%@-%@] dependency is not an NSOperation",
NSStringFromClass([self class]), NSStringFromSelector(_cmd)];
}
if (op == self)
{
[NSException raise: NSInvalidArgumentException
format: @"[%@-%@] attempt to add dependency on self",
NSStringFromClass([self class]), NSStringFromSelector(_cmd)];
}
[internal->lock lock];
if (internal->dependencies == nil)
{
internal->dependencies = [[NSMutableArray alloc] initWithCapacity: 5];
}
NS_DURING
{
if (NO == [internal->dependencies containsObject: op])
{
[self willChangeValueForKey: @"dependencies"];
[internal->dependencies addObject: op];
/* We only need to watch for changes if it's possible for them to
* happen and make a difference.
*/
if (NO == [op isFinished]
&& NO == [self isCancelled]
&& NO == [self isExecuting]
&& NO == [self isFinished])
{
/* Can change readiness if we are neither cancelled nor
* executing nor finished. So we need to observe for the
* finish of the dependency.
*/
[op addObserver: self
forKeyPath: @"isFinished"
options: NSKeyValueObservingOptionNew
context: NULL];
if (internal->ready == YES)
{
/* The new dependency stops us being ready ...
* change state.
*/
[self willChangeValueForKey: @"isReady"];
internal->ready = NO;
[self didChangeValueForKey: @"isReady"];
}
}
[self didChangeValueForKey: @"dependencies"];
}
}
NS_HANDLER
{
[internal->lock unlock];
NSLog(@"Problem adding dependency: %@", localException);
return;
}
NS_ENDHANDLER
[internal->lock unlock];
}
- (void) cancel
{
if (NO == internal->cancelled && NO == [self isFinished])
{
[internal->lock lock];
if (NO == internal->cancelled && NO == [self isFinished])
{
NS_DURING
{
[self willChangeValueForKey: @"isCancelled"];
internal->cancelled = YES;
if (NO == internal->ready)
{
[self willChangeValueForKey: @"isReady"];
internal->ready = YES;
[self didChangeValueForKey: @"isReady"];
}
[self didChangeValueForKey: @"isCancelled"];
}
NS_HANDLER
{
[internal->lock unlock];
NSLog(@"Problem cancelling operation: %@", localException);
return;
}
NS_ENDHANDLER
}
[internal->lock unlock];
}
}
- (void) dealloc
{
if (internal != nil)
{
NSOperation *op;
while ((op = [internal->dependencies lastObject]) != nil)
{
[self removeDependency: op];
}
RELEASE(internal->dependencies);
RELEASE(internal->cond);
RELEASE(internal->lock);
GS_DESTROY_INTERNAL(NSOperation);
}
[super dealloc];
}
- (NSArray *) dependencies
{
NSArray *a;
if (internal->dependencies == nil)
{
a = empty; // OSX return an empty array
}
else
{
[internal->lock lock];
a = [NSArray arrayWithArray: internal->dependencies];
[internal->lock unlock];
}
return a;
}
- (id) init
{
if ((self = [super init]) != nil)
{
GS_CREATE_INTERNAL(NSOperation);
internal->priority = NSOperationQueuePriorityNormal;
internal->dependencies = [[NSMutableArray alloc] initWithCapacity: 5];
internal->threadPriority = 0.5;
internal->ready = YES;
internal->lock = [NSRecursiveLock new];
internal->cond = [[NSConditionLock alloc] initWithCondition: 0];
}
return self;
}
// Executing the operation
- (void) start
{
internal->executing = YES;
internal->finished = NO;
if ([self isConcurrent])
{
[self main];
}
else
{
NS_DURING
{
[self main];
}
NS_HANDLER
{
NSLog(@"%@",[localException reason]);
}
NS_ENDHANDLER;
}
internal->executing = NO;
internal->finished = YES;
}
- (void) main;
{
// subclass responsibility...
[self subclassResponsibility: _cmd];
}
// Cancelling the operation
- (void) cancel
{
[self subclassResponsibility: _cmd];
}
// Getting the operation status
- (BOOL) isCancelled
{
return NO;
return internal->cancelled;
}
- (BOOL) isExecuting
{
return NO;
return internal->executing;
}
- (BOOL) isFinished
{
return NO;
return internal->finished;
}
- (BOOL) isConcurrent
{
return NO;
return internal->concurrent;
}
- (BOOL) isReady
{
return NO;
return internal->ready;
}
// Managing dependencies
- (void) addDependency: (NSOperation *)op
- (void) main;
{
[internal->dependencies addObject: op];
return; // OSX default implementation does nothing
}
- (void) removeDependency: (NSOperation *)op
- (void) observeValueForKeyPath: (NSString *)keyPath
ofObject: (id)object
change: (NSDictionary *)change
context: (void *)context
{
[internal->dependencies removeObject: op];
/* Some dependency has finished (or been removed) ...
* so we need to check to see if we are now ready unless we know we are.
* This is protected by locks so that an update due to an observed
* change in one thread won't interrupt anything in another thread.
*/
[internal->lock lock];
if (NO == internal->ready)
{
NSEnumerator *en;
NSOperation *op;
en = [internal->dependencies objectEnumerator];
while ((op = [en nextObject]) != nil)
{
if (NO == [op isReady])
break;
}
if (op == nil)
{
[self willChangeValueForKey: @"isReady"];
internal->ready = YES;
[self didChangeValueForKey: @"isReady"];
}
}
[internal->lock unlock];
}
- (NSArray *) dependencies
{
return [NSArray arrayWithArray: internal->dependencies];
}
// Prioritization
- (NSOperationQueuePriority) queuePriority
{
return internal->priority;
}
- (void) removeDependency: (NSOperation *)op
{
[internal->lock lock];
NS_DURING
{
if (YES == [internal->dependencies containsObject: op])
{
[op removeObserver: self
forKeyPath: @"isFinished"];
[self willChangeValueForKey: @"dependencies"];
[internal->dependencies removeObject: op];
if (NO == internal->ready)
{
/* The dependency may cause us to become ready ...
* fake an observation so we can deal with that.
*/
[self observeValueForKeyPath: @"isFinished"
ofObject: op
change: nil
context: nil];
}
[self didChangeValueForKey: @"dependencies"];
}
}
NS_HANDLER
{
[internal->lock unlock];
NSLog(@"Problem removing dependency: %@", localException);
return;
}
NS_ENDHANDLER
[internal->lock unlock];
}
- (void) setQueuePriority: (NSOperationQueuePriority)pri
{
internal->priority = pri;
if (pri < NSOperationQueuePriorityVeryLow)
pri = NSOperationQueuePriorityVeryLow;
else if (pri < NSOperationQueuePriorityLow)
pri = NSOperationQueuePriorityLow;
else if (pri < NSOperationQueuePriorityNormal)
pri = NSOperationQueuePriorityNormal;
else if (pri > NSOperationQueuePriorityVeryHigh)
pri = NSOperationQueuePriorityVeryHigh;
else if (pri > NSOperationQueuePriorityHigh)
pri = NSOperationQueuePriorityHigh;
else if (pri > NSOperationQueuePriorityNormal)
pri = NSOperationQueuePriorityNormal;
if (pri != internal->priority)
{
[internal->lock lock];
if (pri != internal->priority)
{
NS_DURING
{
[self willChangeValueForKey: @"queuePriority"];
internal->priority = pri;
[self didChangeValueForKey: @"queuePriority"];
}
NS_HANDLER
{
[internal->lock unlock];
NSLog(@"Problem setting priority: %@", localException);
return;
}
NS_ENDHANDLER
}
[internal->lock unlock];
}
}
- (void) setThreadPriority: (double)pri
{
if (pri > 1) pri = 1;
else if (pri < 0) pri = 0;
internal->threadPriority = pri;
}
- (void) start
{
CREATE_AUTORELEASE_POOL(pool);
NSException *e = nil;
[internal->lock lock];
NS_DURING
{
if (YES == [self isConcurrent])
{
[NSException raise: NSInvalidArgumentException
format: @"[%@-%@] called on concurrent operation",
NSStringFromClass([self class]), NSStringFromSelector(_cmd)];
}
if (YES == [self isExecuting])
{
[NSException raise: NSInvalidArgumentException
format: @"[%@-%@] called on executing operation",
NSStringFromClass([self class]), NSStringFromSelector(_cmd)];
}
if (YES == [self isFinished])
{
[NSException raise: NSInvalidArgumentException
format: @"[%@-%@] called on finished operation",
NSStringFromClass([self class]), NSStringFromSelector(_cmd)];
}
if (NO == [self isReady])
{
[NSException raise: NSInvalidArgumentException
format: @"[%@-%@] called on operation which is not ready",
NSStringFromClass([self class]), NSStringFromSelector(_cmd)];
}
[self willChangeValueForKey: @"isExecuting"];
internal->executing = YES;
[self didChangeValueForKey: @"isExecuting"];
NS_DURING
{
if (NO == [self isCancelled])
{
double prio = [NSThread threadPriority];
[NSThread setThreadPriority: internal->threadPriority];
[self main];
[NSThread setThreadPriority: prio];
}
}
NS_HANDLER
{
e = localException;
}
NS_ENDHANDLER;
/* Notify KVO system of changes to isExecuting and isFinished
*/
[self willChangeValueForKey: @"isExecuting"];
[self willChangeValueForKey: @"isFinished"];
internal->executing = NO;
internal->finished = YES;
[self didChangeValueForKey: @"isFinished"];
[self didChangeValueForKey: @"isExecuting"];
[internal->cond lock];
[internal->cond unlockWithCondition: 1];
}
NS_HANDLER
{
if (e == nil)
{
e = localException;
}
}
NS_ENDHANDLER
[internal->lock unlock];
if (e != nil)
{
[e raise];
}
RELEASE(pool);
}
- (double) threadPriority
{
return internal->threadPriority;
}
- (void) waitUntilFinished
{
[internal->cond lockWhenCondition: 1]; // Wait for finish
[internal->cond unlockWithCondition: 1]; // Signal any other watchers
}
@end
@ -166,6 +455,7 @@ GS_END_INTERNAL(NSOperation)
#define GSInternal NSOperationQueueInternal
#include "GSInternal.h"
GS_BEGIN_INTERNAL(NSOperationQueue)
NSRecursiveLock *lock;
NSMutableArray *operations;
BOOL suspended;
NSInteger count;
@ -174,11 +464,43 @@ GS_END_INTERNAL(NSOperationQueue)
@implementation NSOperationQueue
- (void) addOperation: (NSOperation *)op
{
if (op == nil || NO == [op isKindOfClass: [NSOperation class]])
{
[NSException raise: NSInvalidArgumentException
format: @"[%@-%@] object is not an NSOperation",
NSStringFromClass([self class]), NSStringFromSelector(_cmd)];
}
[internal->lock lock];
if (NO == [internal->operations containsObject: op])
{
[internal->operations addObject: op];
// FIXME ... start if we can
}
[internal->lock unlock];
}
- (void) cancelAllOperations
{
NSEnumerator *en;
id o;
[internal->lock lock];
en = [internal->operations objectEnumerator];
while ((o = [en nextObject]) != nil)
{
[o cancel];
}
[internal->lock unlock];
}
- (void) dealloc
{
if (_internal != nil)
{
[internal->operations release];
[internal->lock release];
GS_DESTROY_INTERNAL(NSOperationQueue);
}
[super dealloc];
@ -192,51 +514,39 @@ GS_END_INTERNAL(NSOperationQueue)
internal->suspended = NO;
internal->count = NSOperationQueueDefaultMaxConcurrentOperationCount;
internal->operations = [NSMutableArray new];
internal->lock = [NSRecursiveLock new];
}
return self;
}
// status
- (BOOL) isSuspended
{
return internal->suspended;
}
- (void) setSuspended: (BOOL)flag
{
internal->suspended = flag;
}
- (NSInteger) maxConcurrentOperationCount
{
return internal->count;
}
- (NSArray *) operations
{
NSArray *a;
[internal->lock lock];
a = [NSArray arrayWithArray: internal->operations];
[internal->lock unlock];
return a;
}
- (void) setMaxConcurrentOperationCount: (NSInteger)cnt
{
internal->count = cnt;
}
// operations
- (void) addOperation: (NSOperation *) op
- (void) setSuspended: (BOOL)flag
{
[internal->operations addObject: op];
}
- (NSArray *) operations
{
return [NSArray arrayWithArray: internal->operations];
}
- (void) cancelAllOperations
{
NSEnumerator *en = [internal->operations objectEnumerator];
id o = nil;
while ((o = [en nextObject]) != nil)
{
[o cancel];
}
internal->suspended = flag;
}
- (void) waitUntilAllOperationsAreFinished