--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/hgext/inotify/linux/watcher.py	Wed Mar 12 15:30:11 2008 -0700
@@ -0,0 +1,335 @@
+# watcher.py - high-level interfaces to the Linux inotify subsystem
+
+# Copyright 2006 Bryan O'Sullivan <bos@serpentine.com>
+
+# This library is free software; you can redistribute it and/or modify
+# it under the terms of version 2.1 of the GNU Lesser General Public
+# License, incorporated herein by reference.
+
+'''High-level interfaces to the Linux inotify subsystem.
+
+The inotify subsystem provides an efficient mechanism for file status
+monitoring and change notification.
+
+The Watcher class hides the low-level details of the inotify
+interface, and provides a Pythonic wrapper around it.  It generates
+events that provide somewhat more information than raw inotify makes
+available.
+
+The AutoWatcher class is more useful, as it automatically watches
+newly-created directories on your behalf.'''
+
+__author__ = "Bryan O'Sullivan <bos@serpentine.com>"
+
+import _inotify as inotify
+import array
+import errno
+import fcntl
+import os
+import termios
+
+
+class Event(object):
+    '''Derived inotify event class.
+
+    The following fields are available:
+
+        mask: event mask, indicating what kind of event this is
+
+        cookie: rename cookie, if a rename-related event
+
+        path: path of the directory in which the event occurred
+
+        name: name of the directory entry to which the event occurred
+        (may be None if the event happened to a watched directory)
+
+        fullpath: complete path at which the event occurred
+
+        wd: watch descriptor that triggered this event'''
+
+    __slots__ = (
+        'cookie',
+        'fullpath',
+        'mask',
+        'name',
+        'path',
+        'raw',
+        'wd',
+        )
+
+    def __init__(self, raw, path):
+        self.path = path
+        self.raw = raw
+        if raw.name:
+            self.fullpath = path + '/' + raw.name
+        else:
+            self.fullpath = path
+
+        self.wd = raw.wd
+        self.mask = raw.mask
+        self.cookie = raw.cookie
+        self.name = raw.name
+    
+    def __repr__(self):
+        r = repr(self.raw)
+        return 'Event(path=' + repr(self.path) + ', ' + r[r.find('(')+1:]
+
+
+_event_props = {
+    'access': 'File was accessed',
+    'modify': 'File was modified',
+    'attrib': 'Attribute of a directory entry was changed',
+    'close_write': 'File was closed after being written to',
+    'close_nowrite': 'File was closed without being written to',
+    'open': 'File was opened',
+    'moved_from': 'Directory entry was renamed from this name',
+    'moved_to': 'Directory entry was renamed to this name',
+    'create': 'Directory entry was created',
+    'delete': 'Directory entry was deleted',
+    'delete_self': 'The watched directory entry was deleted',
+    'move_self': 'The watched directory entry was renamed',
+    'unmount': 'Directory was unmounted, and can no longer be watched',
+    'q_overflow': 'Kernel dropped events due to queue overflow',
+    'ignored': 'Directory entry is no longer being watched',
+    'isdir': 'Event occurred on a directory',
+    }
+
+for k, v in _event_props.iteritems():
+    mask = getattr(inotify, 'IN_' + k.upper())
+    def getter(self):
+        return self.mask & mask
+    getter.__name__ = k
+    getter.__doc__ = v
+    setattr(Event, k, property(getter, doc=v))
+
+del _event_props
+
+
+class Watcher(object):
+    '''Provide a Pythonic interface to the low-level inotify API.
+
+    Also adds derived information to each event that is not available
+    through the normal inotify API, such as directory name.'''
+
+    __slots__ = (
+        'fd',
+        '_paths',
+        '_wds',
+        )
+
+    def __init__(self):
+        '''Create a new inotify instance.'''
+
+        self.fd = inotify.init()
+        self._paths = {}
+        self._wds = {}
+
+    def fileno(self):
+        '''Return the file descriptor this watcher uses.
+
+        Useful for passing to select and poll.'''
+
+        return self.fd
+
+    def add(self, path, mask):
+        '''Add or modify a watch.
+
+        Return the watch descriptor added or modified.'''
+
+        path = os.path.normpath(path)
+        wd = inotify.add_watch(self.fd, path, mask)
+        self._paths[path] = wd, mask
+        self._wds[wd] = path, mask
+        return wd
+
+    def remove(self, wd):
+        '''Remove the given watch.'''
+
+        inotify.remove_watch(self.fd, wd)
+        self._remove(wd)
+
+    def _remove(self, wd):
+        path_mask = self._wds.pop(wd, None)
+        if path_mask is not None:
+            self._paths.pop(path_mask[0])
+
+    def path(self, path):
+        '''Return a (watch descriptor, event mask) pair for the given path.
+        
+        If the path is not being watched, return None.'''
+
+        return self._paths.get(path)
+
+    def wd(self, wd):
+        '''Return a (path, event mask) pair for the given watch descriptor.
+
+        If the watch descriptor is not valid or not associated with
+        this watcher, return None.'''
+
+        return self._wds.get(wd)
+        
+    def read(self, bufsize=None):
+        '''Read a list of queued inotify events.
+
+        If bufsize is zero, only return those events that can be read
+        immediately without blocking.  Otherwise, block until events are
+        available.'''
+
+        events = []
+        for evt in inotify.read(self.fd, bufsize):
+            events.append(Event(evt, self._wds[evt.wd][0]))
+            if evt.mask & inotify.IN_IGNORED:
+                self._remove(evt.wd)
+            elif evt.mask & inotify.IN_UNMOUNT:
+                self.close()
+        return events
+
+    def close(self):
+        '''Shut down this watcher.
+
+        All subsequent method calls are likely to raise exceptions.'''
+
+        os.close(self.fd)
+        self.fd = None
+        self._paths = None
+        self._wds = None
+
+    def __len__(self):
+        '''Return the number of active watches.'''
+
+        return len(self._paths)
+
+    def __iter__(self):
+        '''Yield a (path, watch descriptor, event mask) tuple for each
+        entry being watched.'''
+
+        for path, (wd, mask) in self._paths.iteritems():
+            yield path, wd, mask
+
+    def __del__(self):
+        if self.fd is not None:
+            os.close(self.fd)
+
+    ignored_errors = [errno.ENOENT, errno.EPERM, errno.ENOTDIR]
+
+    def add_iter(self, path, mask, onerror=None):
+        '''Add or modify watches over path and its subdirectories.
+
+        Yield each added or modified watch descriptor.
+
+        To ensure that this method runs to completion, you must
+        iterate over all of its results, even if you do not care what
+        they are.  For example:
+
+            for wd in w.add_iter(path, mask):
+                pass
+
+        By default, errors are ignored.  If optional arg "onerror" is
+        specified, it should be a function; it will be called with one
+        argument, an OSError instance.  It can report the error to
+        continue with the walk, or raise the exception to abort the
+        walk.'''
+
+        # Add the IN_ONLYDIR flag to the event mask, to avoid a possible
+        # race when adding a subdirectory.  In the time between the
+        # event being queued by the kernel and us processing it, the
+        # directory may have been deleted, or replaced with a different
+        # kind of entry with the same name.
+
+        submask = mask | inotify.IN_ONLYDIR
+
+        try:
+            yield self.add(path, mask)
+        except OSError, err:
+            if onerror and err.errno not in self.ignored_errors:
+                onerror(err)
+        for root, dirs, names in os.walk(path, topdown=False, onerror=onerror):
+            for d in dirs:
+                try:
+                    yield self.add(root + '/' + d, submask)
+                except OSError, err:
+                    if onerror and err.errno not in self.ignored_errors:
+                        onerror(err)
+
+    def add_all(self, path, mask, onerror=None):
+        '''Add or modify watches over path and its subdirectories.
+
+        Return a list of added or modified watch descriptors.
+
+        By default, errors are ignored.  If optional arg "onerror" is
+        specified, it should be a function; it will be called with one
+        argument, an OSError instance.  It can report the error to
+        continue with the walk, or raise the exception to abort the
+        walk.'''
+
+        return [w for w in self.add_iter(path, mask, onerror)]
+
+
+class AutoWatcher(Watcher):
+    '''Watcher class that automatically watches newly created directories.'''
+
+    __slots__ = (
+        'addfilter',
+        )
+
+    def __init__(self, addfilter=None):
+        '''Create a new inotify instance.
+
+        This instance will automatically watch newly created
+        directories.
+
+        If the optional addfilter parameter is not None, it must be a
+        callable that takes one parameter.  It will be called each time
+        a directory is about to be automatically watched.  If it returns
+        True, the directory will be watched if it still exists,
+        otherwise, it will beb skipped.'''
+
+        super(AutoWatcher, self).__init__()
+        self.addfilter = addfilter
+
+    _dir_create_mask = inotify.IN_ISDIR | inotify.IN_CREATE
+
+    def read(self, bufsize=None):
+        events = super(AutoWatcher, self).read(bufsize)
+        for evt in events:
+            if evt.mask & self._dir_create_mask == self._dir_create_mask:
+                if self.addfilter is None or self.addfilter(evt):
+                    parentmask = self._wds[evt.wd][1]
+                    # See note about race avoidance via IN_ONLYDIR above.
+                    mask = parentmask | inotify.IN_ONLYDIR
+                    try:
+                        self.add_all(evt.fullpath, mask)
+                    except OSError, err:
+                        if err.errno not in self.ignored_errors:
+                            raise
+        return events
+
+
+class Threshold(object):
+    '''Class that indicates whether a file descriptor has reached a
+    threshold of readable bytes available.
+
+    This class is not thread-safe.'''
+
+    __slots__ = (
+        'fd',
+        'threshold',
+        '_iocbuf',
+        )
+
+    def __init__(self, fd, threshold=1024):
+        self.fd = fd
+        self.threshold = threshold
+        self._iocbuf = array.array('i', [0])
+
+    def readable(self):
+        '''Return the number of bytes readable on this file descriptor.'''
+
+        fcntl.ioctl(self.fd, termios.FIONREAD, self._iocbuf, True)
+        return self._iocbuf[0]
+
+    def __call__(self):
+        '''Indicate whether the number of readable bytes has met or
+        exceeded the threshold.'''
+
+        return self.readable() >= self.threshold