directory_watcher 1.4.1 → 1.5.1

data/lib/directory_watcher/event.rb

@@ -0,0 +1,72 @@
+# 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:
+#
+#    :added      =>  file has been added to the directory
+#    :modified   =>  file has been modified (either mtime or size or both
+#                    have changed)
+#    :removed    =>  file has been removed from the directory
+#    :stable     =>  file has stabilized since being added or modified
+#
+class DirectoryWatcher::Event
+
+  attr_reader :type
+  attr_reader :path
+  attr_reader :stat
+
+  # Create one of the 4 types of events given the two stats
+  #
+  # The rules are:
+  #
+  #   :added    => old_stat will be nil and new_stat will exist
+  #   :removed  => old_stat will exist and new_stat will be nil
+  #   :modified => old_stat != new_stat
+  #   :stable   => old_stat == new_stat and
+  #
+  def self.from_stats( old_stat, new_stat )
+    if old_stat != new_stat then
+      return DirectoryWatcher::Event.new( :removed,  new_stat.path           ) if new_stat.removed?
+      return DirectoryWatcher::Event.new( :added,    new_stat.path, new_stat ) if old_stat.nil?
+      return DirectoryWatcher::Event.new( :modified, new_stat.path, new_stat )
+    else
+      return DirectoryWatcher::Event.new( :stable, new_stat.path, new_stat   )
+    end
+  end
+
+  # Create a new Event with one of the 4 types and the path of the file.
+  #
+  def initialize( type, path, stat = nil )
+    @type = type
+    @path = path
+    @stat = stat
+  end
+
+  # Is the event a modified event.
+  #
+  def modified?
+    type == :modified
+  end
+
+  # Is the event an added event.
+  #
+  def added?
+    type == :added
+  end
+
+  # Is the event a removed event.
+  #
+  def removed?
+    type == :removed
+  end
+
+  # Is the event a stable event.
+  #
+  def stable?
+    type == :stable
+  end
+
+  # Convert the Event to a nice string format
+  #
+  def to_s( )
+    "<#{self.class} type: #{type} path: '#{path}'>"
+  end
+end

data/lib/directory_watcher/eventable_scanner.rb

@@ -0,0 +1,242 @@
+# An Eventable Scanner is one that can be utilized by something that has an
+# Event Loop. It is intended to be subclassed by classes that implement the
+# specific event loop semantics for say EventMachine or Cool.io.
+#
+# The Events that the EventableScanner is programmed for are:
+#
+# on_scan     - this should be called every +interval+ times
+# on_modified - If the event loop can monitor individual files then this should
+#               be called when the file is modified
+# on_removed  - Similar to on_modified but called when a file is removed.
+#
+# Sub classes are required to implement the following:
+#
+#   start_loop_with_attached_scan_timer() - Instance Method
+#     This method is to start up the loop, if necessary assign to @loop_thread
+#     instance variable the Thread that is controlling the event loop.
+#
+#     This method must also assign an object to @timer which is what does the
+#     periodic scanning of the globs. This object must respond to +detach()+ so
+#     that it may be detached from the event loop.
+#
+#   stop_loop() - Instance Method
+#     This method must shut down the event loop, or detach these classes from
+#     the event loop if we just attached to an existing event loop.
+#
+#   Watcher - An Embedded class
+#     This is a class that must have a class method +watcher(path,scanner)+
+#     which is used to instantiate a file watcher. The Watcher instance must
+#     respond to +detach()+ so that it may be independently detached from the
+#     event loop.
+#
+class DirectoryWatcher::EventableScanner
+  include DirectoryWatcher::Logable
+
+  # A Hash of Watcher objects.
+  attr_reader :watchers
+
+  # call-seq:
+  #    EventableScanner.new( config )
+  #
+  # config - the Configuration instances
+  #
+  def initialize( config )
+    @config = config
+    @scan_and_queue = DirectoryWatcher::ScanAndQueue.new(config.glob, config.collection_queue)
+    @watchers = {}
+    @stopping = false
+    @timer = nil
+    @loop_thread = nil
+    @paused = false
+  end
+
+  # The queue on which to put FileStat and Scan items.
+  #
+  def collection_queue
+    @config.collection_queue
+  end
+
+  # The interval at which to scan
+  #
+  def interval
+    @config.interval
+  end
+
+  # Returns +true+ if the scanner is currently running. Returns +false+ if
+  # this is not the case.
+  #
+  def running?
+    return !@stopping if @timer
+    return false
+  end
+
+  # Start up the scanner. If the scanner is already running, nothing happens.
+  #
+  def start
+    return if running?
+    logger.debug "starting scanner"
+    start_loop_with_attached_scan_timer
+  end
+
+  # Stop the scanner. If the scanner is not running, nothing happens.
+  #
+  def stop
+    return unless running?
+    logger.debug "stoping scanner"
+    @stopping = true
+    teardown_timer_and_watches
+    @stopping = false
+    stop_loop
+  end
+
+  # Pause the scanner.
+  #
+  # Pausing the scanner does not stop the scanning per se, it stops items from
+  # being sent to the collection queue
+  #
+  def pause
+    logger.debug "pausing scanner"
+    @paused = true
+  end
+
+  # Resume the scanner.
+  #
+  # This removes the blockage on sending items to the collection queue.
+  #
+  def resume
+    logger.debug "resuming scanner"
+    @paused = false
+  end
+
+  # Is the Scanner currently paused.
+  #
+  def paused?
+    @paused
+  end
+
+  # EventableScanners do not join
+  #
+  def join( limit = nil )
+  end
+
+  # Do a single scan and send those items to the collection queue.
+  #
+  def run
+    logger.debug "running scan and queue"
+    @scan_and_queue.scan_and_queue
+  end
+
+  # Setting maximum iterations means hooking into the periodic timer event and
+  # counting the number of times it is going on. This also resets the current
+  # iterations count
+  #
+  def maximum_iterations=(value)
+    unless value.nil?
+      value = Integer(value)
+      raise ArgumentError, "maximum iterations must be >= 1" unless value >= 1
+    end
+    @iterations = 0
+    @maximum_iterations = value
+  end
+  attr_reader :maximum_iterations
+  attr_reader :iterations
+
+  # Have we completed up to the maximum_iterations?
+  #
+  def finished_iterations?
+    self.iterations >= self.maximum_iterations
+  end
+
+  # This callback is invoked by the Timer instance when it is triggered by
+  # the Loop. This method will check for added files and stable files
+  # and notify the directory watcher accordingly.
+  #
+  def on_scan
+    logger.debug "on_scan called"
+    scan_and_watch_files
+    progress_towards_maximum_iterations
+  end
+
+  # This callback is invoked by the Watcher instance when it is triggered by the
+  # loop for file modifications.
+  #
+  def on_modified(watcher, new_stat)
+    logger.debug "on_modified called"
+    queue_item(new_stat)
+  end
+
+  # This callback is invoked by the Watcher instance when it is triggered by the
+  # loop for file removals
+  #
+  def on_removed(watcher, new_stat)
+    logger.debug "on_removed called"
+    unwatch_file(watcher.path)
+    queue_item(new_stat)
+  end
+
+  #######
+  private
+  #######
+
+  # Send the given item to the collection queue
+  #
+  def queue_item( item )
+    if paused? then
+      logger.debug "Not queueing item, we're paused"
+    else
+      logger.debug "enqueuing #{item} to #{collection_queue}"
+      collection_queue.enq item
+    end
+  end
+
+
+  # Run a single scan and turn on watches for all the files found in that scan
+  # that do not already have watchers on them.
+  #
+  def scan_and_watch_files
+    logger.debug "scanning and watching files"
+    scan = @scan_and_queue.scan_and_queue
+    scan.results.each do |stat|
+      watch_file(stat.path)
+    end
+  end
+
+  # Remove the timer and the watches from the event loop
+  #
+  def teardown_timer_and_watches
+    @timer.detach rescue nil
+    @timer = nil
+
+    @watchers.each_value {|w| w.detach}
+    @watchers.clear
+  end
+
+  # Create and return a new Watcher instance for the given filename _fn_.
+  # A watcher will only be created once for a particular fn.
+  #
+  def watch_file( fn )
+    unless @watchers[fn] then
+      logger.debug "Watching file #{fn}"
+      w = self.class::Watcher.watch(fn, self)
+      @watchers[fn] = w
+    end
+  end
+
+  # Remove the watcher instance from our tracking
+  #
+  def unwatch_file( fn )
+    logger.debug "Unwatching file #{fn}"
+    @watchers.delete(fn)
+  end
+
+  # Make progress towards maximum iterations. And if we get there, then stop
+  # monitoring files.
+  #
+  def progress_towards_maximum_iterations
+    if maximum_iterations then
+      @iterations += 1
+      stop if finished_iterations?
+    end
+  end
+  # :startdoc:
+end  # class DirectoryWatcher::Eventablecanner

data/lib/directory_watcher/file_stat.rb

@@ -0,0 +1,65 @@
+# FileStat contains file system information about a single file including:
+#
+# path  - The fully expanded path of the file
+# mtime - The last modified time of the file, as a Time object
+# size  - The size of the file, in bytes.
+#
+# The FileStat object can also say if the file is removed of not.
+#
+class DirectoryWatcher::FileStat
+
+  # The fully expanded path of the file
+  attr_reader :path
+
+  # The last modified time of the file
+  attr_accessor :mtime
+
+  # The size of the file in bytes
+  attr_accessor :size
+
+  # Create an instance of FileStat that will make sure that the instance method
+  # +removed?+ returns true when called on it.
+  #
+  def self.for_removed_path( path )
+    ::DirectoryWatcher::FileStat.new(path, nil, nil)
+  end
+
+  # Create a new instance of FileStat with the given path, mtime and size
+  #
+  def initialize( path, mtime, size )
+    @path = path
+    @mtime = mtime
+    @size = size
+  end
+
+  # Is the file represented by this FileStat to be considered removed?
+  #
+  # FileStat doesn't actually go to the file system and check, it assumes if the
+  # FileStat was initialized with a nil mtime or a nil size then that data
+  # wasn't available, and therefore must indicate that the file is no longer in
+  # existence.
+  #
+  def removed?
+    @mtime.nil? || @size.nil?
+  end
+
+  # Compare this FileStat to another object.
+  #
+  # This will only return true when all of the following are true:
+  #
+  # 1) The other object is also a FileStat object
+  # 2) The other object's mtime is equal to this mtime
+  # 3) The other object's msize is equal to this size
+  #
+  def eql?( other )
+    return false unless other.instance_of? self.class
+    self.mtime == other.mtime and self.size == other.size
+  end
+  alias :== :eql?
+
+  # Create a nice string based representation of this instance.
+  #
+  def to_s
+    "<#{self.class.name} path: #{path} mtime: #{mtime} size: #{size}>"
+  end
+end

data/lib/directory_watcher/logable.rb

@@ -0,0 +1,26 @@
+class DirectoryWatcher
+
+  # This is the implementation of a logger that does nothing.
+  # It has all the debug, info, warn, error, fatal methods, but they do nothing
+  class NullLogger
+    def debug( msg ); end
+    def info( msg );  end
+    def warn( msg );  end
+    def error( msg ); end
+    def fatal( msg ); end
+  end
+
+  module Logable
+    def logger
+      @config.logger
+    end
+
+    def self.default_logger
+      require 'logging'
+      Logging::Logger[DirectoryWatcher]
+    rescue LoadError
+      NullLogger.new
+    end
+  end
+
+end

data/lib/directory_watcher/notifier.rb

@@ -0,0 +1,49 @@
+# A Notifier pull Event instances from the give queue and sends them to all of
+# the Observers it knows about.
+#
+class DirectoryWatcher::Notifier
+  include DirectoryWatcher::Threaded
+  include DirectoryWatcher::Logable
+
+  # Create a new Notifier that pulls events off the given notification_queue from the
+  # config, and sends them to the listed observers.
+  #
+  def initialize( config, observers )
+    @config = config
+    @observers = observers
+    self.interval = 0.01 # yes this is a fast loop
+  end
+
+  # Notify all the observers of all the available events in the queue.
+  # If there are 2 or more events in a row that are the same, then they are
+  # collapsed into a single event.
+  #
+  def run
+    previous_event = nil
+    until queue.empty? do
+      event = queue.deq
+      next if previous_event == event
+      @observers.each do |observer, func|
+        send_event_to_observer( observer, func, event )
+      end
+      previous_event = event
+    end
+  end
+
+  #######
+  private
+  #######
+
+  def queue
+    @config.notification_queue
+  end
+
+  # Send the given event to the given observer using the given function.
+  #
+  # Capture any exceptions that have, swallow them and send them to stderr.
+  def send_event_to_observer( observer, func, event )
+    observer.send(func, event)
+  rescue Exception => e
+    $stderr.puts "Called #{observer}##{func}(#{event}) and all I got was this lousy exception #{e}"
+  end
+end