listen 0.5.3 → 3.7.1

data/lib/listen/adapter.rb

@@ -1,211 +1,42 @@
-require 'rbconfig'
-require 'thread'
-require 'set'
-require 'fileutils'
+# frozen_string_literal: true
 
-module Listen
-  class Adapter
-    attr_accessor :directories, :latency, :paused
-
-    # The default delay between checking for changes.
-    DEFAULT_LATENCY = 0.25
-
-    # The default warning message when there is a missing dependency.
-    MISSING_DEPENDENCY_MESSAGE = <<-EOS.gsub(/^\s*/, '')
-      For a better performance, it's recommended that you satisfy the missing dependency.
-    EOS
-
-    # The default warning message when falling back to polling adapter.
-    POLLING_FALLBACK_MESSAGE = <<-EOS.gsub(/^\s*/, '')
-      Listen will be polling changes. Learn more at https://github.com/guard/listen#polling-fallback.
-    EOS
-
-    # Selects the appropriate adapter implementation for the
-    # current OS and initializes it.
-    #
-    # @param [String, Array<String>] directories the directories to watch
-    # @param [Hash] options the adapter options
-    # @option options [Boolean] force_polling to force polling or not
-    # @option options [String, Boolean] polling_fallback_message to change polling fallback message or remove it
-    # @option options [Float] latency the delay between checking for changes in seconds
-    #
-    # @yield [changed_dirs, options] callback Callback called when a change happens
-    # @yieldparam [Array<String>] changed_dirs the changed directories
-    # @yieldparam [Hash] options callback options (like :recursive => true)
-    #
-    # @return [Listen::Adapter] the chosen adapter
-    #
-    def self.select_and_initialize(directories, options = {}, &callback)
-      return Adapters::Polling.new(directories, options, &callback) if options.delete(:force_polling)
-
-      warning = ''
-
-      begin
-        if Adapters::Darwin.usable_and_works?(directories, options)
-          return Adapters::Darwin.new(directories, options, &callback)
-        elsif Adapters::Linux.usable_and_works?(directories, options)
-          return Adapters::Linux.new(directories, options, &callback)
-        elsif Adapters::Windows.usable_and_works?(directories, options)
-          return Adapters::Windows.new(directories, options, &callback)
-        end
-      rescue DependencyManager::Error => e
-        warning += e.message + "\n" + MISSING_DEPENDENCY_MESSAGE
-      end
-
-      unless options[:polling_fallback_message] == false
-        warning += options[:polling_fallback_message] || POLLING_FALLBACK_MESSAGE
-        Kernel.warn "[Listen warning]:\n" + warning.gsub(/^(.*)/, '  \1')
-      end
-
-      Adapters::Polling.new(directories, options, &callback)
-    end
-
-    # Initializes the adapter.
-    #
-    # @param [String, Array<String>] directories the directories to watch
-    # @param [Hash] options the adapter options
-    # @option options [Float] latency the delay between checking for changes in seconds
-    # @option options [Boolean] report_changes whether or not to automatically report changes (run the callback)
-    #
-    # @yield [changed_dirs, options] callback Callback called when a change happens
-    # @yieldparam [Array<String>] changed_dirs the changed directories
-    # @yieldparam [Hash] options callback options (like :recursive => true)
-    #
-    # @return [Listen::Adapter] the adapter
-    #
-    def initialize(directories, options = {}, &callback)
-      @directories  = Array(directories)
-      @callback     = callback
-      @paused       = false
-      @mutex        = Mutex.new
-      @changed_dirs = Set.new
-      @turnstile    = Turnstile.new
-      @latency    ||= DEFAULT_LATENCY
-      @latency      = options[:latency] if options[:latency]
-      @report_changes = options[:report_changes].nil? ? true : options[:report_changes]
-    end
-
-    # Starts the adapter.
-    #
-    # @param [Boolean] blocking whether or not to block the current thread after starting
-    #
-    def start(blocking = true)
-      @stop = false
-    end
-
-    # Stops the adapter.
-    #
-    def stop
-      @stop = true
-      @turnstile.signal # ensure no thread is blocked
-    end
-
-    # Returns whether the adapter is statred or not
-    #
-    # @return [Boolean] whether the adapter is started or not
-    #
-    def started?
-      @stop.nil? ? false : !@stop
-    end
+require 'listen/adapter/base'
+require 'listen/adapter/bsd'
+require 'listen/adapter/darwin'
+require 'listen/adapter/linux'
+require 'listen/adapter/polling'
+require 'listen/adapter/windows'
 
-    # Blocks the main thread until the poll thread
-    # runs the callback.
-    #
-    def wait_for_callback
-      @turnstile.wait unless @paused
-    end
-
-    # Blocks the main thread until N changes are
-    # detected.
-    #
-    def wait_for_changes(goal = 0)
-      changes = 0
-
-      loop do
-        @mutex.synchronize { changes = @changed_dirs.size }
-
-        return if @paused || @stop
-        return if changes >= goal
-
-        sleep(@latency)
+module Listen
+  module Adapter
+    OPTIMIZED_ADAPTERS = [Darwin, Linux, BSD, Windows].freeze
+    POLLING_FALLBACK_MESSAGE = 'Listen will be polling for changes.'\
+      'Learn more at https://github.com/guard/listen#listen-adapters.'
+
+    class << self
+      def select(options = {})
+        Listen.logger.debug 'Adapter: considering polling ...'
+        return Polling if options[:force_polling]
+        Listen.logger.debug 'Adapter: considering optimized backend...'
+        return _usable_adapter_class if _usable_adapter_class
+        Listen.logger.debug 'Adapter: falling back to polling...'
+        _warn_polling_fallback(options)
+        Polling
+      rescue
+        Listen.logger.warn format('Adapter: failed: %s:%s', $ERROR_POSITION.inspect,
+                                  $ERROR_POSITION * "\n")
+        raise
       end
-    end
 
-    # Checks if the adapter is usable on the current OS.
-    #
-    # @return [Boolean] whether usable or not
-    #
-    def self.usable?
-      load_depenencies
-      dependencies_loaded?
-    end
-
-    # Checks if the adapter is usable and works on the current OS.
-    #
-    # @param [String, Array<String>] directories the directories to watch
-    # @param [Hash] options the adapter options
-    # @option options [Float] latency the delay between checking for changes in seconds
-    #
-    # @return [Boolean] whether usable and work or not
-    #
-    def self.usable_and_works?(directories, options = {})
-      usable? && Array(directories).all? { |d| works?(d, options) }
-    end
+      private
 
-    # Runs a tests to determine if the adapter can actually pick up
-    # changes in a given directory and returns the result.
-    #
-    # @note This test takes some time depending the adapter latency.
-    #
-    # @param [String, Pathname] directory the directory to watch
-    # @param [Hash] options the adapter options
-    # @option options [Float] latency the delay between checking for changes in seconds
-    #
-    # @return [Boolean] whether the adapter works or not
-    #
-    def self.works?(directory, options = {})
-      work = false
-      test_file = "#{directory}/.listen_test"
-      callback = lambda { |*| work = true }
-      adapter  = self.new(directory, options, &callback)
-      adapter.start(false)
-
-      FileUtils.touch(test_file)
-
-      t = Thread.new { sleep(adapter.latency * 5); adapter.stop }
-
-      adapter.wait_for_callback
-      work
-    ensure
-      Thread.kill(t) if t
-      FileUtils.rm(test_file) if File.exists?(test_file)
-      adapter.stop if adapter && adapter.started?
-    end
-
-    # Runs the callback and passes it the changes if there are any.
-    #
-    def report_changes
-      changed_dirs = nil
-
-      @mutex.synchronize do
-        return if @changed_dirs.empty?
-        changed_dirs = @changed_dirs.to_a
-        @changed_dirs.clear
+      def _usable_adapter_class
+        OPTIMIZED_ADAPTERS.find(&:usable?)
       end
 
-      @callback.call(changed_dirs, {})
-      @turnstile.signal
-    end
-
-    private
-
-    # Polls changed directories and reports them back
-    # when there are changes.
-    #
-    def poll_changed_dirs
-      until @stop
-        sleep(@latency)
-        report_changes
+      def _warn_polling_fallback(options)
+        msg = options.fetch(:polling_fallback_message, POLLING_FALLBACK_MESSAGE)
+        Kernel.warn "[Listen warning]:\n  #{msg}" if msg
       end
     end
   end

data/lib/listen/backend.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'listen/adapter'
+require 'listen/adapter/base'
+require 'listen/adapter/config'
+
+require 'forwardable'
+
+# This class just aggregates configuration object to avoid Listener specs
+# from exploding with huge test setup blocks
+module Listen
+  class Backend
+    extend Forwardable
+
+    def initialize(directories, queue, silencer, config)
+      adapter_select_opts = config.adapter_select_options
+
+      adapter_class = Adapter.select(adapter_select_opts)
+
+      # Use default from adapter if possible
+      @min_delay_between_events = config.min_delay_between_events
+      @min_delay_between_events ||= adapter_class::DEFAULTS[:wait_for_delay]
+      @min_delay_between_events ||= 0.1
+
+      adapter_opts = config.adapter_instance_options(adapter_class)
+
+      aconfig = Adapter::Config.new(directories, queue, silencer, adapter_opts)
+      @adapter = adapter_class.new(aconfig)
+    end
+
+    delegate start: :adapter
+    delegate stop: :adapter
+
+    attr_reader :min_delay_between_events
+
+    private
+
+    attr_reader :adapter
+  end
+end

data/lib/listen/change.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'listen/file'
+require 'listen/directory'
+
+module Listen
+  # TODO: rename to Snapshot
+  class Change
+    # TODO: test this class for coverage
+    class Config
+      def initialize(queue, silencer)
+        @queue = queue
+        @silencer = silencer
+      end
+
+      def silenced?(path, type)
+        @silencer.silenced?(Pathname(path), type)
+      end
+
+      def queue(*args)
+        @queue << args
+      end
+    end
+
+    attr_reader :record
+
+    def initialize(config, record)
+      @config = config
+      @record = record
+    end
+
+    # Invalidate some part of the snapshot/record (dir, file, subtree, etc.)
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    def invalidate(type, rel_path, options)
+      watched_dir = Pathname.new(record.root)
+
+      change = options[:change]
+      cookie = options[:cookie]
+
+      if !cookie && @config.silenced?(rel_path, type)
+        Listen.logger.debug { "(silenced): #{rel_path.inspect}" }
+        return
+      end
+
+      path = watched_dir + rel_path
+
+      Listen.logger.debug do
+        log_details = options[:silence] && 'recording' || change || 'unknown'
+        "#{log_details}: #{type}:#{path} (#{options.inspect})"
+      end
+
+      if change
+        options = cookie ? { cookie: cookie } : {}
+        @config.queue(type, change, watched_dir, rel_path, options)
+      elsif type == :dir
+        # NOTE: POSSIBLE RECURSION
+        # TODO: fix - use a queue instead
+        Directory.scan(self, rel_path, options)
+      elsif (change = File.change(record, rel_path)) && !options[:silence]
+        @config.queue(:file, change, watched_dir, rel_path)
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
+  end
+end

data/lib/listen/cli.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'listen'
+require 'logger'
+
+module Listen
+  class CLI < Thor
+    default_task :start
+
+    desc 'start', 'Starts Listen'
+
+    class_option :verbose,
+                 type:    :boolean,
+                 default: false,
+                 aliases: '-v',
+                 banner:  'Verbose'
+
+    class_option :directory,
+                 type:    :array,
+                 default: '.',
+                 aliases: '-d',
+                 banner:  'The directory to listen to'
+
+    class_option :relative,
+                 type:    :boolean,
+                 default: false,
+                 aliases: '-r',
+                 banner:  'Convert paths relative to current directory'
+
+    def start
+      Listen::Forwarder.new(options).start
+    end
+  end
+
+  class Forwarder
+    attr_reader :logger
+
+    def initialize(options)
+      @options = options
+      @logger = ::Logger.new(STDOUT, level: ::Logger::INFO)
+      @logger.formatter = proc { |_, _, _, msg| "#{msg}\n" }
+    end
+
+    def start
+      logger.info 'Starting listen...'
+
+      directory = @options[:directory]
+      relative = @options[:relative]
+      callback = proc do |modified, added, removed|
+        if @options[:verbose]
+          logger.info "+ #{added}" unless added.empty?
+          logger.info "- #{removed}" unless removed.empty?
+          logger.info "> #{modified}" unless modified.empty?
+        end
+      end
+
+      listener = Listen.to(directory, relative: relative, &callback)
+
+      listener.start
+
+      sleep 0.5 while listener.processing?
+    end
+  end
+end

data/lib/listen/directory.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Listen
+  # TODO: refactor (turn it into a normal object, cache the stat, etc)
+  class Directory
+    # rubocop:disable Metrics/MethodLength
+    def self.scan(snapshot, rel_path, options)
+      record = snapshot.record
+      dir = Pathname.new(record.root)
+      previous = record.dir_entries(rel_path)
+
+      record.add_dir(rel_path)
+
+      # TODO: use children(with_directory: false)
+      path = dir + rel_path
+      current = Set.new(_children(path))
+
+      Listen.logger.debug do
+        format('%s: %s(%s): %s -> %s',
+               (options[:silence] ? 'Recording' : 'Scanning'),
+               rel_path, options.inspect, previous.inspect, current.inspect)
+      end
+
+      begin
+        current.each do |full_path|
+          type = ::File.lstat(full_path.to_s).directory? ? :dir : :file
+          item_rel_path = full_path.relative_path_from(dir).to_s
+          _change(snapshot, type, item_rel_path, options)
+        end
+      rescue Errno::ENOENT
+        # The directory changed meanwhile, so rescan it
+        current = Set.new(_children(path))
+        retry
+      end
+
+      # TODO: this is not tested properly
+      previous = previous.reject { |entry, _| current.include?(path + entry) }
+
+      _async_changes(snapshot, Pathname.new(rel_path), previous, options)
+    rescue Errno::ENOENT, Errno::EHOSTDOWN
+      record.unset_path(rel_path)
+      _async_changes(snapshot, Pathname.new(rel_path), previous, options)
+    rescue Errno::ENOTDIR
+      # TODO: path not tested
+      record.unset_path(rel_path)
+      _async_changes(snapshot, path, previous, options)
+      _change(snapshot, :file, rel_path, options)
+    rescue
+      Listen.logger.warn { format('scan DIED: %s:%s', $ERROR_INFO, $ERROR_POSITION * "\n") }
+      raise
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def self.ascendant_of?(base, other)
+      other.ascend do |ascendant|
+        break true if base == ascendant
+      end
+    end
+
+    def self._async_changes(snapshot, path, previous, options)
+      fail "Not a Pathname: #{path.inspect}" unless path.respond_to?(:children)
+      previous.each do |entry, data|
+        # TODO: this is a hack with insufficient testing
+        type = data.key?(:mtime) ? :file : :dir
+        rel_path_s = (path + entry).to_s
+        _change(snapshot, type, rel_path_s, options)
+      end
+    end
+
+    def self._change(snapshot, type, path, options)
+      return snapshot.invalidate(type, path, options) if type == :dir
+
+      # Minor param cleanup for tests
+      # TODO: use a dedicated Event class
+      opts = options.dup
+      opts.delete(:recursive)
+      snapshot.invalidate(type, path, opts)
+    end
+
+    def self._children(path)
+      return path.children unless RUBY_ENGINE == 'jruby'
+
+      # JRuby inconsistency workaround, see:
+      # https://github.com/jruby/jruby/issues/3840
+      exists = path.exist?
+      directory = path.directory?
+      exists && !directory and raise Errno::ENOTDIR, path.to_s
+      path.children
+    end
+  end
+end

data/lib/listen/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Besides programming error exceptions like ArgumentError,
+# all public interface exceptions should be declared here and inherit from Listen::Error.
+module Listen
+  class Error < RuntimeError
+    class NotStarted < Error; end
+    class SymlinkLoop < Error; end
+    class INotifyMaxWatchesExceeded < Error; end
+  end
+end

data/lib/listen/event/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Listen
+  module Event
+    class Config
+      attr_reader :listener, :event_queue, :min_delay_between_events
+
+      def initialize(
+        listener,
+        event_queue,
+        queue_optimizer,
+        wait_for_delay,
+        &block
+      )
+
+        @listener = listener
+        @event_queue = event_queue
+        @queue_optimizer = queue_optimizer
+        @min_delay_between_events = wait_for_delay
+        @block = block
+      end
+
+      def sleep(seconds)
+        Kernel.sleep(seconds)
+      end
+
+      def call(*args)
+        @block&.call(*args)
+      end
+
+      def callable?
+        @block
+      end
+
+      def optimize_changes(changes)
+        @queue_optimizer.smoosh_changes(changes)
+      end
+    end
+  end
+end

data/lib/listen/event/loop.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'thread'
+
+require 'timeout'
+require 'listen/event/processor'
+require 'listen/thread'
+require 'listen/error'
+
+module Listen
+  module Event
+    class Loop
+      include Listen::FSM
+
+      Error = ::Listen::Error
+      NotStarted = ::Listen::Error::NotStarted # for backward compatibility
+
+      start_state :pre_start
+      state :pre_start
+      state :starting
+      state :started
+      state :stopped
+
+      def initialize(config)
+        @config = config
+        @wait_thread = nil
+        @reasons = ::Queue.new
+        initialize_fsm
+      end
+
+      def wakeup_on_event
+        if started? && @wait_thread&.alive?
+          _wakeup(:event)
+        end
+      end
+
+      def started?
+        state == :started
+      end
+
+      MAX_STARTUP_SECONDS = 5.0
+
+      # @raises Error::NotStarted if background thread hasn't started in MAX_STARTUP_SECONDS
+      def start
+        # TODO: use a Fiber instead?
+        return unless state == :pre_start
+
+        transition! :starting
+
+        @wait_thread = Listen::Thread.new("wait_thread") do
+          _process_changes
+        end
+
+        Listen.logger.debug("Waiting for processing to start...")
+
+        wait_for_state(:started, timeout: MAX_STARTUP_SECONDS) or
+          raise Error::NotStarted, "thread didn't start in #{MAX_STARTUP_SECONDS} seconds (in state: #{state.inspect})"
+
+        Listen.logger.debug('Processing started.')
+      end
+
+      def pause
+        # TODO: works?
+        # fail NotImplementedError
+      end
+
+      def stop
+        transition! :stopped
+
+        @wait_thread&.join
+        @wait_thread = nil
+      end
+
+      def stopped?
+        state == :stopped
+      end
+
+      private
+
+      def _process_changes
+        processor = Event::Processor.new(@config, @reasons)
+
+        transition! :started
+
+        processor.loop_for(@config.min_delay_between_events)
+      end
+
+      def _wakeup(reason)
+        @reasons << reason
+        @wait_thread.wakeup
+      end
+    end
+  end
+end