listen 0.7.3 → 1.0.0

data/lib/listen.rb

@@ -1,24 +1,21 @@
-module Listen
+require 'listen/turnstile'
+require 'listen/listener'
+require 'listen/multi_listener'
+require 'listen/directory_record'
+require 'listen/adapter'
 
-  autoload :Turnstile,         'listen/turnstile'
-  autoload :Listener,          'listen/listener'
-  autoload :MultiListener,     'listen/multi_listener'
-  autoload :DirectoryRecord,   'listen/directory_record'
-  autoload :DependencyManager, 'listen/dependency_manager'
-  autoload :Adapter,           'listen/adapter'
+module Listen
 
   module Adapters
-    autoload :Darwin,  'listen/adapters/darwin'
-    autoload :Linux,   'listen/adapters/linux'
-    autoload :BSD,     'listen/adapters/bsd'
-    autoload :Windows, 'listen/adapters/windows'
-    autoload :Polling, 'listen/adapters/polling'
+    Adapter::ADAPTERS.each do |adapter|
+      require "listen/adapters/#{adapter.downcase}"
+    end
   end
 
-  # Listens to filesystem modifications on a either single directory or multiple directories.
+  # Listens to file system modifications on a either single directory or multiple directories.
+  # When calling this method, the current thread is not blocked.
   #
   # @param (see Listen::Listener#new)
-  # @param (see Listen::MultiListener#new)
   #
   # @yield [modified, added, removed] the changed files
   # @yieldparam [Array<String>] modified the list of modified files
@@ -28,13 +25,31 @@ module Listen
   # @return [Listen::Listener] the file listener if no block given
   #
   def self.to(*args, &block)
-    listener = if args.length == 1 || ! args[1].is_a?(String)
-      Listener.new(*args, &block)
-    else
-      MultiListener.new(*args, &block)
-    end
+    listener = _init_listener(*args, &block)
 
     block ? listener.start : listener
   end
 
+  # Listens to file system modifications on a either single directory or multiple directories.
+  # When calling this method, the current thread is blocked.
+  #
+  # @param (see Listen::Listener#new)
+  #
+  # @yield [modified, added, removed] the changed files
+  # @yieldparam [Array<String>] modified the list of modified files
+  # @yieldparam [Array<String>] added the list of added files
+  # @yieldparam [Array<String>] removed the list of removed files
+  #
+  # @since 1.0.0
+  #
+  def self.to!(*args, &block)
+    _init_listener(*args, &block).start!
+  end
+
+  # @private
+  #
+  def self._init_listener(*args, &block)
+    Listener.new(*args, &block)
+  end
+
 end

data/lib/listen/adapter.rb

@@ -5,19 +5,25 @@ require 'fileutils'
 
 module Listen
   class Adapter
-    attr_accessor :directories, :latency, :paused
+    attr_accessor :directories, :callback, :stopped, :paused,
+                  :mutex, :changed_directories, :turnstile, :latency,
+                  :worker, :worker_thread, :poller_thread
+
+    # The list of existing optimized adapters.
+    OPTIMIZED_ADAPTERS = %w[Darwin Linux BSD Windows]
+
+    # The list of existing fallback adapters.
+    FALLBACK_ADAPTERS = %w[Polling]
+
+    # The list of all existing adapters.
+    ADAPTERS = OPTIMIZED_ADAPTERS + FALLBACK_ADAPTERS
 
     # 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.
+      Listen will be polling for changes. Learn more at https://github.com/guard/listen#polling-fallback.
     EOS
 
     # Selects the appropriate adapter implementation for the
@@ -29,36 +35,23 @@ module Listen
     # @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)
+    # @yield [changed_directories, options] callback the callback called when a change happens
+    # @yieldparam [Array<String>] changed_directories 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::BSD.usable_and_works?(directories, options)
-          return Adapters::BSD.new(directories, options, &callback)
-        elsif Adapters::Windows.usable_and_works?(directories, options)
-          return Adapters::Windows.new(directories, options, &callback)
+      OPTIMIZED_ADAPTERS.each do |adapter|
+        namespaced_adapter = Adapters.const_get(adapter)
+        if namespaced_adapter.send(:usable_and_works?, directories, options)
+          return namespaced_adapter.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
 
+      self.warn_polling_fallback(options)
       Adapters::Polling.new(directories, options, &callback)
     end
 
@@ -67,97 +60,145 @@ module Listen
     # @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)
+    # @yield [changed_directories, options] callback Callback called when a change happens
+    # @yieldparam [Array<String>] changed_directories 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]
+      @directories         = Array(directories)
+      @callback            = callback
+      @stopped             = true
+      @paused              = false
+      @mutex               = Mutex.new
+      @changed_directories = Set.new
+      @turnstile           = Turnstile.new
+      @latency             = options.fetch(:latency, default_latency)
+      @worker              = initialize_worker
     end
 
-    # Starts the adapter.
+    # Starts the adapter and don't block the current thread.
     #
     # @param [Boolean] blocking whether or not to block the current thread after starting
     #
-    def start(blocking = true)
-      @stop = false
+    def start
+      mutex.synchronize do
+        return unless stopped
+        @stopped = false
+      end
+
+      start_worker
+      start_poller
+    end
+
+    # Starts the adapter and block the current thread.
+    #
+    # @since 1.0.0
+    #
+    def start!
+      start
+      blocking_thread.join
     end
 
     # Stops the adapter.
     #
     def stop
-      @stop = true
-      @turnstile.signal # ensure no thread is blocked
+      mutex.synchronize do
+        return if stopped
+        @stopped = true
+        turnstile.signal # ensure no thread is blocked
+      end
+
+      worker.stop if worker
+      Thread.kill(worker_thread) if worker_thread
+      poller_thread.join if poller_thread
+    end
+
+    # Pauses the adapter.
+    #
+    def pause
+      @paused = true
     end
 
-    # Returns whether the adapter is statred or not
+    # Unpauses the adapter.
+    #
+    def unpause
+      @paused = false
+    end
+
+    # Returns whether the adapter is started or not.
     #
     # @return [Boolean] whether the adapter is started or not
     #
     def started?
-      @stop.nil? ? false : !@stop
+      !stopped
+    end
+
+    # Returns whether the adapter is paused or not.
+    #
+    # @return [Boolean] whether the adapter is paused or not
+    #
+    def paused?
+      paused
     end
 
     # Blocks the main thread until the poll thread
     # runs the callback.
     #
     def wait_for_callback
-      @turnstile.wait unless @paused
+      turnstile.wait unless paused
     end
 
     # Blocks the main thread until N changes are
     # detected.
     #
-    def wait_for_changes(goal = 0)
+    def wait_for_changes(threshold = 0)
       changes = 0
 
       loop do
-        @mutex.synchronize { changes = @changed_dirs.size }
+        mutex.synchronize { changes = changed_directories.size }
 
-        return if @paused || @stop
-        return if changes >= goal
+        return if paused || stopped
+        return if changes >= threshold
 
-        sleep(@latency)
+        sleep(latency)
       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
+    # @return [Boolean] whether the adapter is usable and work or not
     #
     def self.usable_and_works?(directories, options = {})
       usable? && Array(directories).all? { |d| works?(d, options) }
     end
 
+    # Checks if the adapter is usable on target OS.
+    #
+    # @return [Boolean] whether usable or not
+    #
+    def self.usable?
+      load_dependency if RbConfig::CONFIG['target_os'] =~ target_os_regex
+    end
+
+    # Load the adapter gem
+    #
+    # @return [Boolean] whether required or not
+    #
+    def self.load_dependency
+      @loaded ||= require adapter_gem
+    end
+
     # 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.
+    # @note This test takes some time depending on the adapter latency.
     #
     # @param [String, Pathname] directory the directory to watch
     # @param [Hash] options the adapter options
@@ -166,11 +207,11 @@ module Listen
     # @return [Boolean] whether the adapter works or not
     #
     def self.works?(directory, options = {})
-      work = false
+      work      = false
       test_file = "#{directory}/.listen_test"
-      callback = lambda { |*| work = true }
-      adapter  = self.new(directory, options, &callback)
-      adapter.start(false)
+      callback  = lambda { |*| work = true }
+      adapter   = self.new(directory, options, &callback)
+      adapter.start
 
       FileUtils.touch(test_file)
 
@@ -180,7 +221,7 @@ module Listen
       work
     ensure
       Thread.kill(t) if t
-      FileUtils.rm(test_file) if File.exists?(test_file)
+      FileUtils.rm(test_file, :force => true)
       adapter.stop if adapter && adapter.started?
     end
 
@@ -189,24 +230,81 @@ module Listen
     def report_changes
       changed_dirs = nil
 
-      @mutex.synchronize do
-        return if @changed_dirs.empty?
-        changed_dirs = @changed_dirs.to_a
-        @changed_dirs.clear
+      mutex.synchronize do
+        return if @changed_directories.empty?
+        changed_dirs = @changed_directories.to_a
+        @changed_directories.clear
       end
 
-      @callback.call(changed_dirs, {})
-      @turnstile.signal
+      callback.call(changed_dirs, {})
+      turnstile.signal
     end
 
     private
 
-    # Polls changed directories and reports them back
-    # when there are changes.
+    # The default delay between checking for changes.
+    #
+    # @note This method can be overriden on a per-adapter basis.
+    #
+    def default_latency
+      DEFAULT_LATENCY
+    end
+
+    # The thread on which the main thread should wait
+    # when the adapter has been started in blocking mode.
+    #
+    # @note This method can be overriden on a per-adapter basis.
+    #
+    def blocking_thread
+      worker_thread
+    end
+
+    # Initialize the adpater' specific worker.
+    #
+    # @note Each adapter must override this method
+    #   to initialize its own @worker.
+    #
+    def initialize_worker
+      nil
+    end
+
+    # Should start the worker in a new thread.
+    #
+    # @note Each adapter must override this method
+    #   to start its worker on a new @worker_thread thread.
+    #
+    def start_worker
+      raise NotImplementedError, "#{self.class} cannot respond to: #{__method__}"
+    end
+
+    # This method starts a new thread which poll for changes detected by
+    # the adapter and report them back to the user.
+    #
+    def start_poller
+      @poller_thread = Thread.new { poll_changed_directories }
+    end
+
+    # Warn of polling fallback unless the :polling_fallback_message
+    # has been set to false.
+    #
+    # @param [String] warning an existing warning message
+    # @param [Hash] options the adapter options
+    # @option options [Boolean] polling_fallback_message to change polling fallback message or remove it
+    #
+    def self.warn_polling_fallback(options)
+      return if options[:polling_fallback_message] == false
+
+      warning = options[:polling_fallback_message] || POLLING_FALLBACK_MESSAGE
+      Kernel.warn "[Listen warning]:\n#{warning.gsub(/^(.*)/, '  \1')}"
+    end
+
+    # Polls changed directories and reports them back when there are changes.
+    #
+    # @note This method can be overriden on a per-adapter basis.
     #
-    def poll_changed_dirs
-      until @stop
-        sleep(@latency)
+    def poll_changed_directories
+      until stopped
+        sleep(latency)
         report_changes
       end
     end

data/lib/listen/adapters/bsd.rb

@@ -4,68 +4,15 @@ module Listen
     # Listener implementation for BSD's `kqueue`.
     #
     class BSD < Adapter
-      extend DependencyManager
-
-      # Declare the adapter's dependencies
-      dependency 'rb-kqueue', '~> 0.2'
-
       # Watched kqueue events
       #
       # @see http://www.freebsd.org/cgi/man.cgi?query=kqueue
       # @see https://github.com/nex3/rb-kqueue/blob/master/lib/rb-kqueue/queue.rb
       #
-      EVENTS = [ :delete, :write, :extend, :attrib, :link, :rename, :revoke ]
-
-      # Initializes the Adapter. See {Listen::Adapter#initialize} for
-      # more info.
-      #
-      def initialize(directories, options = {}, &callback)
-        super
-        @kqueue = init_kqueue
-      end
-
-      # Starts the adapter.
-      #
-      # @param [Boolean] blocking whether or not to block the current thread after starting
-      #
-      def start(blocking = true)
-        @mutex.synchronize do
-          return if @stop == false
-          super
-        end
-
-        @kqueue_thread = Thread.new do
-          until @stop
-            @kqueue.poll
-            sleep(@latency)
-          end
-        end
-        @poll_thread   = Thread.new { poll_changed_dirs } if @report_changes
-
-        @kqueue_thread.join if blocking
-      end
-
-      # Stops the adapter.
-      #
-      def stop
-        @mutex.synchronize do
-          return if @stop == true
-          super
-        end
-
-        @kqueue.stop
-        Thread.kill(@kqueue_thread) if @kqueue_thread
-        @poll_thread.join if @poll_thread
-      end
+      EVENTS = [:delete, :write, :extend, :attrib, :link, :rename, :revoke]
 
-      # Checks if the adapter is usable on the current OS.
-      #
-      # @return [Boolean] whether usable or not
-      #
-      def self.usable?
-        return false unless RbConfig::CONFIG['target_os'] =~ /freebsd/i
-        super
-      end
+      def self.target_os_regex; /freebsd/i; end
+      def self.adapter_gem; 'rb-kqueue'; end
 
       private
 
@@ -74,24 +21,26 @@ module Listen
       #
       # @return [INotify::Notifier] initialized kqueue
       #
-      def init_kqueue
+      # @see Listen::Adapter#initialize_worker
+      #
+      def initialize_worker
         require 'find'
 
         callback = lambda do |event|
           path = event.watcher.path
-          @mutex.synchronize do
+          mutex.synchronize do
             # kqueue watches everything, but Listen only needs the
             # directory where stuffs happens.
-            @changed_dirs << (File.directory?(path) ? path : File.dirname(path))
+            @changed_directories << (File.directory?(path) ? path : File.dirname(path))
 
             # If it is a directory, and it has a write flag, it means a
             # file has been added so find out which and deal with it.
-            # No need to check for removed file, kqueue will forget them
-            # when the vfs does..
-            if File.directory?(path) && !(event.flags & [:write]).empty?
+            # No need to check for removed files, kqueue will forget them
+            # when the vfs does.
+            if File.directory?(path) && event.flags.include?(:write)
               queue = event.watcher.queue
               Find.find(path) do |file|
-                unless queue.watchers.detect {|k,v| v.path == file.to_s}
+                unless queue.watchers.detect { |k,v| v.path == file.to_s }
                   queue.watch_file(file, *EVENTS, &callback)
                 end
               end
@@ -100,13 +49,27 @@ module Listen
         end
 
         KQueue::Queue.new.tap do |queue|
-          @directories.each do |directory|
+          directories.each do |directory|
             Find.find(directory) do |path|
               queue.watch_file(path, *EVENTS, &callback)
             end
           end
         end
       end
+
+      # Starts the worker in a new thread.
+      #
+      # @see Listen::Adapter#start_worker
+      #
+      def start_worker
+        @worker_thread = Thread.new do
+          until stopped
+            worker.poll
+            sleep(latency)
+          end
+        end
+      end
     end
+
   end
 end