/* =============================================================================
FILE: UKKQueue.m
PROJECT: Filie
COPYRIGHT: (c) 2003 M. Uli Kusterer, all rights reserved.
AUTHORS: M. Uli Kusterer - UK
LICENSES: MIT License
REVISIONS:
2006-03-13 UK Clarified license, streamlined UKFileWatcher stuff,
Changed notifications to be useful and turned off by
default some deprecated stuff.
2004-12-28 UK Several threading fixes.
2003-12-21 UK Created.
========================================================================== */
// -----------------------------------------------------------------------------
// Headers:
// -----------------------------------------------------------------------------
#import "UKKQueue.h"
#import "UKMainThreadProxy.h"
#import <unistd.h>
#import <fcntl.h>
// -----------------------------------------------------------------------------
// Macros:
// -----------------------------------------------------------------------------
// @synchronized isn't available prior to 10.3, so we use a typedef so
// this class is thread-safe on Panther but still compiles on older OSs.
#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_3
#define AT_SYNCHRONIZED(n) @synchronized(n)
#else
#define AT_SYNCHRONIZED(n)
#endif
// -----------------------------------------------------------------------------
// Globals:
// -----------------------------------------------------------------------------
static UKKQueue * gUKKQueueSharedQueueSingleton = nil;
@implementation UKKQueue
// Deprecated:
#if UKKQUEUE_OLD_SINGLETON_ACCESSOR_NAME
+(UKKQueue*) sharedQueue
{
return [self sharedFileWatcher];
}
#endif
// -----------------------------------------------------------------------------
// sharedQueue:
// Returns a singleton queue object. In many apps (especially those that
// subscribe to the notifications) there will only be one kqueue instance,
// and in that case you can use this.
//
// For all other cases, feel free to create additional instances to use
// independently.
//
// REVISIONS:
// 2006-03-13 UK Renamed from sharedQueue.
// 2005-07-02 UK Created.
// -----------------------------------------------------------------------------
+(id) sharedFileWatcher
{
AT_SYNCHRONIZED( self )
{
if( !gUKKQueueSharedQueueSingleton )
gUKKQueueSharedQueueSingleton = [[UKKQueue alloc] init]; // This is a singleton, and thus an intentional "leak".
}
return gUKKQueueSharedQueueSingleton;
}
// -----------------------------------------------------------------------------
// * CONSTRUCTOR:
// Creates a new KQueue and starts that thread we use for our
// notifications.
//
// REVISIONS:
// 2004-11-12 UK Doesn't pass self as parameter to watcherThread anymore,
// because detachNewThreadSelector retains target and args,
// which would cause us to never be released.
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(id) init
{
self = [super init];
if( self )
{
queueFD = kqueue();
if( queueFD == -1 )
{
[self release];
return nil;
}
watchedPaths = [[NSMutableArray alloc] init];
watchedFDs = [[NSMutableArray alloc] init];
// Start new thread that fetches and processes our events:
keepThreadRunning = YES;
[NSThread detachNewThreadSelector:@selector(watcherThread:) toTarget:self withObject:nil];
}
return self;
}
// -----------------------------------------------------------------------------
// release:
// Since NSThread retains its target, we need this method to terminate the
// thread when we reach a retain-count of two. The thread is terminated by
// setting keepThreadRunning to NO.
//
// REVISIONS:
// 2004-11-12 UK Created.
// -----------------------------------------------------------------------------
-(oneway void) release
{
AT_SYNCHRONIZED(self)
{
//NSLog(@"%@ (%d)", self, [self retainCount]);
if( [self retainCount] == 2 && keepThreadRunning )
keepThreadRunning = NO;
}
[super release];
}
// -----------------------------------------------------------------------------
// * DESTRUCTOR:
// Releases the kqueue again.
//
// REVISIONS:
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(void) dealloc
{
delegate = nil;
[delegateProxy release];
if( keepThreadRunning )
keepThreadRunning = NO;
// Close all our file descriptors so the files can be deleted:
NSEnumerator* enny = [watchedFDs objectEnumerator];
NSNumber* fdNum;
while( (fdNum = [enny nextObject]) )
{
if( close( [fdNum intValue] ) == -1 )
NSLog(@"dealloc: Couldn't close file descriptor (%d)", errno);
}
[watchedPaths release];
watchedPaths = nil;
[watchedFDs release];
watchedFDs = nil;
[super dealloc];
//NSLog(@"kqueue released.");
}
// -----------------------------------------------------------------------------
// queueFD:
// Returns a Unix file descriptor for the KQueue this uses. The descriptor
// is owned by this object. Do not close it!
//
// REVISIONS:
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(int) queueFD
{
return queueFD;
}
// -----------------------------------------------------------------------------
// addPathToQueue:
// Tell this queue to listen for all interesting notifications sent for
// the object at the specified path. If you want more control, use the
// addPathToQueue:notifyingAbout: variant instead.
//
// REVISIONS:
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(void) addPathToQueue: (NSString*)path
{
[self addPath: path];
}
-(void) addPath: (NSString*)path
{
[self addPathToQueue: path notifyingAbout: UKKQueueNotifyAboutRename
| UKKQueueNotifyAboutWrite
| UKKQueueNotifyAboutDelete
| UKKQueueNotifyAboutAttributeChange];
}
// -----------------------------------------------------------------------------
// addPathToQueue:notfyingAbout:
// Tell this queue to listen for the specified notifications sent for
// the object at the specified path.
//
// REVISIONS:
// 2005-06-29 UK Files are now opened using O_EVTONLY instead of O_RDONLY
// which allows ejecting or deleting watched files/folders.
// Thanks to Phil Hargett for finding this flag in the docs.
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(void) addPathToQueue: (NSString*)path notifyingAbout: (u_int)fflags
{
struct timespec nullts = { 0, 0 };
struct kevent ev;
int fd = open( [path fileSystemRepresentation], O_EVTONLY, 0 );
if( fd >= 0 )
{
EV_SET( &ev, fd, EVFILT_VNODE,
EV_ADD | EV_ENABLE | EV_CLEAR,
fflags, 0, (void*)path );
AT_SYNCHRONIZED( self )
{
[watchedPaths addObject: path];
[watchedFDs addObject: [NSNumber numberWithInt: fd]];
kevent( queueFD, &ev, 1, NULL, 0, &nullts );
}
}
}
-(void) removePath: (NSString*)path
{
[self removePathFromQueue: path];
}
// -----------------------------------------------------------------------------
// removePathFromQueue:
// Stop listening for changes to the specified path. This removes all
// notifications. Use this to balance both addPathToQueue:notfyingAbout:
// as well as addPathToQueue:.
//
// REVISIONS:
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(void) removePathFromQueue: (NSString*)path
{
int index = 0;
int fd = -1;
AT_SYNCHRONIZED( self )
{
index = [watchedPaths indexOfObject: path];
if( index == NSNotFound )
return;
fd = [[watchedFDs objectAtIndex: index] intValue];
[watchedFDs removeObjectAtIndex: index];
[watchedPaths removeObjectAtIndex: index];
}
if( close( fd ) == -1 )
NSLog(@"removePathFromQueue: Couldn't close file descriptor (%d)", errno);
}
// -----------------------------------------------------------------------------
// removeAllPathsFromQueue:
// Stop listening for changes to all paths. This removes all
// notifications.
//
// REVISIONS:
// 2004-12-28 UK Added as suggested by bbum.
// -----------------------------------------------------------------------------
-(void) removeAllPathsFromQueue;
{
AT_SYNCHRONIZED( self )
{
NSEnumerator * fdEnumerator = [watchedFDs objectEnumerator];
NSNumber * anFD;
while( (anFD = [fdEnumerator nextObject]) != nil )
close( [anFD intValue] );
[watchedFDs removeAllObjects];
[watchedPaths removeAllObjects];
}
}
// -----------------------------------------------------------------------------
// watcherThread:
// This method is called by our NSThread to loop and poll for any file
// changes that our kqueue wants to tell us about. This sends separate
// notifications for the different kinds of changes that can happen.
// All messages are sent via the postNotification:forFile: main bottleneck.
//
// This also calls sharedWorkspace's noteFileSystemChanged.
//
// To terminate this method (and its thread), set keepThreadRunning to NO.
//
// REVISIONS:
// 2005-08-27 UK Changed to use keepThreadRunning instead of kqueueFD
// being -1 as termination criterion, and to close the
// queue in this thread so the main thread isn't blocked.
// 2004-11-12 UK Fixed docs to include termination criterion, added
// timeout to make sure the bugger gets disposed.
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(void) watcherThread: (id)sender
{
int n;
struct kevent ev;
struct timespec timeout = { 5, 0 }; // 5 seconds timeout.
int theFD = queueFD; // So we don't have to risk accessing iVars when the thread is terminated.
while( keepThreadRunning )
{
NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];
NS_DURING
n = kevent( queueFD, NULL, 0, &ev, 1, &timeout );
if( n > 0 )
{
if( ev.filter == EVFILT_VNODE )
{
if( ev.fflags )
{
NSString* fpath = [[(NSString *)ev.udata retain] autorelease]; // In case one of the notified folks removes the path.
//NSLog(@"UKKQueue: Detected file change: %@", fpath);
[[NSWorkspace sharedWorkspace] noteFileSystemChanged: fpath];
//NSLog(@"ev.flags = %u",ev.fflags); // DEBUG ONLY!
if( (ev.fflags & NOTE_RENAME) == NOTE_RENAME )
[self postNotification: UKFileWatcherRenameNotification forFile: fpath];
if( (ev.fflags & NOTE_WRITE) == NOTE_WRITE )
[self postNotification: UKFileWatcherWriteNotification forFile: fpath];
if( (ev.fflags & NOTE_DELETE) == NOTE_DELETE )
[self postNotification: UKFileWatcherDeleteNotification forFile: fpath];
if( (ev.fflags & NOTE_ATTRIB) == NOTE_ATTRIB )
[self postNotification: UKFileWatcherAttributeChangeNotification forFile: fpath];
if( (ev.fflags & NOTE_EXTEND) == NOTE_EXTEND )
[self postNotification: UKFileWatcherSizeIncreaseNotification forFile: fpath];
if( (ev.fflags & NOTE_LINK) == NOTE_LINK )
[self postNotification: UKFileWatcherLinkCountChangeNotification forFile: fpath];
if( (ev.fflags & NOTE_REVOKE) == NOTE_REVOKE )
[self postNotification: UKFileWatcherAccessRevocationNotification forFile: fpath];
}
}
}
NS_HANDLER
NSLog(@"Error in UKKQueue watcherThread: %@",localException);
NS_ENDHANDLER
[pool release];
}
// Close our kqueue's file descriptor:
if( close( theFD ) == -1 )
NSLog(@"release: Couldn't close main kqueue (%d)", errno);
//NSLog(@"exiting kqueue watcher thread.");
}
// -----------------------------------------------------------------------------
// postNotification:forFile:
// This is the main bottleneck for posting notifications. If you don't want
// the notifications to go through NSWorkspace, override this method and
// send them elsewhere.
//
// REVISIONS:
// 2004-02-27 UK Changed this to send new notification, and the old one
// only to objects that respond to it. The old category on
// NSObject could cause problems with the proxy itself.
// 2004-10-31 UK Helloween fun: Make this use a mainThreadProxy and
// allow sending the notification even if we have a
// delegate.
// 2004-03-13 UK Documented.
// -----------------------------------------------------------------------------
-(void) postNotification: (NSString*)nm forFile: (NSString*)fp
{
if( delegateProxy )
{
#if UKKQUEUE_BACKWARDS_COMPATIBLE
if( ![delegateProxy respondsToSelector: @selector(watcher:receivedNotification:forPath:)] )
[delegateProxy kqueue: self receivedNotification: nm forFile: fp];
else
#endif
[delegateProxy watcher: self receivedNotification: nm forPath: fp];
}
if( !delegateProxy || alwaysNotify )
{
#if UKKQUEUE_SEND_STUPID_NOTIFICATIONS
[[[NSWorkspace sharedWorkspace] notificationCenter] postNotificationName: nm object: fp];
#else
[[[NSWorkspace sharedWorkspace] notificationCenter] postNotificationName: nm object: self
userInfo: [NSDictionary dictionaryWithObjectsAndKeys: fp, @"path", nil]];
#endif
}
}
-(id) delegate
{
return delegate;
}
-(void) setDelegate: (id)newDelegate
{
id oldProxy = delegateProxy;
delegate = newDelegate;
delegateProxy = [delegate copyMainThreadProxy];
[oldProxy release];
}
// -----------------------------------------------------------------------------
// Flag to send a notification even if we have a delegate:
// -----------------------------------------------------------------------------
-(BOOL) alwaysNotify
{
return alwaysNotify;
}
-(void) setAlwaysNotify: (BOOL)n
{
alwaysNotify = n;
}
// -----------------------------------------------------------------------------
// description:
// This method can be used to help in debugging. It provides the value
// used by NSLog & co. when you request to print this object using the
// %@ format specifier.
//
// REVISIONS:
// 2004-11-12 UK Created.
// -----------------------------------------------------------------------------
-(NSString*) description
{
return [NSString stringWithFormat: @"%@ { watchedPaths = %@, alwaysNotify = %@ }", NSStringFromClass([self class]), watchedPaths, (alwaysNotify? @"YES" : @"NO") ];
}
@end