directory_watcher 1.4.1 → 1.5.1

data/lib/directory_watcher/paths.rb

@@ -0,0 +1,55 @@
+class DirectoryWatcher
+  # Paths contains helpful methods to determine paths of files inside the
+  # DirectoryWatcher library
+  #
+  module Paths
+    # The root directory of the project is considered the parent directory of
+    # the 'lib' directory.
+    #
+    # Returns The full expanded path of the parent directory of 'lib' going up
+    # the path from the current file. Trailing File::SEPARATOR is guaranteed
+    #
+    def root_dir
+      path_parts = ::File.expand_path(__FILE__).split(::File::SEPARATOR)
+      lib_index = path_parts.rindex("lib")
+      return path_parts[0...lib_index].join(::File::SEPARATOR) + ::File::SEPARATOR
+    end
+
+    # Return a path relative to the 'lib' directory in this project
+    #
+    def lib_path(*args,&block)
+      sub_path('lib', *args, &block)
+    end
+
+    # Return a path relative to the 'root' directory in the project
+    #
+    def path(*args,&block)
+      sub_path('', *args, &block)
+    end
+
+    # Calculate the full expanded path of the item with respect to a sub path of
+    # 'root_dir'
+    #
+    def sub_path(sub,*args,&block)
+      rv = ::File.join(root_dir, sub) + ::File::SEPARATOR
+      rv = ::File.join(rv, *args) if args
+      if block
+        with_load_path( rv ) do
+          rv = block.call
+        end
+      end
+      return rv
+    end
+
+    # Execute a block in the context of a path added to $LOAD_PATH
+    #
+    def with_load_path(path, &block)
+      $LOAD_PATH.unshift path
+      block.call
+    ensure
+      $LOAD_PATH.shift
+    end
+
+    extend self
+  end
+end

data/lib/directory_watcher/rev_scanner.rb

@@ -1,4 +1,3 @@
-
 begin
   require 'rev'
   DirectoryWatcher::HAVE_REV = true
@@ -8,177 +7,115 @@ end
 
 if DirectoryWatcher::HAVE_REV
 
+# Deprecated:
+#
 # 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
+# scanner because it relies on the operating system kernel notifications
 # 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
-
+# The RevScanner is essentially the exact same as the CoolioScanner with class
+# names changed and using _rev_loop instead of _coolio_loop. Unfortunately the
+# RevScanner cannot be a sub class of CoolioScanner because of C-extension
+# reasons between the rev and coolio gems
+#
+# Rev 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.
+#
+class DirectoryWatcher::RevScanner < ::DirectoryWatcher::EventableScanner
   # 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_.
+  #    RevScanner.new( glob, interval, collection_queue )
   #
-  def initialize( &block )
-    super(&block)
-    @watchers = {}
+  def initialize( glob, interval, collection_queue )
+    super(glob, interval, collection_queue)
   end
 
-  # Start the Rev scanner loop. If the scanner is already running, this method
-  # will return without taking any action.
+  # Called by EventablScanner#start to start the loop up and attach the periodic
+  # timer that will poll the globs for new files.
   #
-  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
+  def start_loop_with_attached_scan_timer
+    return if @loop_thread
+    @timer = ScanTimer.new( self )
+    @loop_thread = Thread.new {
+      @timer.attach(event_loop)
+      event_loop.run
     }
   end
 
-  # Stop the Rev scanner loop. If the scanner is already stopped, this method
-  # will return without taking any action.
+  # Called by EventableScanner#stop to stop the loop as part of the shutdown
+  # process.
   #
-  def stop
-    return unless running?
-
-    @timer.detach
-    @timer = nil
-
-    @watchers.each_value {|w| w.detach}
-    @watchers.clear
-
-    notify
-
-    @thread._rev_loop.stop rescue nil
-    @thread.kill    # for some reason the rev loop is not returning after stopping
-    @thread = nil
+  def stop_loop
+    if @loop_thread then
+      event_loop.stop rescue nil
+      @loop_thread.kill
+      @loop_thread = nil
+    end
   end
 
-  # :stopdoc:
+  # Return the rev loop object
   #
-  # 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.
+  # This is used during the startup, shutdown process and for the Watcher to
+  # attach and detach from the event loop
   #
-  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
+  def event_loop
+    if @loop_thread then
+      @loop_thread._rev_loop
     else
-      watcher.detach
-      @watchers.delete fn
-      @files.delete fn
-      @events << ::DirectoryWatcher::Event.new(:removed, fn)
+      Thread.current._rev_loop
     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.
+  # :stopdoc:
   #
-  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.
+  # Watch files using the Rev::StatWatcher.
   #
-  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
+  # The rev +on_change+ callback is converted to the appropriate +on_removed+
+  # and +on_modified+ callbacks for the EventableScanner.
+  class Watcher < ::Rev::StatWatcher
+    def self.watch(fn, scanner )
+      new(fn, scanner)
     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)
+      # for file watching, we want to make sure this happens at a reasonable
+      # value, so set it to 0 if the scanner.interval is > 5 seconds. This will
+      # make it use the system value, and allow us to test.
+      i = scanner.interval < 5 ? scanner.interval : 0
+      super(fn, i)
       @scanner = scanner
+      attach(scanner.event_loop)
     end
 
+    # Rev uses on_change so we convert that to the appropriate
+    # EventableScanner calls. Unlike Coolio, Rev's on_change() takes no
+    # parameters
+    #
     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)
+      if File.exist?(path) then
+        @scanner.on_removed(self, ::DirectoryWatcher::FileStat.for_removed_path(path))
+      else
+        stat = File.stat(path)
+        @scanner.on_modified(self, ::DirectoryWatcher::FileStat.new(path, stat.mtime, stat.size))
+      end
     end
   end
 
-  class Timer < Rev::TimerWatcher
+  # Periodically execute a Scan. Hook this into the EventableScanner#on_scan
+  #
+  class ScanTimer< Rev::TimerWatcher
     def initialize( scanner )
       super(scanner.interval, true)
       @scanner = scanner
     end
 
-    def on_timer
-      @scanner._on_timer
+    def on_timer( *args )
+      @scanner.on_scan
     end
   end
-  # :startdoc:
 
 end  # class DirectoryWatcher::RevScanner
-end  # if DirectoryWatcher::HAVE_REV
 
-# EOF
+end  # if DirectoryWatcher::HAVE_REV

data/lib/directory_watcher/scan.rb

@@ -0,0 +1,72 @@
+# A Scan is the scan of a full directory structure with the ability to iterate
+# over the results, or return them as a full dataset
+#
+#   results = Scan.new( globs ).run
+#
+class DirectoryWatcher::Scan
+
+  def initialize( globs = Array.new )
+    @globs = [ globs ].flatten
+    @results = Array.new
+  end
+
+  # Run the entire scan and collect all the results. The Scan will only ever
+  # be run once.
+  #
+  # Return the array of FileStat results
+  def run
+    results
+  end
+
+  # Return the results of the scan. If the scan has not been run yet, then run
+  # it
+  def results
+    @results = collect_all_stats if @results.empty?
+    return @results
+  end
+
+  #######
+  private
+  #######
+
+  # Collect all the Stats into an Array and return them
+  #
+  def collect_all_stats
+    r = []
+    each { |stat| r << stat }
+    return r
+  end
+
+  # Iterate over each glob, yielding it
+  #
+  def each_glob( &block )
+    @globs.each do |glob|
+      yield glob
+    end
+  end
+
+  # Iterate over each item that matches the glob.
+  # The item yielded is a ::DirectoryWatcher::FileStat object.
+  #
+  def each( &block )
+    each_glob do |glob|
+      Dir.glob(glob).each do |fn|
+        if stat = file_stat( fn ) then
+          yield stat if block_given?
+        end
+      end
+    end
+  end
+
+  # Return the stat of of the file in question. If the item is not a file,
+  # then return the value of the passed in +if_not_file+
+  #
+  def file_stat( fn, if_not_file = false )
+    stat = File.stat fn
+    return if_not_file unless stat.file?
+    return DirectoryWatcher::FileStat.new( fn, stat.mtime, stat.size )
+  rescue SystemCallError => e
+    # swallow
+    $stderr.puts "Error Stating #{fn} : #{e}"
+  end
+end

data/lib/directory_watcher/scan_and_queue.rb

@@ -0,0 +1,22 @@
+# ScanAndQueue creates a Scan from its input globs and then sends that Scan to
+# its Queue.
+#
+# Every time scan_and_queue is called a new scan is created an sent to the
+# queue.
+class DirectoryWatcher::ScanAndQueue
+
+  def initialize( glob, queue )
+    @globs = glob
+    @queue =queue
+  end
+
+  # Create and run a Scan and submit it to the Queue.
+  #
+  # Returns the Scan that was run
+  def scan_and_queue
+    scan = ::DirectoryWatcher::Scan.new( @globs )
+    scan.run
+    @queue.enq scan
+    return scan
+  end
+end

data/lib/directory_watcher/scanner.rb

@@ -1,8 +1,6 @@
-
 # 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.
+# interval and generating a Scan which it will then send down the collection
+# queue to the Collector.
 #
 # 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
@@ -10,220 +8,39 @@
 # 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
+  include DirectoryWatcher::Threaded
+  include DirectoryWatcher::Logable
 
   # call-seq:
-  #    find_added( files, cur, prev )
+  #    Scanner.new( configuration )
   #
-  # 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.
+  # From the Configuration instance passed in Scanner uses:
   #
-  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 )
+  # glob             - Same as that in DirectoryWatcher
+  # interval         - Same as that in DirectoryWatcher
+  # collection_queue - The Queue to send the Scans too.
+  #                    the other end of this queue is connected to a Collector
   #
-  # 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.
+  # The Scanner is not generally used out side of a DirectoryWatcher so this is
+  # more of an internal API
   #
-  def find_removed( cur, prev )
-    removed = prev - cur
-    removed.each {|fn| @events << ::DirectoryWatcher::Event.new(:removed, fn)}
-    self
+  #def initialize( glob, interval, collection_queue )
+  def initialize( config )
+    @config = config
+    @scan_and_queue = ::DirectoryWatcher::ScanAndQueue.new( @config.glob, @config.collection_queue )
   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
+  # Set the interval before starting the loop.
+  # This allows for interval to be set AFTER the DirectoryWatcher instance is
+  # allocated but before it is started.
+  def before_starting
+    self.interval = @config.interval
   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.
+  # Performs exactly one scan of the directory and sends the
+  # results to the Collector
   #
-  def notify
-    @notify.call(@events) unless @events.empty?
-  ensure
-    @events.clear
+  def run
+    @scan_and_queue.scan_and_queue
   end
-
-end  # class DirectoryWatcher::Scanner
+end