directory_watcher 1.4.1 → 1.5.1

data/lib/directory_watcher/threaded.rb

@@ -0,0 +1,277 @@
+#
+# == Synopsis
+# The Threaded module is used to perform some activity at a specified
+# interval.
+#
+# == Details
+# Sometimes it is useful for an object to have its own thread of execution
+# to perform a task at a recurring interval. The Threaded module
+# encapsulates this functionality so you don't have to write it yourself. It
+# can be used with any object that responds to the +run+ method.
+#
+# The threaded object is run by calling the +start+ method. This will create
+# a new thread that will invoke the +run+ method at the desired interval.
+# Just before the thread is created the +before_starting+ method will be
+# called (if it is defined by the threaded object). Likewise, after the
+# thread is created the +after_starting+ method will be called (if it is
+# defined by the threaded object).
+#
+# The threaded object is stopped by calling the +stop+ method. This sets an
+# internal flag and then wakes up the thread. The thread gracefully exits
+# after checking the flag. Like the start method, before and after methods
+# are defined for stopping as well. Just before the thread is stopped the
+# +before_stopping+ method will be called (if it is defined by the threaded
+# object). Likewise, after the thread has died the +after_stopping+ method
+# will be called (if it is defined by the threaded object).
+#
+# Calling the +join+ method on a threaded object will cause the calling
+# thread to wait until the threaded object has stopped. An optional timeout
+# parameter can be given.
+#
+module DirectoryWatcher::Threaded
+
+  # This method will be called by the activity thread at the desired
+  # interval. Implementing classes are expect to provide this
+  # functionality.
+  #
+  def run
+    raise NotImplementedError,
+         'The run method must be defined by the threaded object.'
+  end
+
+  # Start the activity thread. If already started this method will return
+  # without taking any action.
+  #
+  # If the including class defines a 'before_starting' method, it will be
+  # called before the thread is created and run. Likewise, if the
+  # including class defines an 'after_starting' method, it will be called
+  # after the thread is created.
+  #
+  def start
+    return self if _activity_thread.running?
+
+    before_starting if self.respond_to?(:before_starting)
+    @_activity_thread.start self
+    after_starting if self.respond_to?(:after_starting)
+    self
+  end
+
+  # Stop the activity thread. If already stopped this method will return
+  # without taking any action.
+  #
+  # If the including class defines a 'before_stopping' method, it will be
+  # called before the thread is stopped. Likewise, if the including class
+  # defines an 'after_stopping' method, it will be called after the thread
+  # has stopped.
+  #
+  def stop
+    return self unless _activity_thread.running?
+
+    before_stopping if self.respond_to?(:before_stopping)
+    @_activity_thread.stop
+    self
+  end
+
+  # Stop the activity thread from doing work. This will not stop the activity
+  # thread, it will just stop it from calling the 'run' method on every
+  # iteration. It will also not increment the number of iterations it has run.
+  def pause
+    @_activity_thread.working = false
+  end
+
+  # Resume the activity thread
+  def resume
+    @_activity_thread.working = true
+  end
+
+  # Wait on the activity thread.  If the thread is already stopped, this
+  # method will return without taking any action.  Otherwise, this method
+  # does not return until the activity thread has stopped, or a specific
+  # number of iterations has passed since this method was called.
+  #
+  def wait( limit = nil )
+    return self unless _activity_thread.running?
+    initial_iterations = @_activity_thread.iterations
+    loop {
+      break unless @_activity_thread.running?
+      break if limit and @_activity_thread.iterations > ( initial_iterations + limit )
+      Thread.pass
+    }
+  end
+
+  # If the activity thread is running, the calling thread will suspend
+  # execution and run the activity thread. This method does not return until
+  # the activity thread is stopped or until _limit_ seconds have passed.
+  #
+  # If the activity thread is not running, this method returns immediately
+  # with +nil+.
+  #
+  def join( limit = nil )
+    _activity_thread.join(limit) ? self : nil
+  end
+
+  # Returns +true+ if the activity thread is running. Returns +false+
+  # otherwise.
+  #
+  def running?
+    _activity_thread.running?
+  end
+
+  # Returns +true+ if the activity thread has finished its maximum
+  # number of iterations or the thread is no longer running.
+  # Returns +false+ otherwise.
+  #
+  def finished_iterations?
+    return true unless _activity_thread.running?
+    @_activity_thread.finished_iterations?
+  end
+
+  # Returns the status of threaded object.
+  #
+  #    'sleep'    : sleeping or waiting on I/O
+  #    'run'      : executing
+  #    'aborting' : aborting
+  #    false      : not running or terminated normally
+  #    nil        : terminated with an exception
+  #
+  # If this method returns +nil+, then calling join on the threaded object
+  # will cause the exception to be raised in the calling thread.
+  #
+  def status
+    return false if _activity_thread.thread.nil?
+    @_activity_thread.thread.status
+  end
+
+  # Sets the number of seconds to sleep between invocations of the
+  # threaded object's 'run' method.
+  #
+  def interval=( value )
+    value = Float(value)
+    raise ArgumentError, "Sleep interval must be >= 0" unless value >= 0
+    _activity_thread.interval = value
+  end
+
+  # Returns the number of seconds to sleep between invocations of the
+  # threaded object's 'run' method.
+  #
+  def interval
+    _activity_thread.interval
+  end
+
+  # Sets the maximum number of invocations of the threaded object's
+  # 'run' method
+  #
+  def maximum_iterations=( value )
+    unless value.nil?
+      value = Integer(value)
+      raise ArgumentError, "maximum iterations must be >= 1" unless value >= 1
+    end
+
+    _activity_thread.maximum_iterations = value
+  end
+
+  # Returns the maximum number of invocations of the threaded
+  # object's 'run' method
+  #
+  def maximum_iterations
+    _activity_thread.maximum_iterations
+  end
+
+  # Returns the number of iterations of the threaded object's 'run' method
+  # completed thus far.
+  #
+  def iterations
+    _activity_thread.iterations
+  end
+
+  # Set to +true+ to continue running the threaded object even if an error
+  # is raised by the +run+ method. The default behavior is to stop the
+  # activity thread when an error is raised by the run method.
+  #
+  # A SystemExit will never be caught; it will always cause the Ruby
+  # interpreter to exit.
+  #
+  def continue_on_error=( value )
+    _activity_thread.continue_on_error = (value ? true : false)
+  end
+
+  # Returns +true+ if the threaded object should continue running even if an
+  # error is raised by the run method. The default is to return +false+. The
+  # threaded object will stop running when an error is raised.
+  #
+  def continue_on_error?
+    _activity_thread.continue_on_error
+  end
+
+  # :stopdoc:
+  def _activity_thread
+    @_activity_thread ||= ::DirectoryWatcher::Threaded::ThreadContainer.new(60, 0, nil, false);
+  end  # @private
+
+  # @private
+  ThreadContainer = Struct.new( :interval, :iterations, :maximum_iterations, :continue_on_error, :thread, :running, :working) {
+    def start( threaded )
+
+      self.working = true
+      self.running = true
+      self.iterations = 0
+      self.thread = Thread.new { run threaded }
+      Thread.pass
+    end  # @private
+
+    def stop
+      self.running = false
+      thread.wakeup
+    end  # @private
+
+    def run( threaded )
+      loop do
+        begin
+          break unless running?
+          do_work( threaded )
+
+          sleep interval if running?
+        rescue SystemExit; raise
+        rescue Exception => err
+          if continue_on_error
+            $stderr.puts err
+          else
+            $stderr.puts err
+            raise err
+          end
+        end
+      end
+    ensure
+      if threaded.respond_to?(:after_stopping) and !self.running
+        threaded.after_stopping
+      end
+      self.running = false
+    end  # @private
+
+    def join( limit = nil )
+      return if thread.nil?
+      limit ? thread.join(limit) : thread.join
+    end  # @private
+
+    def do_work( threaded )
+      if working then
+        threaded.run
+
+        if maximum_iterations
+          self.iterations += 1
+          if finished_iterations?
+            self.running = false
+          end
+        end
+      end
+    end # @private
+
+    def finished_iterations?
+      return true if maximum_iterations and (iterations >= maximum_iterations)
+      return false
+    end  # @private
+
+    alias :running? :running
+  }
+  # :startdoc:
+end

data/lib/directory_watcher/version.rb

@@ -0,0 +1,8 @@
+class DirectoryWatcher
+  module Version
+    def version
+      File.read(DirectoryWatcher.path('version.txt')).strip
+    end
+    extend self
+  end
+end

data/spec/directory_watcher_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe DirectoryWatcher do
+  it "has a version" do
+    DirectoryWatcher.version.should =~ /\d\.\d\.\d/
+  end
+end
+
+describe "Scanners" do
+  [ nil, :em, :coolio ].each do |scanner|
+#  [ :rev ].each do |scanner|
+    context "#{scanner} Scanner" do
+
+      let( :default_options       ) { { :glob => "**/*", :interval => 0.05}                      }
+      let( :options               ) { default_options.merge( :scanner => scanner )               }
+      let( :options_with_pre_load ) { options.merge( :pre_load => true )                         }
+      let( :options_with_stable   ) { options.merge( :stable => 2 )                              }
+      let( :options_with_glob     ) { options.merge( :glob => '**/*.42' )                        }
+      let( :options_with_persist  ) { options.merge( :persist => scratch_path( 'persist.yml' ) ) }
+
+      let( :directory_watcher               ) { DirectoryWatcher.new( @scratch_dir, options ) }
+      let( :directory_watcher_with_pre_load ) { DirectoryWatcher.new( @scratch_dir, options_with_pre_load ) }
+      let( :directory_watcher_with_stable   ) { DirectoryWatcher.new( @scratch_dir, options_with_stable   ) }
+      let( :directory_watcher_with_glob     ) { DirectoryWatcher.new( @scratch_dir, options_with_glob     ) }
+      let( :directory_watcher_with_persist  ) { DirectoryWatcher.new( @scratch_dir, options_with_persist  ) }
+
+      let( :scenario               ) { DirectoryWatcherSpecs::Scenario.new( directory_watcher) }
+      let( :scenario_with_pre_load ) { DirectoryWatcherSpecs::Scenario.new( directory_watcher_with_pre_load ) }
+      let( :scenario_with_stable   ) { DirectoryWatcherSpecs::Scenario.new( directory_watcher_with_stable   ) }
+      let( :scenario_with_glob     ) { DirectoryWatcherSpecs::Scenario.new( directory_watcher_with_glob     ) }
+      let( :scenario_with_persist  ) { DirectoryWatcherSpecs::Scenario.new( directory_watcher_with_persist  ) }
+
+      it_should_behave_like 'Scanner'
+    end
+  end
+end
+

data/spec/paths_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe DirectoryWatcher::Paths do
+  it "has a libpath" do
+    DirectoryWatcher.lib_path.should == File.expand_path( "../../lib", __FILE__) + ::File::SEPARATOR
+  end
+end

data/spec/scanner_scenarios.rb

@@ -0,0 +1,236 @@
+shared_examples_for "Scanner" do
+  context "Event Types"do
+    it "sends added events" do
+
+      scenario.run_and_wait_for_event_count(1) do
+        touch( scratch_path( 'added' ) )
+      end.stop
+
+      scenario.events.should be_events_like( [[ :added, 'added' ]] )
+    end
+
+    it "sends modified events for file size modifications" do
+
+      modified_file = scratch_path( 'modified' )
+      scenario.run_and_wait_for_event_count(1) do
+        touch( modified_file )
+      end.run_and_wait_for_event_count(1) do
+        append_to( modified_file )
+      end.stop
+
+      scenario.events.should be_events_like( [[ :added, 'modified'], [ :modified, 'modified']] )
+    end
+
+    it "sends modified events for mtime modifications" do
+      modified_file = scratch_path( 'modified' )
+
+      scenario.run_and_wait_for_event_count(1) do
+        touch( modified_file, Time.now - 5 )
+      end.run_and_wait_for_event_count(1) do
+        touch( modified_file )
+      end.stop
+
+      scenario.events.should be_events_like( [[ :added, 'modified'], [ :modified, 'modified']] )
+    end
+
+    it "sends removed events" do
+      removed_file = scratch_path( 'removed' )
+      scenario.run_and_wait_for_event_count(1) do
+        touch( removed_file, Time.now )
+      end.run_and_wait_for_event_count(1) do
+        File.unlink( removed_file )
+      end.stop
+
+      scenario.events.should be_events_like [ [:added, 'removed'], [:removed, 'removed'] ]
+    end
+
+    it "sends stable events" do
+      stable_file = scratch_path( 'stable' )
+      scenario_with_stable.run_and_wait_for_event_count(2) do |s|
+        touch( stable_file )
+        # do nothing wait for the stable event.
+      end.stop
+
+      scenario_with_stable.events.should be_events_like [ [:added, 'stable'], [:stable, 'stable'] ]
+    end
+
+    it "only sends stable events once" do
+      stable_file = scratch_path( 'stable' )
+      scenario_with_stable.run_and_wait_for_scan_count(5) do |s|
+        touch( stable_file )
+        # do nothing
+      end.stop
+
+      scenario_with_stable.events.size.should == 2
+    end
+
+    it "events are not sent for directory creation" do
+      a_dir = scratch_path( 'subdir' )
+
+      scenario.run_and_wait_for_scan_count(2) do
+        Dir.mkdir( a_dir )
+      end.stop
+
+      scenario.events.should be_empty
+    end
+
+    it "sends events for files in sub directories" do
+      a_dir = scratch_path( 'subdir' )
+
+      scenario.run_and_wait_for_event_count(1) do
+        Dir.mkdir( a_dir )
+        subfile = File.join( a_dir, 'subfile' )
+        touch( subfile )
+      end.stop
+
+      scenario.events.should be_events_like [ [:added, 'subfile'] ]
+    end
+  end
+
+  context "run_once" do
+    it "can be run on command via 'run_once'" do
+      one_shot_file = scratch_path( "run_once" )
+      scenario.run_once_and_wait_for_event_count(1) do
+        touch( one_shot_file )
+      end.stop
+      scenario.events.should be_events_like [ [:added, 'run_once'] ]
+    end
+  end
+
+  context "pre_load option " do
+    it "skips initial add events" do
+      modified_file = scratch_path( 'modified' )
+      touch( modified_file, Time.now - 5 )
+
+      scenario_with_pre_load.run_and_wait_for_event_count(1) do
+        touch( modified_file )
+      end.stop
+
+      scenario_with_pre_load.events.should be_events_like( [[ :modified, 'modified']] )
+    end
+  end
+
+  context "globbing" do
+    it "only sends events for files that match" do
+      non_matching = scratch_path( 'no-match' )
+      matching = scratch_path( 'match.42' )
+
+      scenario_with_glob.run_and_wait_for_event_count(1) do
+        touch( non_matching )
+        touch( matching, Time.now - 5 )
+      end.run_and_wait_for_event_count(1) do
+        touch( matching )
+      end.stop
+
+      scenario_with_glob.events.should be_events_like( [[ :added, 'match.42' ], [ :modified, 'match.42' ]] )
+    end
+  end
+
+  context "running?" do
+    it "is true when the watcher is running" do
+      directory_watcher.start
+      directory_watcher.running?.should be_true
+      directory_watcher.stop
+    end
+
+    it "is false when the watcher is not running" do
+      directory_watcher.running?.should be_false
+      directory_watcher.start
+      directory_watcher.running?.should be_true
+      directory_watcher.stop
+      directory_watcher.running?.should be_false
+    end
+  end
+
+  context "persistence" do
+    it "saves the current state of the system when the watcher is stopped" do
+      modified_file = scratch_path( 'modified' )
+      scenario_with_persist.run_and_wait_for_event_count(1) do
+        touch( modified_file, Time.now - 20 )
+      end.run_and_wait_for_event_count(1) do
+        touch( modified_file, Time.now - 10 )
+      end.stop
+
+      scenario_with_persist.events.should be_events_like( [[ :added, 'modified'], [ :modified, 'modified' ]] )
+
+      scenario_with_persist.reset
+      scenario_with_persist.resume
+      Thread.pass until scenario_with_persist.events.size >= 1
+      scenario_with_persist.pause
+
+      scenario_with_persist.run_and_wait_for_event_count(1) do
+        touch( modified_file )
+      end.stop
+
+      scenario_with_persist.events.should be_events_like( [[:added, 'persist.yml'], [ :modified, 'modified' ]] )
+    end
+  end
+
+  context "sorting" do
+    [:ascending, :descending].each do |ordering|
+      context "#{ordering}" do
+        context "file name" do
+          let( :filenames ) { ('a'..'z').sort_by {rand} }
+          let( :options   ) { default_options.merge( :order_by => ordering ) }
+          before do
+            filenames.each do |p|
+              touch( scratch_path( p ))
+            end
+          end
+
+          it "#{ordering}" do
+            scenario.run_and_wait_for_event_count(filenames.size) do
+              # wait
+            end
+            final_events = filenames.sort.map { |p| [:added, p] }
+            final_events.reverse! if ordering == :descending
+            scenario.events.should be_events_like( final_events )
+          end
+        end
+
+        context "mtime" do
+          let( :current_time ) { Time.now }
+          let( :basenames    ) { ('a'..'z').to_a }
+          let( :delta_times  ) { unique_integer_list( basenames.size, 5000 ) }
+          let( :filenames    ) { basenames.inject({}) { |h,k| h[k] = current_time - delta_times.shift; h } }
+          let( :options      ) { default_options.merge( :sort_by => :mtime, :order_by => ordering ) }
+
+          before do
+            filenames.keys.sort_by{ rand }.each do |p|
+              touch( scratch_path(p), filenames[p] )
+            end
+          end
+
+          it "#{ordering}" do
+            scenario.run_and_wait_for_event_count(filenames.size) { nil }
+            sorted_fnames = filenames.to_a.sort_by { |v| v[1] }
+            final_events = sorted_fnames.map { |fn,ts| [:added, fn] }
+            final_events.reverse! if ordering == :descending
+            scenario.events.should be_events_like( final_events )
+          end
+        end
+
+        context "size" do
+          let( :basenames  ) { ('a'..'z').to_a }
+          let( :file_sizes ) { unique_integer_list( basenames.size, 1000 ) }
+          let( :filenames  ) { basenames.inject({}) { |h,k| h[k] = file_sizes.shift; h } }
+          let( :options    ) { default_options.merge( :sort_by => :size, :order_by => ordering ) }
+
+          before do
+            filenames.keys.sort_by{ rand }.each do |p|
+              append_to( scratch_path(p), filenames[p] )
+            end
+          end
+
+          it "#{ordering}" do
+            scenario.run_and_wait_for_event_count(filenames.size) { nil }
+            sorted_fnames = filenames.to_a.sort_by { |v| v[1] }
+            final_events = sorted_fnames.map { |fn,ts| [:added, fn] }
+            final_events.reverse! if ordering == :descending
+            scenario.events.should be_events_like( final_events )
+          end
+        end
+      end
+    end
+  end
+end