directory_watcher 1.2.0 → 1.3.0

data/History.txt

@@ -1,3 +1,12 @@
+== 1.3.0 / 2009-10-21
+
+* 2 major enhancements
+  - added support for Rev based notifications
+  - added support for EventMachine based notifications
+
+* 1 minor enhancement
+  - pulled out the scanner thread into its own class
+
 == 1.2.0 / 2009-04-12
 
 * 2 minor enhancements

data/README.txt

@@ -1,4 +1,4 @@
-directory_watcher
+Directory Watcher
     by Tim Pease
     http://codeforpeople.rubyforge.org/directory_watcher
 
@@ -27,10 +27,21 @@ watcher.
 
   sudo gem install bones
 
+== NOTES:
+
+The support for EventMachine based file notifications is fairly new and
+experimental. Please feel free to experiment and report any issues on the
+github issue tracker.
+
+  http://github.com/TwP/directory_watcher/issues
+
+The support for Rev based file notifications is also fairly new and subject to
+the same disclaimer as the EventMachine functionality.
+
 == LICENSE:
 
 MIT License
-Copyright (c) 2007 - 2008
+Copyright (c) 2007 - 2009
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/directory_watcher.rb

@@ -57,7 +57,7 @@ require 'yaml'
 # *stable* event. This event is generated after a file has been added or
 # modified and then remains unchanged for a certain number of scan
 # intervals.
-# 
+#
 # To enable the generation of this event the +stable+ count must be
 # configured. This is the number of scan intervals a file must remain
 # unchanged (based modification time and file size) before it is considered
@@ -167,25 +167,51 @@ require 'yaml'
 #    dw.run_once
 #    dw.persist!    # stores state to dw_state.yml
 #
+# === Scanning Strategies
+#
+# By default DirectoryWatcher uses a thread that scans the directory being
+# watched for files and calls "stat" on each file. The stat information is
+# used to determine which files have been modified, added, removed, etc.
+# This approach is fairly intensive for short intervals and/or directories
+# with many files.
+#
+# DirectoryWatcher supports using Rev () or EventMachine () instead of a
+# busy polling thread. These libraries use system level kernel hooks to
+# receive notifications of file system changes. This makes DirectoryWorker
+# much more efficient.
+#
+# This example will use Rev to generate file notifications.
+#
+#    dw = DirectoryWatcher.new '.', :glob => '**/*.rb', :scanner => :rev
+#    dw.add_observer {|*args| args.each {|event| puts event}}
+#
+#    dw.start
+#    gets      # when the user hits "enter" the script will terminate
+#    dw.stop
+#
+# The scanner cannot be changed after the DirectoryWatcher has been
+# created. To use an EventMachine scanner, pass :em as the :scanner
+# option.
+#
 # == Contact
 #
 # A lot of discussion happens about Ruby in general on the ruby-talk
 # mailing list (http://www.ruby-lang.org/en/ml.html), and you can ask
 # any questions you might have there. I monitor the list, as do many
 # other helpful Rubyists, and you're sure to get a quick answer. Of
-# course, you're also welcome to email me (Tim Pease) directly at the 
+# course, you're also welcome to email me (Tim Pease) directly at the
 # at tim.pease@gmail.com, and I'll do my best to help you out.
-# 
+#
 # (the above paragraph was blatantly stolen from Nathaniel Talbott's
 # Test::Unit documentation)
-# 
+#
 # == Author
 #
 # Tim Pease
 #
 class DirectoryWatcher
 
-  VERSION = '1.2.0'    # :nodoc:
+  VERSION = '1.3.0'    # :nodoc:
 
   # An +Event+ structure contains the _type_ of the event and the file _path_
   # to which the event pertains. The type can be one of the following:
@@ -196,20 +222,21 @@ class DirectoryWatcher
   #    :removed    =>  file has been removed from the directory
   #    :stable     =>  file has stabilized since being added or modified
   #
-  Event = Struct.new(:type, :path) do
+  Event = Struct.new(:type, :path) {
     def to_s( ) "#{type} '#{path}'" end
-  end
+  }
 
   # :stopdoc:
   # A persistable file stat structure used internally by the directory
   # watcher.
   #
-  FileStat = Struct.new(:mtime, :size, :stable) do
-    def <=>( other )
-      return unless other.is_a? ::DirectoryWatcher::FileStat
-      self.mtime <=> other.mtime
+  FileStat = Struct.new(:mtime, :size, :stable) {
+    def eql?( other )
+      return false unless other.instance_of? FileStat
+      self.mtime == other.mtime and self.size == other.size
     end
-  end
+    alias :== :eql?
+  }
   # :startdoc:
 
   # call-seq:
@@ -232,6 +259,8 @@ class DirectoryWatcher
   #    :persist   =>  file     the state will be persisted to and restored
   #                            from the file when the directory watcher is
   #                            stopped and started (respectively)
+  #    :scanner   =>  nil      the directory scanning strategy to use with
+  #                            the directory watcher (either :em :rev or nil)
   #
   # The default glob pattern will scan all files in the configured directory.
   # Setting the :stable option to +nil+ will prevent stable events from being
@@ -239,6 +268,7 @@ class DirectoryWatcher
   #
   def initialize( directory, opts = {} )
     @dir = directory
+    @observer_peers = {}
 
     if Kernel.test(?e, @dir)
       unless Kernel.test(?d, @dir)
@@ -248,15 +278,16 @@ class DirectoryWatcher
       Dir.mkdir @dir
     end
 
+    klass = opts[:scanner].to_s.capitalize + 'Scanner'
+    klass = DirectoryWatcher.const_get klass rescue Scanner
+    @scanner = klass.new {|events| notify_observers(events)}
+
     self.glob = opts[:glob] || '*'
     self.interval = opts[:interval] || 30
     self.stable = opts[:stable] || nil
     self.persist = opts[:persist]
 
-    @files = (opts[:pre_load] ? scan_files : Hash.new)
-    @events = []
-    @thread = nil
-    @observer_peers = {}
+    @scanner.reset opts[:pre_load]
   end
 
   # call-seq:
@@ -314,15 +345,15 @@ class DirectoryWatcher
   # files. A single glob pattern can be given or an array of glob patterns.
   #
   def glob=( val )
-    @glob = case val
-            when String; [File.join(@dir, val)]
-            when Array; val.flatten.map! {|g| File.join(@dir, g)}
-            else
-              raise(ArgumentError,
-                    'expecting a glob pattern or an array of glob patterns')
-            end
-    @glob.uniq!
-    val
+    glob = case val
+           when String; [File.join(@dir, val)]
+           when Array; val.flatten.map! {|g| File.join(@dir, g)}
+           else
+             raise(ArgumentError,
+                   'expecting a glob pattern or an array of glob patterns')
+           end
+    glob.uniq!
+    @scanner.glob = glob
   end
   attr_reader :glob
 
@@ -333,9 +364,14 @@ class DirectoryWatcher
   def interval=( val )
     val = Float(val)
     raise ArgumentError, "interval must be greater than zero" if val <= 0
-    @interval = Float(val)
+    @scanner.interval = Float(val)
+  end
+
+  # Returns the directory scan interval in seconds.
+  #
+  def interval
+    @scanner.interval
   end
-  attr_reader :interval
 
   # Sets the number of intervals a file must remain unchanged before it is
   # considered "stable". When this condition is met, a stable event is
@@ -359,15 +395,21 @@ class DirectoryWatcher
   #
   def stable=( val )
     if val.nil?
-      @stable = nil
+      @scanner.stable = nil
       return
     end
 
     val = Integer(val)
     raise ArgumentError, "stable must be greater than zero" if val <= 0
-    @stable = val
+    @scanner.stable = val
+  end
+
+  # Returs the number of intervals a file must remain unchanged before it is
+  # considered "stable".
+  #
+  def stable
+    @scanner.stable
   end
-  attr_reader :stable
 
   # Sets the name of the file to which the directory watcher state will be
   # persisted when it is stopped. Setting the persist filename to +nil+ will
@@ -384,7 +426,7 @@ class DirectoryWatcher
   #
   def persist!
     return if running?
-    File.open(@persist, 'w') {|fd| fd.write YAML.dump(@files)} if @persist
+    File.open(@persist, 'w') {|fd| fd.write YAML.dump(@scanner.files)} if @persist
     self
   end
 
@@ -394,7 +436,7 @@ class DirectoryWatcher
   #
   def load!
     return if running?
-    @files = YAML.load_file(@persist) if @persist and test(?f, @persist)
+    @scanner.files = YAML.load_file(@persist) if @persist and test(?f, @persist)
     self
   end
 
@@ -402,7 +444,7 @@ class DirectoryWatcher
   # +false+ if this is not the case.
   #
   def running?
-    !@thread.nil?
+    @scanner.running?
   end
 
   # Start the directory watcher scanning thread. If the directory watcher is
@@ -412,8 +454,7 @@ class DirectoryWatcher
     return if running?
 
     load!
-    @stop = false
-    @thread = Thread.new(self) {|dw| dw.__send__ :run_loop}
+    @scanner.start
     self
   end
 
@@ -423,12 +464,9 @@ class DirectoryWatcher
   def stop
     return unless running?
 
-    @stop = true
-    @thread.wakeup if @thread.status == 'sleep'
-    @thread.join
+    @scanner.stop
     self
   ensure
-    @thread = nil
     persist!
   end
 
@@ -443,11 +481,11 @@ class DirectoryWatcher
   # generated.
   #
   def reset( pre_load = false )
-    was_running = running?
+    was_running = @scanner.running?
 
     stop if was_running
     File.delete(@persist) if @persist and test(?f, @persist)
-    @files = (pre_load ? scan_files : Hash.new)
+    @scanner.reset pre_load
     start if was_running
   end
 
@@ -463,142 +501,38 @@ class DirectoryWatcher
   # with +nil+.
   #
   def join( limit = nil )
-    return unless running?
-    @thread.join limit
+    @scanner.join limit
   end
 
   # Performs exactly one scan of the directory for file changes and notifies
   # the observers.
-  # 
-  # This method wil not persist file changes if that options is configured.
-  # The user must call persist! explicitly when using the run_once method.
   #
   def run_once
-    files = scan_files
-    keys = [files.keys, @files.keys]  # current files, previous files
-
-    find_added(files, *keys)
-    find_modified(files, *keys)
-    find_removed(*keys)
-
-    notify_observers
-    @files = files    # store the current file list for the next iteration
+    @scanner.run_once
     self
   end
 
 
   private
 
-  # Using the configured glob pattern, scan the directory for all files and
-  # return a hash with the filenames as keys and +File::Stat+ objects as the
-  # values. The +File::Stat+ objects contain the mtime and size of the file.
-  #
-  def scan_files
-    files = {}
-    @glob.each do |glob|
-      Dir.glob(glob).each do |fn|
-        begin
-          stat = File.stat fn
-          next unless stat.file?
-          files[fn] = DirectoryWatcher::FileStat.new(stat.mtime, stat.size)
-        rescue SystemCallError; end
-      end
-    end
-    files
-  end
-
-  # Calling this method will enter the directory watcher's run loop. The
-  # calling thread will not return until the +stop+ method is called.
-  #
-  # The run loop is responsible for scanning the directory for file changes,
-  # and then dispatching events to registered listeners.
-  #
-  def run_loop
-    until @stop
-      start = Time.now.to_f
-
-      run_once
-
-      nap_time = @interval - (Time.now.to_f - start)
-      sleep nap_time if nap_time > 0
-    end
-  end
-
-  # call-seq:
-  #    find_added( files, cur, prev )
-  #
-  # Taking the list of current files, _cur_, and the list of files found
-  # previously, _prev_, figure out which files have been added and generate
-  # a new file added event for each.
-  #
-  def find_added( files, cur, prev )
-    added = cur - prev
-    added.each do |fn|
-      files[fn].stable = @stable
-      @events << Event.new(:added, fn)
-    end
-    self
-  end
-
-  # call-seq:
-  #    find_removed( cur, prev )
+  # Invoke the update method of each registered observer in turn passing the
+  # list of file events to each.
   #
-  # Taking the list of current files, _cur_, and the list of files found
-  # previously, _prev_, figure out which files have been removed and
-  # generate a new file removed event for each.
-  #
-  def find_removed( cur, prev )
-    removed = prev - cur
-    removed.each {|fn| @events << Event.new(:removed, fn)}
-    self
-  end
-
-  # call-seq:
-  #    find_modified( files, cur, prev )
-  #
-  # Taking the list of current files, _cur_, and the list of files found
-  # previously, _prev_, find those that are common between them and determine
-  # if any have been modified. Generate a new file modified event for each
-  # modified file. Also, by looking at the stable count in the _files_ hash,
-  # figure out if any files have become stable since being added or modified.
-  # Generate a new stable event for each stabilized file.
-  #
-  def find_modified( files, cur, prev )
-    (cur & prev).each do |key|
-      cur_stat, prev_stat = files[key], @files[key]
-
-      # if the modification time or the file size differs from the last
-      # time it was seen, then create a :modified event
-      if (cur_stat <=> prev_stat) != 0 or cur_stat.size != prev_stat.size
-        @events << Event.new(:modified, key)
-        cur_stat.stable = @stable
-
-      # otherwise, if the count is not nil see if we need to create a
-      # :stable event
-      elsif !prev_stat.stable.nil?
-        cur_stat.stable = prev_stat.stable - 1
-        if cur_stat.stable == 0
-          @events << Event.new(:stable, key)
-          cur_stat.stable = nil
-        end
-      end
-    end
-    self
-  end
-
-  # If there are queued files events, then invoke the update method of each
-  # registered observer in turn passing the list of file events to each.
-  # The file events array is cleared at the end of this method call.
-  #
-  def notify_observers
-    unless @events.empty?
-      @observer_peers.each do |observer, func|
-        begin; observer.send(func, *@events); rescue Exception; end
-      end
-      @events.clear
+  def notify_observers( events )
+    @observer_peers.each do |observer, func|
+      begin; observer.send(func, *events); rescue Exception; end
     end
   end
 
 end  # class DirectoryWatcher
 
+begin
+  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
+  require 'directory_watcher/scanner'
+  require 'directory_watcher/em_scanner'
+  require 'directory_watcher/rev_scanner'
+ensure
+  $LOAD_PATH.shift
+end
+
 # EOF

data/lib/directory_watcher/em_scanner.rb

@@ -0,0 +1,221 @@
+
+begin
+  require 'eventmachine'
+  DirectoryWatcher::HAVE_EM = true
+rescue LoadError
+  DirectoryWatcher::HAVE_EM = false
+end
+
+if DirectoryWatcher::HAVE_EM
+[:epoll, :kqueue].each {|poll| break if EventMachine.send(poll)}
+
+
+# The EmScanner uses the EventMachine reactor loop to monitor changes to
+# files in the watched directory. This scanner is more efficient than the
+# pure Ruby scanner because it relies on the operating system kernel
+# notifictions instead of a periodic polling and stat of every file in the
+# watched directory (the technique used by the Scanner class).
+#
+# EventMachine cannot notify us when a file is added to the watched
+# directory; therefore, added files are only picked up when we apply the
+# glob pattern to the directory. This is done at the configured interval.
+#
+# Notes:
+#
+#  * Kqueue does not generate notifications when "touch" is used to update
+#    a file's timestamp. This applies to Mac and BSD systems.
+#
+#  * New files are detected only when the watched directory is polled at the
+#    configured interval.
+# 
+class DirectoryWatcher::EmScanner < ::DirectoryWatcher::Scanner
+
+  # call-seq:
+  #    EmScanner.new { |events| block }
+  #
+  # Create an EventMachine based scanner that will generate file events and
+  # pass those events (as an array) to the given _block_.
+  #
+  def initialize( &block )
+    super(&block)
+    @timer = nil
+    @run_loop = lambda {_run_loop}
+    @watchers = {}
+  end
+
+  # Returns +true+ if the scanner is currently running. Returns +false+ if
+  # this is not the case.
+  #
+  def running?
+    !@timer.nil?
+  end
+
+  # Start the EventMachine scanner. If the scanner has already been started
+  # this method will return without taking any action.
+  #
+  # If the EventMachine reactor is not running, it will be started by this
+  # method.
+  #
+  def start
+    return if running?
+
+    unless EventMachine.reactor_running?
+      @thread = Thread.new {EventMachine.run}
+      Thread.pass until EventMachine.reactor_running?
+    end
+
+    @files.keys.each do |fn|
+      if test ?e, fn
+        _watch_file fn
+        next
+      end
+
+      @files.delete fn
+      @events << ::DirectoryWatcher::Event.new(:removed, fn)
+    end
+
+    _run_loop
+  end
+
+  # Stop the EventMachine scanner. If the scanner is already stopped this
+  # method will return without taking any action.
+  #
+  # The EventMachine reactor will _not_ be stopped by this method. It is up
+  # to the user to stop the reactor using the EventMachine#stop_event_loop
+  # method.
+  #
+  def stop
+    return unless running?
+
+    EventMachine.cancel_timer @timer rescue nil
+    @timer = nil
+
+    @watchers.each_value {|w| w.stop_watching if w.active?}
+    @watchers.clear
+
+    notify
+  end
+
+  # call-seq:
+  #    join( limit = nil )
+  #
+  # This is a no-op method for the EventMachine file scanner.
+  #
+  def join( limit = nil )
+  end
+
+  # :stopdoc:
+  #
+  # This callback is invoked by a Watcher instance when some event has
+  # occured on the file. The scanner determines if the file has been
+  # modified or deleted and notifies the directory watcher accordingly.
+  #
+  def _event!( watcher )
+    fn = watcher.path
+    stat = watcher.stat
+
+    if stat
+      _watch_file fn unless watcher.active?
+      @files[fn] = stat
+      @events << ::DirectoryWatcher::Event.new(:modified, fn)
+    else
+      if watcher.active?
+        watcher.stop_watching
+        @watchers.delete fn
+      end
+      @files.delete fn
+      @events << ::DirectoryWatcher::Event.new(:removed, fn)
+    end
+
+    notify
+  end
+  # :startdoc:
+ 
+
+  private
+
+  # EventMachine cannot notify us when new files are added to the watched
+  # directory. The event loop will run at the configured interval and look
+  # for files that have been added or files that have become stable.
+  #
+  def _run_loop
+    start = Time.now.to_f
+
+    _find_added
+    _find_stable
+
+    notify
+
+    nap_time = @interval - (Time.now.to_f - start)
+    nap_time = 0.001 unless nap_time > 0
+    @timer = EventMachine.add_timer nap_time, @run_loop
+  end
+
+  # From the list of files in the watched directory, find those that we are
+  # not currently watching and add them to the watch list. Generate "added"
+  # events for those newly found files.
+  #
+  def _find_added
+    cur = list_files
+    prev = @files.keys
+    added = cur - prev
+
+    added.each do |fn|
+      @files[fn] = _watch_file(fn).stat
+      @events << ::DirectoryWatcher::Event.new(:added, fn)
+    end
+  end
+
+  # Iterate over the FileStat instances looking for those with non-nil
+  # stable counts. Decrement these counts and generate "stable" events for
+  # those files whose count reaches zero.
+  #
+  def _find_stable
+    @files.each do |fn, stat|
+      next if stat.stable.nil?
+      stat.stable -= 1
+      if stat.stable <= 0
+        @events << ::DirectoryWatcher::Event.new(:stable, fn)
+        stat.stable = nil
+      end
+    end
+  end
+
+  # Create and return a new Watcher instance for the given filename _fn_.
+  #
+  def _watch_file( fn )
+    @watchers[fn] = EventMachine.watch_file fn, Watcher, self
+  end
+
+  # :stopdoc:
+  #
+  # This is our tailored implementation of the EventMachine FileWatch class.
+  # It receives notifications of file events and provides a mechanism to
+  # translate the EventMachine events into DirectoryWatcher events.
+  #
+  class Watcher < EventMachine::FileWatch
+    def initialize( scanner )
+      @scanner = scanner
+      @active = true
+    end
+
+    def stat
+      return unless test ?e, @path
+      stat = File.stat @path
+      ::DirectoryWatcher::FileStat.new(stat.mtime, stat.size, @scanner.stable)
+    end
+
+    def active?() @active; end
+    def event!() @scanner._event!(self); end
+    def unbind() @active = false; end
+    def file_deleted() EventMachine.next_tick {event!}; end
+
+    alias :file_modified :event!
+    alias :file_moved :event!
+  end
+  # :startdoc:
+
+end  # class DirectoryWatcher::EmScanner
+end  # if HAVE_EM
+
+# EOF

data/lib/directory_watcher/rev_scanner.rb

@@ -0,0 +1,183 @@
+
+begin
+  require 'rev'
+  DirectoryWatcher::HAVE_REV = true
+rescue LoadError
+  DirectoryWatcher::HAVE_REV = false
+end
+
+if DirectoryWatcher::HAVE_REV
+
+# The RevScanner uses the Rev loop to monitor changes to files in the
+# watched directory. This scanner is more efficient than the pure Ruby
+# scanner because it relies on the operating system kernel notifictions
+# instead of a periodic polling and stat of every file in the watched
+# directory (the technique used by the Scanner class).
+#
+class DirectoryWatcher::RevScanner < ::DirectoryWatcher::Scanner
+
+  # call-seq:
+  #    RevScanner.new { |events| block }
+  #
+  # Create a Rev based scanner that will generate file events and pass
+  # those events (as an array) to the given _block_.
+  #
+  def initialize( &block )
+    super(&block)
+    @watchers = {}
+  end
+
+  # Start the Rev scanner loop. If the scanner is already running, this method
+  # will return without taking any action.
+  #
+  def start
+    return if running?
+
+    @timer = Timer.new self
+    @thread = Thread.new {
+      rev_loop = Thread.current._rev_loop
+      @files.keys.each do |fn|
+        if test ?e, fn
+          _watch_file fn
+          next
+        end
+
+        @files.delete fn
+        @events << ::DirectoryWatcher::Event.new(:removed, fn)
+      end
+
+      @timer.attach rev_loop
+      rev_loop.run
+    }
+  end
+
+  # Stop the Rev scanner loop. If the scanner is already stopped, this method
+  # will return without taking any action.
+  #
+  def stop
+    return unless running?
+
+    @thread._rev_loop.stop rescue nil
+    @thread = nil
+
+    @timer.detach
+    @timer = nil
+
+    @watchers.each_value {|w| w.detach}
+    @watchers.clear
+
+    notify
+  end
+
+  # :stopdoc:
+  #
+  # This callback is invoked by a Watcher instance when some change has
+  # occured on the file. The scanner determines if the file has been
+  # modified or deleted and notifies the directory watcher accordingly.
+  #
+  def _on_change( watcher )
+    fn = watcher.path
+    stat = watcher.stat
+
+    if stat
+      if @files[fn] != stat
+        @files[fn] = stat
+        @events << ::DirectoryWatcher::Event.new(:modified, fn)
+      end
+    else
+      watcher.detach
+      @watchers.delete fn
+      @files.delete fn
+      @events << ::DirectoryWatcher::Event.new(:removed, fn)
+    end
+
+    notify
+  end
+
+  # This callback is invoked by the Timer instance when it is triggered by
+  # the Rev loop. This method will check for added files and stable files
+  # and notify the directory watcher accordingly.
+  #
+  def _on_timer
+    _find_added
+    _find_stable
+    notify
+  end
+  # :startdoc:
+
+
+  private
+
+  # From the list of files in the watched directory, find those that we are
+  # not currently watching and add them to the watch list. Generate "added"
+  # events for those newly found files.
+  #
+  def _find_added
+    cur = list_files
+    prev = @files.keys
+    added = cur - prev
+
+    added.each do |fn|
+      @files[fn] = _watch_file(fn).stat
+      @events << ::DirectoryWatcher::Event.new(:added, fn)
+    end
+  end
+
+  # Iterate over the FileStat instances looking for those with non-nil
+  # stable counts. Decrement these counts and generate "stable" events for
+  # those files whose count reaches zero.
+  #
+  def _find_stable
+    @files.each do |fn, stat|
+      next if stat.stable.nil?
+      stat.stable -= 1
+      if stat.stable <= 0
+        @events << ::DirectoryWatcher::Event.new(:stable, fn)
+        stat.stable = nil
+      end
+    end
+  end
+
+  # Create and return a new Watcher instance for the given filename _fn_.
+  #
+  def _watch_file( fn )
+    w = Watcher.new(fn, self)
+    w.attach(@thread ? @thread._rev_loop : Thread.current._rev_loop)
+    @watchers[fn] = w
+  end
+
+  # :stopdoc:
+  #
+  class Watcher < Rev::StatWatcher
+    def initialize( fn, scanner )
+      super(fn, scanner.interval)
+      @scanner = scanner
+    end
+
+    def on_change
+      @scanner._on_change self
+    end
+
+    def stat
+      return unless test ?e, path
+      stat = File.stat path
+      ::DirectoryWatcher::FileStat.new(stat.mtime, stat.size, @scanner.stable)
+    end
+  end
+
+  class Timer < Rev::TimerWatcher
+    def initialize( scanner )
+      super(scanner.interval, true)
+      @scanner = scanner
+    end
+
+    def on_timer
+      @scanner._on_timer
+    end
+  end
+  # :startdoc:
+
+end  # class DirectoryWatcher::RevScanner
+end  # if DirectoryWatcher::HAVE_REV
+
+# EOF

data/lib/directory_watcher/scanner.rb

@@ -0,0 +1,229 @@
+
+# The Scanner is responsible for polling the watched directory at a regular
+# interval and generating events when files are modified, added or removed.
+# These events are passed to the DirectoryWatcher which notifies the
+# registered observers.
+#
+# The Scanner is a pure Ruby class, and as such it works across all Ruby
+# interpreters on the major platforms. This also means that it can be
+# processor intensive for large numbers of files or very fast update
+# intervals. Your mileage will vary, but it is something to keep an eye on.
+#
+class DirectoryWatcher::Scanner
+
+  attr_accessor :glob
+  attr_accessor :interval
+  attr_accessor :stable
+  attr_accessor :files
+
+  # call-seq:
+  #    Scanner.new { |events| block }
+  #
+  # Create a thread-based scanner that will generate file events and pass
+  # those events (as an array) to the given _block_.
+  #
+  def initialize( &block )
+    @events = []
+    @thread = nil
+    @notify = block;
+  end
+
+  # Returns +true+ if the scanner is currently running. Returns +false+ if
+  # this is not the case.
+  #
+  def running?
+    !@thread.nil?
+  end
+
+  # Start the scanner thread. If the scanner is already running, this method
+  # will return without taking any action.
+  #
+  def start
+    return if running?
+
+    @stop = false
+    @thread = Thread.new(self) {|scanner| scanner.__send__ :run_loop}
+    self
+  end
+
+  # Stop the scanner thread. If the scanner is already stopped, this method
+  # will return without taking any action.
+  #
+  def stop
+    return unless running?
+
+    @stop = true
+    @thread.wakeup if @thread.status == 'sleep'
+    @thread.join
+    self
+  ensure
+    @thread = nil
+  end
+
+  # call-seq:
+  #    reset( pre_load = false )
+  #
+  # Reset the scanner state by clearing the stored file list. Passing +true+
+  # to this method will cause the file list to be pre-loaded after it has
+  # been cleared effectively skipping the initial round of file added events
+  # that would normally be generated.
+  #
+  def reset( pre_load = false )
+    @events.clear
+    @files = (pre_load ? scan_files : Hash.new)
+  end
+
+  # call-seq:
+  #    join( limit = nil )
+  #
+  # If the scanner thread is running, the calling thread will suspend
+  # execution and run the scanner thread. This method does not return until
+  # the scanner thread is stopped or until _limit_ seconds have passed.
+  #
+  # If the scanner thread is not running, this method returns immediately
+  # with +nil+.
+  #
+  def join( limit = nil )
+    return unless running?
+    @thread.join limit
+  end
+
+  # Performs exactly one scan of the directory for file changes and notifies
+  # the observers.
+  #
+  def run_once
+    files = scan_files
+    keys = [files.keys, @files.keys]  # current files, previous files
+
+    find_added(files, *keys)
+    find_modified(files, *keys)
+    find_removed(*keys)
+
+    notify
+    @files = files    # store the current file list for the next iteration
+    self
+  end
+
+
+  private
+
+  # Using the configured glob pattern, scan the directory for all files and
+  # return a hash with the filenames as keys and +FileStat+ objects as the
+  # values. The +FileStat+ objects contain the mtime and size of the file.
+  #
+  def scan_files
+    files = {}
+    @glob.each do |glob|
+      Dir.glob(glob).each do |fn|
+        begin
+          stat = File.stat fn
+          next unless stat.file?
+          files[fn] = ::DirectoryWatcher::FileStat.new(stat.mtime, stat.size)
+        rescue SystemCallError; end
+      end
+    end
+    files
+  end
+
+  # Using the configured glob pattern, scan the directory for all files and
+  # return an array of the filenames found.
+  #
+  def list_files
+    files = []
+    @glob.each do |glob|
+      Dir.glob(glob).each {|fn| files << fn if test ?f, fn}
+    end
+    files
+  end
+
+
+  # Calling this method will enter the scanner's run loop. The
+  # calling thread will not return until the +stop+ method is called.
+  #
+  # The run loop is responsible for scanning the directory for file changes,
+  # and then dispatching events to registered listeners.
+  #
+  def run_loop
+    until @stop
+      start = Time.now.to_f
+
+      run_once
+
+      nap_time = @interval - (Time.now.to_f - start)
+      sleep nap_time if nap_time > 0
+    end
+  end
+
+  # call-seq:
+  #    find_added( files, cur, prev )
+  #
+  # Taking the list of current files, _cur_, and the list of files found
+  # previously, _prev_, figure out which files have been added and generate
+  # a new file added event for each.
+  #
+  def find_added( files, cur, prev )
+    added = cur - prev
+    added.each do |fn|
+      files[fn].stable = @stable
+      @events << ::DirectoryWatcher::Event.new(:added, fn)
+    end
+    self
+  end
+
+  # call-seq:
+  #    find_removed( cur, prev )
+  #
+  # Taking the list of current files, _cur_, and the list of files found
+  # previously, _prev_, figure out which files have been removed and
+  # generate a new file removed event for each.
+  #
+  def find_removed( cur, prev )
+    removed = prev - cur
+    removed.each {|fn| @events << ::DirectoryWatcher::Event.new(:removed, fn)}
+    self
+  end
+
+  # call-seq:
+  #    find_modified( files, cur, prev )
+  #
+  # Taking the list of current files, _cur_, and the list of files found
+  # previously, _prev_, find those that are common between them and determine
+  # if any have been modified. Generate a new file modified event for each
+  # modified file. Also, by looking at the stable count in the _files_ hash,
+  # figure out if any files have become stable since being added or modified.
+  # Generate a new stable event for each stabilized file.
+  #
+  def find_modified( files, cur, prev )
+    (cur & prev).each do |key|
+      cur_stat, prev_stat = files[key], @files[key]
+
+      # if the modification time or the file size differs from the last
+      # time it was seen, then create a :modified event
+      if cur_stat != prev_stat
+        @events << ::DirectoryWatcher::Event.new(:modified, key)
+        cur_stat.stable = @stable
+
+      # otherwise, if the count is not nil see if we need to create a
+      # :stable event
+      elsif !prev_stat.stable.nil?
+        cur_stat.stable = prev_stat.stable - 1
+        if cur_stat.stable <= 0
+          @events << ::DirectoryWatcher::Event.new(:stable, key)
+          cur_stat.stable = nil
+        end
+      end
+    end
+    self
+  end
+
+  # If there are queued files events, then invoke the notify block given
+  # when the scanner was created. The file events array is cleared at the
+  # end of this method call.
+  #
+  def notify
+    @notify.call(@events) unless @events.empty?
+  ensure
+    @events.clear
+  end
+
+end  # class DirectoryWatcher::Scanner

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: directory_watcher
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors: 
 - Tim Pease
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-12 00:00:00 -06:00
+date: 2009-10-21 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.5.0
+        version: 2.5.1
     version: 
 description: ""
 email: tim.pease@gmail.com
@@ -36,6 +36,9 @@ files:
 - README.txt
 - Rakefile
 - lib/directory_watcher.rb
+- lib/directory_watcher/em_scanner.rb
+- lib/directory_watcher/rev_scanner.rb
+- lib/directory_watcher/scanner.rb
 - tasks/ann.rake
 - tasks/bones.rake
 - tasks/gem.rake
@@ -51,6 +54,8 @@ files:
 - tasks/zentest.rake
 has_rdoc: true
 homepage: http://codeforpeople.rubyforge.org/directory_watcher
+licenses: []
+
 post_install_message: 
 rdoc_options: 
 - --main
@@ -72,9 +77,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: codeforpeople
-rubygems_version: 1.3.1
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: A class for watching files within a directory and generating events when those files change
 test_files: []