swerling-sinotify 0.0.1

data/ext/src/sinotify.c

@@ -0,0 +1,205 @@
+#include <ruby.h>
+
+// includes that are different for ruby 1.8 vs. ruby 1.9
+#ifdef RUBY_19
+#warning "INCLUDING RUBY19 HEADERS (not really a warning, just for info)"
+#include <ruby/io.h>
+#else
+#warning "INCLUDING RUBY18 HEADERS (not really a warning, just for info) "
+#include <rubyio.h>
+
+#endif
+
+#ifdef HAVE_VERSION_H
+#include <version.h>
+#endif
+
+#ifdef HAVE_LINUX_INOTIFY_H
+#include <asm/unistd.h>
+#include <linux/inotify.h>
+#else
+#include "inotify.h"
+#include "inotify-syscalls.h"
+#endif
+
+#include <sys/syscall.h>
+#include <unistd.h>
+
+static inline int inotify_init (void)
+{
+	return syscall (__NR_inotify_init);
+}
+
+static inline int inotify_add_watch (int fd, const char *name, __u32 mask)
+{
+	return syscall (__NR_inotify_add_watch, fd, name, mask);
+}
+
+static inline int inotify_rm_watch (int fd, __u32 wd)
+{
+	return syscall (__NR_inotify_rm_watch, fd, wd);
+}
+
+VALUE rb_cSinotify;
+VALUE rb_cNotifier;
+VALUE rb_cSinotifyEvent;
+
+int event_check (int fd) {
+  struct timeval;
+	int r;
+
+	fd_set rfds;
+	FD_ZERO(&rfds);
+	FD_SET(fd, &rfds);
+
+  // Not using timout anymore
+	r = rb_thread_select (fd+1, &rfds, NULL, NULL, NULL);
+	return r;
+}
+
+static VALUE rb_inotify_event_new(struct inotify_event *event) {
+	VALUE retval;
+	retval = Data_Wrap_Struct(rb_cSinotifyEvent, NULL, free, event);
+	rb_obj_call_init(retval, 0, NULL);
+	return retval;
+}
+
+static VALUE rb_inotify_new(VALUE klass) {
+	int *fd;
+	VALUE retval;
+	fd = malloc(sizeof(int));
+	*fd = inotify_init();
+	if(*fd < 0) rb_sys_fail("inotify_init()");
+	retval = Data_Wrap_Struct(klass, NULL, free, fd);
+	rb_obj_call_init(retval, 0, NULL);
+	return retval;
+}
+
+static VALUE rb_inotify_add_watch(VALUE self, VALUE filename, VALUE mask) {
+	int *fd, wd;
+	Data_Get_Struct(self, int, fd);
+	wd = inotify_add_watch(*fd, RSTRING_PTR(filename), NUM2INT(mask));
+	if(wd < 0) {
+	  rb_sys_fail(RSTRING_PTR(filename));
+	}
+	return INT2NUM(wd);
+}
+
+static VALUE rb_inotify_rm_watch(VALUE self, VALUE wdnum) {
+	int *fd;
+	Data_Get_Struct(self, int, fd);
+	if(inotify_rm_watch(*fd, NUM2INT(wdnum)) < 0) {
+		rb_sys_fail("removing watch");
+	}
+	return Qtrue;
+}
+
+static VALUE rb_inotify_each_event(VALUE self) {
+	int *fd, r;
+	struct inotify_event *event, *pevent;
+	char buffer[16384];
+	size_t buffer_n, event_size;
+
+	Data_Get_Struct(self, int, fd);
+	while(1) {
+		r = event_check(*fd);
+		if(r == 0) {
+			continue;
+		}
+		if((r = read(*fd, buffer, 16384)) < 0) {
+			rb_sys_fail("reading event");
+		}
+		buffer_n = 0;
+		while (buffer_n < r) {
+			pevent = (struct inotify_event *)&buffer[buffer_n];
+			event_size = sizeof(struct inotify_event) + pevent->len;
+			event = malloc(event_size);
+			memmove(event, pevent, event_size);
+			buffer_n += event_size;
+			rb_yield(rb_inotify_event_new(event));
+		}
+	}
+	return Qnil;
+}
+
+static VALUE rb_inotify_close(VALUE self) {
+	int *fd;
+	Data_Get_Struct(self, int, fd);
+	if(close(*fd) != 0) {
+		rb_sys_fail("closing inotify");
+	}
+	return Qnil;
+}
+
+static VALUE rb_inotify_event_name(VALUE self) {
+	struct inotify_event *event;
+	Data_Get_Struct(self, struct inotify_event, event);
+	if(event->len) {
+		return rb_str_new2(event->name);
+	} else {
+		return Qnil;
+	}
+}
+
+static VALUE rb_inotify_event_wd(VALUE self) {
+	struct inotify_event *event;
+	Data_Get_Struct(self, struct inotify_event, event);
+	return INT2NUM(event->wd);
+}
+
+
+static VALUE rb_inotify_event_mask(VALUE self) {
+	struct inotify_event *event;
+	Data_Get_Struct(self, struct inotify_event, event);
+	return LONG2NUM(event->mask);
+}
+
+void Init_sinotify () {
+	rb_cSinotify = rb_define_module("Sinotify");
+
+  //
+  // The Sinotify::PrimNotifier class
+  //
+	rb_cNotifier = rb_define_class_under(rb_cSinotify, "PrimNotifier", rb_cObject);
+
+	rb_define_singleton_method(rb_cNotifier, "new", rb_inotify_new, 0);
+	rb_define_method(rb_cNotifier, "add_watch", rb_inotify_add_watch, 2);
+	rb_define_method(rb_cNotifier, "rm_watch", rb_inotify_rm_watch, 1);
+	rb_define_method(rb_cNotifier, "each_event", rb_inotify_each_event, 0);
+	rb_define_method(rb_cNotifier, "close", rb_inotify_close, 0);
+
+  //
+  // The Sinotify::PrimEvent class
+  //
+	rb_cSinotifyEvent = rb_define_class_under(rb_cSinotify, "PrimEvent", rb_cObject);
+	rb_define_method(rb_cSinotifyEvent, "prim_name", rb_inotify_event_name, 0);
+	rb_define_method(rb_cSinotifyEvent, "prim_wd", rb_inotify_event_wd, 0);
+	rb_define_method(rb_cSinotifyEvent, "prim_mask", rb_inotify_event_mask, 0);
+
+  // following inotify masks taken from inotify lib, see 'man inotify', section
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ACCESS"), INT2NUM(IN_ACCESS));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MODIFY"), INT2NUM(IN_MODIFY));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ATTRIB"), INT2NUM(IN_ATTRIB));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CLOSE_WRITE"), INT2NUM(IN_CLOSE_WRITE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CLOSE_NOWRITE"), INT2NUM(IN_CLOSE_NOWRITE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("OPEN"), INT2NUM(IN_OPEN));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVED_FROM"), INT2NUM(IN_MOVED_FROM));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVED_TO"), INT2NUM(IN_MOVED_TO));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CREATE"), INT2NUM(IN_CREATE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("DELETE"), INT2NUM(IN_DELETE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("DELETE_SELF"), INT2NUM(IN_DELETE_SELF));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVE_SELF"), INT2NUM(IN_MOVE_SELF));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("UNMOUNT"), INT2NUM(IN_UNMOUNT));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("Q_OVERFLOW"), INT2NUM(IN_Q_OVERFLOW));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("IGNORED"), INT2NUM(IN_IGNORED));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CLOSE"), INT2NUM(IN_CLOSE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVE"), INT2NUM(IN_MOVE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ONLYDIR"), INT2NUM(IN_ONLYDIR));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("DONT_FOLLOW"), INT2NUM(IN_DONT_FOLLOW));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MASK_ADD"), INT2NUM(IN_MASK_ADD));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ISDIR"), INT2NUM(IN_ISDIR));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ONESHOT"), INT2NUM(IN_ONESHOT));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ALL_EVENTS"), INT2NUM(IN_ALL_EVENTS));
+
+
+}

data/lib/sinotify.rb

@@ -0,0 +1,18 @@
+ext_lib = File.join(File.dirname(__FILE__), '../ext/sinotify.so')
+unless File.exist?(ext_lib)
+  raise "Could not find ext/sinotify.so. \n" \
+      + "Please build the sinotify.so extention first (cd [sinotify gem]/ext && ruby extconf.rb && make)" 
+end
+
+# load base info and c lib
+require ext_lib
+require File.join(File.dirname(__FILE__), 'sinotify_info')
+
+# load external dependencies
+require 'rubygems'
+require 'cosell'
+require 'logger'
+
+# load application
+Sinotify.require_all_libs_relative_to(__FILE__)
+

data/lib/sinotify/event.rb

@@ -0,0 +1,185 @@
+module Sinotify
+
+  # 
+  # Sinotify events are triggered as they come in to the Notifier ('announced'
+  # in the parlance of the Cosell announcement framework that sinotify uses).
+  # Each event has the 'path' of the file or dir that was effected, the
+  # timestamp of the event (generated in ruby, not at the primitive level), and
+  # whether the event was on a file or a directory. Also available is the event
+  # type, called the 'etype,' which can be :modify, :create, :delete, etc.  The
+  # list of event types is below. 
+  #
+  # A Sinotify::Event does not perfectly model a linux inotify event. See
+  # Sinotify::PrimEvent for that.
+  #
+  # This event class deviates from Sinotify::PrimEvent in one significant regard. Sinotify does not 
+  # pass events about children of a given directory, it only passes events about the directory 
+  # (or file) itself. That is _not_ to say you can't setup a recursive watch in the Notifier class,
+  # just that _the event itself_ only pertains the the inode/file/directory being altered, not to 
+  # its children. 
+  #
+  # This is perhaps best illustrated by an example. Let's say you
+  #
+  #   1. Create a directory called '/tmp/test'
+  #   2. Create a file in '/tmp/test' called '/tmp/test/blah'
+  #   3. You put a watch on the directory '/tmp/test'
+  #   4. You then do a 'rm -rf /tmp/test' 
+  #      (thus deleting both the file /tmp/test/blah AND the directory /tmp/test)
+  #
+  # In linux inotify, you would get two events in this scenario, _both_ on the
+  # watch for the /tmp/test directory. One of the events would be a ':delete' event
+  # (that is, the mask of the event would be equal to
+  # Sinotify::PrimEvent::DELETE, or the 'etype' of the PrimEvent would equal
+  # ':delete'), and the 'name' slot in the event would be 'blah.' This is your
+  # cue that the event _really_ happened on a child of the thing being watched
+  # ('/tmp/test'), not to the directory itself. Since you deleted both the file
+  # and the directory with your 'rm -rf' command, another event would come in
+  # of the etype :delete_self for the directory, and 'is_dir' would be in the
+  # mask (ie. the mask would be Sinotify::PrimEvent::DELETE & Sinotify::PrimEvent::IS_DIR). 
+  #
+  # Sinotify events would be a bit different in the example above.
+  # You would still get 2 events, but both would be :delete events, 
+  # one where the 'path' is '/tmp/test', and the other where the 'path'
+  # is '/tmp/test/blah'. In the case of the event for '/tmp/test', the call
+  # to 'directory?' would return true.
+  #
+  # If you want to work with an event notifier that works more like the low level linux inotify
+  # (receiving both :delete with name slot filled in and another event w/ :delete_self), 
+  # you will have to work directly with PrimNotifier and PrimEvent (along with their irritating 
+  # linux inotify-style blocking synchronous event loop)
+  #
+  # Here is the list of possible events adapted from the definitions
+  # in [linux_src]/include/linux/inotify.h: 
+  #
+  #   File related:
+  #     :access	# File was accessed 
+  #     :modify # file modified
+  #     :attrib # meta data changed
+  #     :close_write   # writable file was closed
+  #     :close_nowrite   # unwritable file was closed
+  #     :open  # file was opened
+  #     :moved_from # file moved from X
+  #     :moved_to  # file moved to Y
+  #     :create # file created
+  #     :delete # file deleted
+  #     :delete_self # self was deleted
+  #     :move_self  # self was moved
+  #
+  #  File related helpers:
+  #
+  #     :close  # (close_write | close_nowrite)
+  #     :move  # (moved_from | moved_to)
+  #
+  #  Misc events
+  #
+  #     :unmount # backing fs was unmounted
+  #     :q_overflow # event queue overflowed
+  #     :ignored  # file was ignored
+  #     :mask_add # added to mask of already existing event
+  #     :isdir # event occurred against dir
+  #     :oneshot # only send event once
+  #
+  class Event
+
+    attr_accessor :prim_event, :path, :timestamp, :is_dir
+
+    # a few attr declarations just so they show up in rdoc
+
+    # Given a prim_event, and the Watch associated with the event's watch descriptor,
+    # return a Sinotify::Event. 
+    def self.from_prim_event_and_watch(prim_event, watch)
+      path = watch.path         # path for the watch associated w/ this even
+      is_dir = watch.directory? # original watch was on a dir or a file?
+
+      # This gets a little odd. The prim_event's 'name' field
+      # will be nil if the change was to a directory itself, or if
+      # the watch was on a file to begin with. However,
+      # when a watch is on a dir, but the event occurs on a file in that dir
+      # inotify sets the 'name' field to the file. :isdir will be in the etypes
+      # if that file happens to be a subdir. Sinotify events do not
+      # play this game, only sending events for the thing that was altered
+      # in the first place. So right here is where we deduce if the 
+      # event was _really_ on a file or a dir.
+      unless prim_event.name.nil?
+        path = File.join(path, prim_event.name) 
+        is_dir = prim_event.etypes.include?(:isdir)
+      end
+
+      # is_dir must be passed along, since it may no longer exist (and thus cant be deduced later)
+      # inotify prim_events to not retain enough information to make it possible to deduce the
+      # original fullpath and whether it was a file or directory, so this info must be passed around.
+      return Sinotify::Event.new(:prim_event => prim_event,
+                                 :path => path,
+                                 :timestamp => Time.now, # any way to get this from prim event?
+                                 :is_dir => is_dir) 
+    end
+
+    def initialize(args={})
+      args.each{|k,v| self.send("#{k}=",v)}
+      @timestamp ||= Time.now
+
+      # initialize a few variables just to shut up the ruby warnings
+      @etypes = nil
+    end
+
+    # The Sinotify::PrimEvent associated with this event (a straight 
+    # wrapper around the linux inotify event)
+    def prim_event; @prim_event; end
+
+    # The full path of the file or directory on which the event happened
+    def path; @path; end
+
+    # when the event happened
+    def timestamp; @timestamp; end
+
+
+    def to_s; self.inspect_or_to_s(false); end
+    def inspect; self.inspect_or_to_s(true); end
+
+    # The etypes associated with this event (eg. :create, :modify, :delete, etc)
+    def etypes
+      # The etype/mask functions delegated to prim_event, EXCEPT: when :delete_self is in 
+      # the list, and path is a directory, change it to 'delete'. If you want
+      # the etypes in the original prim_event, ask for event.prim_event.etypes
+      if @etypes.nil?
+        @etypes = self.prim_event.etypes
+
+        # change :delete_self into :delete 
+        if self.directory? and @etypes.include?(:delete_self)
+          @etypes.delete(:delete_self)
+          @etypes << :delete
+        end
+
+        # add :close if :close_write or :close_nowrite are there, but :close is not
+        if @etypes.include?(:close_write) || @etypes.include?(:close_nowrite)
+          (@etypes << :close) unless @etypes.include?(:close)
+        end
+
+      end
+      @etypes
+    end
+
+    def directory?
+      self.is_dir.eql?(true)
+    end
+
+    def has_etype? etype
+      self.etypes.include?(etype)
+    end
+
+    def watch_descriptor
+      self.prim_event.watch_descriptor
+    end
+
+    protected
+
+      # :stopdoc:
+      def inspect_or_to_s(show_prim_event = false)
+        prim_event = (show_prim_event)? ", :prim_event => #{self.prim_event.inspect}" : ''
+        "<#{self.class} :path => '#{self.path}', dir? => #{self.directory?}, :etypes => #{self.etypes.inspect rescue 'could not determine'}#{prim_event}>"
+      end
+
+      # :startdoc:
+  end
+
+end

data/lib/sinotify/notifier.rb

@@ -0,0 +1,308 @@
+module Sinotify
+
+  #
+  #  Watch a directory or file for events like create, modify, delete, etc.
+  #  (See Sinotify::Event for full list). 
+  #
+  #  See the synopsis section in the README.txt for example usage.
+  #
+  #
+  class Notifier
+    include Cosell
+
+    attr_accessor :file_or_dir_name, :etypes, :recurse, :recurse_throttle, :logger
+
+    #  Required Args
+    #
+    #    file_or_dir_name: the file/directory to watch
+    #
+    #  Options:
+    #    :recurse => (true|false)
+    #      whether to automatically create watches on sub directories
+    #      default: true if file_or_dir_name is a directory, else false
+    #      raises if true and file_or_dir_name is not a directory
+    #
+    #    :recurse_throttle => 
+    #      When recursing, a background thread drills down into all the child directories
+    #      creating notifiers on them. The recurse_throttle tells the notifier how far
+    #      to recurse before sleeping for 0.1 seconds, so that drilling down does not hog
+    #      the system on large directorie hierarchies.
+    #      default is 10
+    #
+    #    :etypes => 
+    #      which inotify file system event types to listen for (eg :create, :delete, etc)
+    #      See docs for Sinotify::Event for list of event types.
+    #      default is :all_types
+    #
+    #    :logger => 
+    #      Where to log errors to. Default is Logger.new(STDOUT).
+    #
+    #    :announcement_throttle =>
+    #      How many events can be announced at a time before the queue goes back to sleep for a cycle.
+    #      (ie. Cosell's 'announcements_per_cycle')
+    #
+    #    :announcements_sleep_time =>
+    #      How long the queue should sleep for before announcing the next batch of queued up 
+    #      Sinotify::Events (ie. Cosell's 'sleep_time')
+    #
+    def initialize(file_or_dir_name, opts = {})
+
+      initialize_cosell!  # init the announcements framework
+
+      raise "Could not find #{file_or_dir_name}" unless File.exist?(file_or_dir_name)
+      self.file_or_dir_name = file_or_dir_name
+
+      # by default, recurse if directory?. If opts[:recurse] was true and passed in,
+      # make sure the watch is on a directory
+      self.recurse = opts[:recurse].nil?? self.on_directory? : opts[:recurse] 
+      raise "Cannot recurse, #{file_or_dir_name} is not a directory" if self.recurse? && !self.on_directory?
+
+      # how many directories at a time to register. 
+      self.recurse_throttle = opts[:recurse_throttle] || 10 
+
+      self.etypes = Array(opts[:etypes] || :all_events)
+      validate_etypes!
+
+      self.prim_notifier = Sinotify::PrimNotifier.new
+
+      # setup async announcements queue (part of the Cosell mixin)
+      @logger = opts[:logger] || Logger.new(STDOUT)
+      sleep_time = opts[:announcements_sleep_time] || 0.05 
+      announcement_throttle = opts[:announcement_throttle] || 50 
+      self.queue_announcements!(:sleep_time => sleep_time, 
+                                :logger => opts[:logger], 
+                                :announcements_per_cycle => announcement_throttle)
+
+      self.closed = false
+
+      # initialize a few variables just to shut up the ruby warnings
+      # Apparently the lazy init idiom using ||= is no longer approved of. Shame that.
+      @spy_logger = nil
+      @spy_logger_level = nil
+      @watch_thread = nil
+    end
+    
+    # whether this watch is on a directory
+    def on_directory?
+      File.directory?(self.file_or_dir_name)
+    end
+
+    # Start watching for inotify file system events.
+    def watch!
+      raise "Cannot reopen an inotifier. Create a new one instead" if self.closed?
+      self.add_all_directories_in_background
+      self.start_prim_event_loop_thread
+      return self
+    end
+
+    # Close this notifier. Notifiers cannot be reopened after close!. 
+    def close!
+      @closed = true
+      self.remove_all_watches
+    end
+
+    # Log a message every time a prim_event comes in (will be logged even if it is considered 'noise'),
+    # and log a message whenever an event is announced. Overrides Cosell's spy! method (and uses cosell's
+    # spy! to log announced events).
+    #
+    # Options:
+    #    :logger => The log to log to. Default is a logger on STDOUT
+    #    :level => The log level to log with. Default is :info
+    #
+    def spy!(opts = {})
+      @spy_logger = opts[:logger] || Logger.new(STDOUT)
+      @spy_logger_level = opts[:level] || :info
+      opts[:on] = Sinotify::Event
+      opts[:preface_with] = "Sinotify::Notifier Event Spy"
+      super(opts)
+    end
+
+    # Return a list of files/directories currently being watched. Will only contain one entry unless
+    # this notifier was setup on a directory with the option :recurse => true.
+    def all_directories_being_watched
+      self.watches.values.collect{|w| w.path }.sort
+    end
+
+    def watches
+      @watches ||= {}
+    end
+
+    # Whether this notifier watches all the files in all of the subdirectories
+    # of the directory being watched.
+    def recurse?
+      self.recurse
+    end
+
+    def to_s
+      "Sinotify::Notifier[#{self.file_or_dir_name}, :watches => #{self.watches.size}]"
+    end
+
+    protected
+
+      #:stopdoc: 
+ 
+      def validate_etypes!
+        bad = self.etypes.detect{|etype| PrimEvent.mask_from_etype(etype).nil? }
+        raise "Unrecognized etype '#{bad}'. Please see valid list in docs for Sinotify::Event" if bad
+      end
+
+      # some events we don't want to report (certain events are generated just from creating watches)
+      def event_is_noise? prim_event, watch
+
+        etypes_strings = prim_event.etypes.map{|e|e.to_s}.sort
+
+        # the simple act of creating a watch causes these to fire"
+        return true if ["close_nowrite", "isdir"].eql?(etypes_strings)
+        return true if ["isdir", "open"].eql?(etypes_strings)
+        return true if ["ignored"].eql?(etypes_strings)
+
+        # If the event is on a subdir of the directory specified in watch, don't send it because
+        # there should be another even (on the subdir itself) that comes through, and this one
+        # will be redundant. 
+        return true if ["delete", "isdir"].eql?(etypes_strings)
+
+        return false
+      end
+
+      # Open up a background thread that adds all the watches on @file_or_dir_name and,
+      # if @recurse is true, all of its subdirs.
+      def add_all_directories_in_background
+        @child_dir_thread = Thread.new do 
+          begin
+            self.add_watches! 
+          rescue Exception => x
+            log "Exception: #{x}, trace: \n\t#{x.backtrace.join("\n\t")}", :error 
+          end
+        end 
+      end
+
+      def add_watches!(fn = self.file_or_dir_name, throttle = 0)
+
+        return if closed?
+        if throttle.eql?(self.recurse_throttle)
+          sleep 0.1
+          throttle = 0
+        end
+        throttle += 1
+
+        self.add_watch(fn)
+
+        if recurse?
+          Dir[File.join(fn, '/**')].each do |child_fn|
+            next if child_fn.eql?(fn)
+            self.add_watches!(child_fn, throttle) if File.directory?(child_fn)
+          end
+        end
+
+      end
+
+      def add_watch(fn)
+        watch_descriptor = self.prim_notifier.add_watch(fn, self.raw_mask)
+        # puts "ADDED WATCH: #{watch_descriptor} for #{fn}"
+        remove_watch(watch_descriptor) # remove the existing, if it exists
+        watch = Watch.new(:path => fn, :watch_descriptor => watch_descriptor)
+        self.watches[watch_descriptor.to_s] = watch
+      end
+
+      # Remove the watch associated with the watch_descriptor passed in
+      def remove_watch(watch_descriptor, prim_remove = false)
+        if watches[watch_descriptor.to_s]
+          # puts "REMOVING: #{watch_descriptor}"
+          self.watches.delete(watch_descriptor.to_s)
+
+          # the prim_notifier will complain if we remove a watch on a deleted file,
+          # since the watch will have automatically been removed already. Be default we
+          # don't care, but if caller is sure there are some prim watches to clean
+          # up, then they can pass 'true' for prim_remove. Another way to handle
+          # this would be to just default to true and fail silently, but trying this
+          # more conservative approach for now.
+          self.prim_notifier.rm_watch(watch_descriptor.to_i) if prim_remove
+        end
+      end
+
+      def remove_all_watches
+        self.watches.keys.each{|watch_descriptor| self.remove_watch(watch_descriptor, true) }
+      end
+
+      def log(msg, level = :debug)
+        puts(msg) unless [:debug, :info].include?(level)
+        self.logger.send(level, msg) if self.logger
+      end
+
+      def spy_on_event(prim_event)
+        if @spy_logger
+          msg = "Sinotify::Notifier Prim Event Spy: #{prim_event.inspect}"
+          @spy_logger.send(@spy_logger_level, msg)
+        end
+      end
+
+      # Listen for linux inotify events, and as they come in
+      #   1. adapt them into Sinotify::Event objects 
+      #   2. 'announce' them using Cosell. 
+      # By default, Cosell is setup to Queue the announcements in a bg thread.
+      #
+      # The references to two different logs in this method may be a bit confusing. The @spy_logger 
+      # exclusively logs (spys on) events and announcements. The "log" method instead uses the @logger
+      # and logs errors and exceptions. The @logger is defined when creating this object (using the :logger
+      # option), and the @spy_logger is defined in the :spy! method.
+      #
+      def start_prim_event_loop_thread
+
+        raise "Already watching!" unless @watch_thread.nil?
+
+        @watch_thread = Thread.new do
+          begin
+            self.prim_notifier.each_event do |prim_event|
+              watch = self.watches[prim_event.watch_descriptor.to_s]
+              if event_is_noise?(prim_event, watch)
+                @spy_logger.debug("Sinotify::Notifier Spy: Skipping noise[#{prim_event.inspect}]") if @spy_logger
+              else
+                spy_on_event(prim_event)
+                if watch.nil?
+                  self.log "Could not determine watch from descriptor #{prim_event.watch_descriptor}, something is wrong. Event: #{prim_event.inspect}", :warn
+                else
+                  event = Sinotify::Event.from_prim_event_and_watch(prim_event, watch)
+                  self.announce event
+                  if event.has_etype?(:create) && event.directory?
+                    Thread.new do 
+                      # have to thread this because the :create event comes in _before_ the directory exists,
+                      # and inotify will not permit a watch on a file unless it exists
+                      sleep 0.1
+                      self.add_watch(event.path)
+                    end
+                  end
+                  # puts "REMOVING: #{event.inspect}, WATCH: #{self.watches[event.watch_descriptor.to_s]}" if event.has_etype?(:delete) && event.directory?
+                  self.remove_watch(event.watch_descriptor) if event.has_etype?(:delete) && event.directory?
+                  break if closed?
+                end
+              end
+          end
+          rescue Exception => x
+            log "Exception: #{x}, trace: \n\t#{x.backtrace.join("\n\t")}", :error 
+          end
+
+          log "Exiting prim event loop thread for #{self}"
+        end
+
+      end
+
+      def raw_mask
+        if @raw_mask.nil?
+          (self.etypes << :delete_self) if self.etypes.include?(:delete)
+          @raw_mask = self.etypes.inject(0){|raw, etype| raw | PrimEvent.mask_from_etype(etype) }
+        end
+        @raw_mask
+      end
+
+      # ruby gives warnings in verbose mode if you use attr_accessor to set these next few: 
+      def prim_notifier; @prim_notifier; end
+      def prim_notifier= x; @prim_notifier = x; end
+      def watch_descriptor; @watch_descriptor; end
+      def watch_descriptor= x; @watch_descriptor = x; end
+      def closed?; @closed.eql?(true); end
+      def closed= x; @closed = x; end
+
+      #:startdoc: 
+  end
+end
+