listen 3.2.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9a53907593c7c8390f895d361bce34873381883dbd033e02d1706e2e28c13d1
-  data.tar.gz: 5a8dfdc3c74345e7283b5f5aee13b5ded0f3f44c8fecaf7027551eb2359ecdae
+  metadata.gz: 5b176ea600fdb505fc248ac0f680ca32e16aacb4c158d70bbf2a3a2f179e81cc
+  data.tar.gz: e3d6d42fcb64fd16149ecdfc889ac934977c5ebd3aa0b73f82efd2241a53b73a
 SHA512:
-  metadata.gz: b5cbabed841e265c54aebfff999d306f5a91590e5e5abe8f9867c5ea9e66caa4d952acc7e7b8be10c2f1ea0a77b0ff4a07d653ec45d3009e149b5faa8331a689
-  data.tar.gz: 76c990e22b861cae3d9c764a290fab1ed90f6547b9c1329c92be797b8d99364ae21cb3367a84e8064e6834c9a3b76ab440a8c597f0dcacae1e06b1991e39c303
+  metadata.gz: eda24062fbec2af3e05da6ae80bc91ce6753bb4644d1fd2f2890c961bc85f7291d532d43d570def525b09987e19ff422c3746cb461583d0b597767e39d72ac2e
+  data.tar.gz: 82104ab7d9b6f3d5a743af79d56b9d44d60c0823c06010542049978a90d6f30ccb4145b0ec63bb3341bb823871fbfe2c32f674f19501433a4df79fc56319a430

data/README.md

@@ -1,12 +1,13 @@
-## IMPORTANT: If you cannot install Listen (e.g. on Travis/CI builds), [a workaround is here](https://github.com/guard/listen/wiki/Ruby-version-requirements)
-
-:exclamation: Listen is currently accepting more maintainers. Please [read this](https://github.com/guard/guard/wiki/Maintainers) if you're interested in joining the team.
-
 # Listen
 
-[![Gem Version](https://badge.fury.io/rb/listen.svg)](http://badge.fury.io/rb/listen) [![Build Status](https://travis-ci.org/guard/listen.svg)](https://travis-ci.org/guard/listen) [![Code Climate](https://codeclimate.com/github/guard/listen.svg)](https://codeclimate.com/github/guard/listen) [![Coverage Status](https://coveralls.io/repos/guard/listen/badge.svg?branch=master)](https://coveralls.io/r/guard/listen)
+The `listen` gem listens to file modifications and notifies you about the changes.
+
+:exclamation: `Listen` is currently accepting more maintainers. Please [read this](https://github.com/guard/guard/wiki/Maintainers) if you're interested in joining the team.
 
-The Listen gem listens to file modifications and notifies you about the changes.
+[![Development Status](https://github.com/guard/listen/workflows/Development/badge.svg)](https://github.com/guard/listen/actions?workflow=Development)
+[![Gem Version](https://badge.fury.io/rb/listen.svg)](http://badge.fury.io/rb/listen)
+[![Code Climate](https://codeclimate.com/github/guard/listen.svg)](https://codeclimate.com/github/guard/listen)
+[![Coverage Status](https://coveralls.io/repos/guard/listen/badge.svg?branch=master)](https://coveralls.io/r/guard/listen)
 
 ## Features
 
@@ -15,7 +16,7 @@ The Listen gem listens to file modifications and notifies you about the changes.
 * You can watch multiple directories.
 * Regexp-patterns for ignoring paths for more accuracy and speed
 * Increased change detection accuracy on OS X HFS and VFAT volumes.
-* Tested on selected Ruby environments via [Travis CI](https://travis-ci.org/guard/listen). (See [.travis.yml](https:///github.com/guard/listen/master/.travis.yml) for supported/tested Ruby Versions),
+* Continuous Integration: tested on selected Ruby environments via [Github Workflows](https:///github.com/guard/listen/master/.github/workflows).
 
 ## Issues / limitations
 
@@ -24,37 +25,81 @@ The Listen gem listens to file modifications and notifies you about the changes.
   * Symlinked directories pointing within a watched directory are not supported ([#273](https://github.com/guard/listen/pull/273)- see [Duplicate directory errors](https://github.com/guard/listen/wiki/Duplicate-directory-errors)).
 * No directory/adapter-specific configuration options.
 * Support for plugins planned for future.
-* TCP functionality was removed in Listen [3.0.0](https://github.com/guard/listen/releases/tag/v3.0.0) ([#319](https://github.com/guard/listen/issues/319), [#218](https://github.com/guard/listen/issues/218)). There are plans to extract this feature to separate gems ([#258](https://github.com/guard/listen/issues/258)), until this is finished, you can use by locking the `listen` gem to version `'~> 2.10'`.
+* TCP functionality was removed in `listen` [3.0.0](https://github.com/guard/listen/releases/tag/v3.0.0) ([#319](https://github.com/guard/listen/issues/319), [#218](https://github.com/guard/listen/issues/218)). There are plans to extract this feature to separate gems ([#258](https://github.com/guard/listen/issues/258)), until this is finished, you can use by locking the `listen` gem to version `'~> 2.10'`.
 * Some filesystems won't work without polling (VM/Vagrant Shared folders, NFS, Samba, sshfs, etc.).
 * Specs suite on JRuby and Rubinius aren't reliable on Travis CI, but should work.
 * Windows and \*BSD adapter aren't continuously and automatically tested.
 * OSX adapter has some performance limitations ([#342](https://github.com/guard/listen/issues/342)).
-* Ruby < 2.2.x is no longer supported - upgrade to Ruby 2.2 or 2.3.
+* FreeBSD users need patched version of rb-kqueue (as of 2020/11). See #475 for the issue, mat813/rb-kqueue#12 for the patch, and Bug 250432 in bugzilla.
 * Listeners do not notify across forked processes, if you wish for multiple processes to receive change notifications you must [listen inside of each process](https://github.com/guard/listen/issues/398#issuecomment-223957952).
 
 Pull requests or help is very welcome for these.
 
 ## Install
 
-The simplest way to install Listen is to use [Bundler](http://bundler.io).
+The simplest way to install `listen` is to use [Bundler](http://bundler.io).
+
+```ruby
+gem 'listen', '~> 3.3' # NOTE: for TCP functionality, use '~> 2.10' for now
+```
 
+## Complete Example
+Here is a complete example of using the `listen` gem:
 ```ruby
-gem 'listen', '~> 3.0' # NOTE: for TCP functionality, use '~> 2.10' for now
+require 'listen'
+
+listener = Listen.to('/srv/app') do |modified, added, removed|
+  puts(modified: modified, added: added, removed: removed)
+end
+listener.start
+sleep
+```
+Running the above in the background, you can see the callback block being called in response to each command:
+```
+$ cd /srv/app
+$ touch a.txt
+{:modified=>[], :added=>["/srv/app/a.txt"], :removed=>[]}
+
+$ echo more >> a.txt
+{:modified=>["/srv/app/a.txt"], :added=>[], :removed=>[]}
+
+$ mv a.txt b.txt
+{:modified=>[], :added=>["/srv/app/b.txt"], :removed=>["/srv/app/a.txt"]}
+
+$ vi b.txt
+# add a line to this new file and press ZZ to save and exit
+{:modified=>["/srv/app/b.txt"], :added=>[], :removed=>[]}
+
+$ vi c.txt
+# add a line and press ZZ to save and exit
+{:modified=>[], :added=>["/srv/app/c.txt"], :removed=>[]}
+
+$ rm b.txt c.txt
+{:modified=>[], :added=>[], :removed=>["/srv/app/b.txt", "/srv/app/c.txt"]}
 ```
 
 ## Usage
 
-Call `Listen.to` with either a single directory or multiple directories, then define the "changes" callback in a block.
+Call `Listen.to` with one or more directories and the "changes" callback passed as a block.
 
 ``` ruby
 listener = Listen.to('dir/to/listen', 'dir/to/listen2') do |modified, added, removed|
-  puts "modified absolute path: #{modified}"
-  puts "added absolute path: #{added}"
-  puts "removed absolute path: #{removed}"
+  puts "modified absolute path array: #{modified}"
+  puts "added absolute path array: #{added}"
+  puts "removed absolute path array: #{removed}"
 end
-listener.start # not blocking
+listener.start # starts a listener thread--does not block
+
+# do whatever you want here...just don't exit the process :)
+
 sleep
 ```
+## Changes Callback
+
+Changes to the listened-to directories are reported by the listener thread in a callback.
+The callback receives **three** array parameters: `modified`, `added` and `removed`, in that order.
+Each of these three is always an array with 0 or more entries.
+Each array entry is an absolute path.
 
 ### Pause / unpause / stop
 
@@ -75,13 +120,14 @@ listener.unpause # resumes processing changes ("start" would do the same)
 listener.stop    # stop both listening to changes and processing them
 ```
 
-  Note: While paused, Listen keeps on collecting changes in the background - to clear them, call "stop"
+  Note: While paused, `listen` keeps on collecting changes in the background - to clear them, call `stop`.
 
-  Note: You should keep track of all started listeners and stop them properly on finish.
+  Note: You should keep track of all started listeners and `stop` them properly on finish.
 
 ### Ignore / ignore!
 
-Listen ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer), you can add ignoring patterns with the `ignore` option/method or overwrite default with `ignore!` option/method.
+`Listen` ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer).
+You can add ignoring patterns with the `ignore` option/method or overwrite default with `ignore!` option/method.
 
 ``` ruby
 listener = Listen.to('dir/path/to/listen', ignore: /\.txt/) { |modified, added, removed| # ... }
@@ -93,11 +139,11 @@ sleep
 
 Note: `:ignore` regexp patterns are evaluated against relative paths.
 
-Note: Ignoring paths does not improve performance, except when Polling ([#274](https://github.com/guard/listen/issues/274))
+Note: Ignoring paths does not improve performance, except when Polling ([#274](https://github.com/guard/listen/issues/274)).
 
 ### Only
 
-Listen catches all files (less the ignored ones) by default. If you want to only listen to a specific type of file (i.e., just `.rb` extension), you should use the `only` option/method.
+`Listen` watches all files (less the ignored ones) by default. If you want to only listen to a specific type of file (i.e., just `.rb` extension), you should use the `only` option/method.
 
 ``` ruby
 listener = Listen.to('dir/path/to/listen', only: /\.rb$/) { |modified, added, removed| # ... }
@@ -109,35 +155,6 @@ sleep
 Note: `:only` regexp patterns are evaluated only against relative **file** paths.
 
 
-## Changes callback
-
-Changes to the listened-to directories gets reported back to the user in a callback.
-The registered callback gets invoked, when there are changes, with **three** parameters:
-`modified`, `added` and `removed` paths, in that particular order.
-Paths are always returned in their absolute form.
-
-Example:
-
-```ruby
-listener = Listen.to('path/to/app') do |modified, added, removed|
-  # This block will be called when there are changes.
-end
-listener.start
-sleep
-```
-
-or ...
-
-```ruby
-# Create a callback
-callback = Proc.new do |modified, added, removed|
-  # This proc will be called when there are changes.
-end
-listener = Listen.to('dir', &callback)
-listener.start
-sleep
-```
-
 ## Options
 
 All the following options can be set through the `Listen.to` after the directory path(s) params.
@@ -167,16 +184,42 @@ polling_fallback_message: 'custom message'      # Set a custom polling fallback
                                                 # default: "Listen will be polling for changes. Learn more at https://github.com/guard/listen#listen-adapters."
 ```
 
-## Debugging
+## Logging and Debugging
 
-Setting the environment variable `LISTEN_GEM_DEBUGGING=1` sets up the INFO level logger, while `LISTEN_GEM_DEBUGGING=2` sets up the DEBUG level logger.
+`Listen` logs its activity to `Listen.logger`.
+This is the primary method of debugging.
 
-You can also set `Listen.logger` to a custom logger.
+### Custom Logger
+You can call `Listen.logger =` to set a custom `listen` logger for the process. For example:
+```
+Listen.logger = Rails.logger
+```
 
+### Default Logger
+If no custom logger is set, a default `listen` logger which logs to to `STDERR` will be created and assigned to `Listen.logger`.
 
-## Listen adapters
+The default logger defaults to the `error` logging level (severity).
+You can override the logging level by setting the environment variable `LISTEN_GEM_DEBUGGING=<level>`.
+For `<level>`, all standard `::Logger` levels are supported, with any mix of upper-/lower-case:
+```
+export LISTEN_GEM_DEBUGGING=debug # or 2 [deprecated]
+export LISTEN_GEM_DEBUGGING=info  # or 1 or true or yes [deprecated]
+export LISTEN_GEM_DEBUGGING=warn
+export LISTEN_GEM_DEBUGGING=fatal
+export LISTEN_GEM_DEBUGGING=error
+```
+The default of `error` will be used if an unsupported value is set.
 
-The Listen gem has a set of adapters to notify it when there are changes.
+Note: The alternate values `1`, `2`, `true` and `yes` shown above are deprecated and will be removed from `listen` v4.0.
+
+### Disabling Logging
+If you want to disable `listen` logging, set
+```
+Listen.logger = ::Logger.new('/dev/null')
+```
+## Listen Adapters
+
+The `Listen` gem has a set of adapters to notify it when there are changes.
 
 There are 4 OS-specific adapters to support Darwin, Linux, \*BSD and Windows.
 These adapters are fast as they use some system-calls to implement the notifying function.
@@ -184,9 +227,9 @@ These adapters are fast as they use some system-calls to implement the notifying
 There is also a polling adapter - although it's much slower than other adapters,
 it works on every platform/system and scenario (including network filesystems such as VM shared folders).
 
-The Darwin and Linux adapters are dependencies of the Listen gem so they work out of the box. For other adapters a specific gem will have to be added to your Gemfile, please read below.
+The Darwin and Linux adapters are dependencies of the `listen` gem so they work out of the box. For other adapters a specific gem will have to be added to your Gemfile, please read below.
 
-The Listen gem will choose the best adapter automatically, if present. If you
+The `listen` gem will choose the best adapter automatically, if present. If you
 want to force the use of the polling adapter, use the `:force_polling` option
 while initializing the listener.
 
@@ -218,31 +261,33 @@ end
 
 Please visit the [installation section of the Listen WIKI](https://github.com/guard/listen/wiki#installation) for more information and options for potential fixes.
 
-### Issues and troubleshooting
+### Issues and Troubleshooting
+
+If the gem doesn't work as expected, start by setting `LISTEN_GEM_DEBUGGING=debug` or `LISTEN_GEM_DEBUGGING=info` as described above in [Logging and Debugging](#logging-and-debugging).
 
-*NOTE: without providing the output after setting the `LISTEN_GEM_DEBUGGING=1` environment variable, it can be almost impossible to guess why listen is not working as expected.*
+*NOTE: without providing the output after setting the `LISTEN_GEM_DEBUGGING=debug` environment variable, it is usually impossible to guess why `listen` is not working as expected.*
 
 See [TROUBLESHOOTING](https://github.com/guard/listen/wiki/Troubleshooting)
 
 ## Performance
 
-If Listen seems slow or unresponsive, make sure you're not using the Polling adapter (you should see a warning upon startup if you are).
+If `listen` seems slow or unresponsive, make sure you're not using the Polling adapter (you should see a warning upon startup if you are).
 
 Also, if the directories you're watching contain many files, make sure you're:
 
 * not using Polling (ideally)
 * using `:ignore` and `:only` options to avoid tracking directories you don't care about (important with Polling and on MacOS)
-* running Listen with the `:latency` and `:wait_for_delay` options not too small or too big (depends on needs)
+* running `listen` with the `:latency` and `:wait_for_delay` options not too small or too big (depends on needs)
 * not watching directories with log files, database files or other frequently changing files
-* not using a version of Listen prior to 2.7.7
-* not getting silent crashes within Listen (see LISTEN_GEM_DEBUGGING=2)
-* not running multiple instances of Listen in the background
+* not using a version of `listen` prior to 2.7.7
+* not getting silent crashes within `listen` (see `LISTEN_GEM_DEBUGGING=debug`)
+* not running multiple instances of `listen` in the background
 * using a file system with atime modification disabled (ideally)
 * not using a filesystem with inaccurate file modification times (ideally), e.g. HFS, VFAT
 * not buffering to a slow terminal (e.g. transparency + fancy font + slow gfx card + lots of output)
 * ideally not running a slow encryption stack, e.g. btrfs + ecryptfs
 
-When in doubt, LISTEN_GEM_DEBUGGING=2 can help discover the actual events and time they happened.
+When in doubt, `LISTEN_GEM_DEBUGGING=debug` can help discover the actual events and time they happened.
 
 See also [Tips and Techniques](https://github.com/guard/listen/wiki/Tips-and-Techniques).
 

data/lib/listen.rb

@@ -1,23 +1,18 @@
+# frozen_string_literal: true
+
 require 'logger'
+require 'weakref'
 require 'listen/logger'
 require 'listen/listener'
 
-require 'listen/internals/thread_pool'
-
-# Always set up logging by default first time file is required
-#
-# NOTE: If you need to clear the logger completely, do so *after*
-# requiring this file. If you need to set a custom logger,
-# require the listen/logger file and set the logger before requiring
-# this file.
-Listen.setup_default_logger_if_unset
-
 # Won't print anything by default because of level - unless you've set
 # LISTEN_GEM_DEBUGGING or provided your own logger with a high enough level
-Listen::Logger.info "Listen loglevel set to: #{Listen.logger.level}"
-Listen::Logger.info "Listen version: #{Listen::VERSION}"
+Listen.logger.info "Listen loglevel set to: #{Listen.logger.level}"
+Listen.logger.info "Listen version: #{Listen::VERSION}"
 
 module Listen
+  @listeners = Queue.new
+
   class << self
     # Listens to file system modifications on a either single directory or
     # multiple directories.
@@ -32,21 +27,21 @@ module Listen
     # @return [Listen::Listener] the listener
     #
     def to(*args, &block)
-      @listeners ||= []
       Listener.new(*args, &block).tap do |listener|
-        @listeners << listener
+        @listeners.enq(WeakRef.new(listener))
       end
     end
 
     # This is used by the `listen` binary to handle Ctrl-C
     #
     def stop
-      Internals::ThreadPool.stop
-      @listeners ||= []
-
-      # TODO: should use a mutex for this
-      @listeners.each(&:stop)
-      @listeners = nil
+      while (listener = @listeners.deq(true))
+        begin
+          listener.stop
+        rescue WeakRef::RefError
+        end
+      end
+    rescue ThreadError
     end
   end
 end

data/lib/listen/adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'listen/adapter/base'
 require 'listen/adapter/bsd'
 require 'listen/adapter/darwin'
@@ -13,15 +15,15 @@ module Listen
 
     class << self
       def select(options = {})
-        _log :debug, 'Adapter: considering polling ...'
+        Listen.logger.debug 'Adapter: considering polling ...'
         return Polling if options[:force_polling]
-        _log :debug, 'Adapter: considering optimized backend...'
+        Listen.logger.debug 'Adapter: considering optimized backend...'
         return _usable_adapter_class if _usable_adapter_class
-        _log :debug, 'Adapter: falling back to polling...'
+        Listen.logger.debug 'Adapter: falling back to polling...'
         _warn_polling_fallback(options)
         Polling
       rescue
-        _log :warn, format('Adapter: failed: %s:%s', $ERROR_POSITION.inspect,
+        Listen.logger.warn format('Adapter: failed: %s:%s', $ERROR_POSITION.inspect,
                            $ERROR_POSITION * "\n")
         raise
       end
@@ -36,10 +38,6 @@ module Listen
         msg = options.fetch(:polling_fallback_message, POLLING_FALLBACK_MESSAGE)
         Kernel.warn "[Listen warning]:\n  #{msg}" if msg
       end
-
-      def _log(type, message)
-        Listen::Logger.send(type, message)
-      end
     end
   end
 end

data/lib/listen/adapter/base.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 require 'listen/options'
 require 'listen/record'
 require 'listen/change'
+require 'listen/thread'
 
 module Listen
   module Adapter
@@ -30,7 +33,7 @@ module Listen
       # TODO: it's a separate method as a temporary workaround for tests
       def configure
         if @configured
-          _log(:warn, 'Adapter already configured!')
+          Listen.logger.warn('Adapter already configured!')
           return
         end
 
@@ -63,48 +66,39 @@ module Listen
         configure
 
         if started?
-          _log(:warn, 'Adapter already started!')
+          Listen.logger.warn('Adapter already started!')
           return
         end
 
         @started = true
 
-        calling_stack = caller.dup
-        Listen::Internals::ThreadPool.add do
-          begin
-            @snapshots.values.each do |snapshot|
-              _timed('Record.build()') { snapshot.record.build }
-            end
-            _run
-          rescue
-            msg = 'run() in thread failed: %s:\n'\
-              ' %s\n\ncalled from:\n %s'
-            _log_exception(msg, calling_stack)
-            raise # for unit tests mostly
+        @run_thread = Listen::Thread.new("run_thread") do
+          @snapshots.values.each do |snapshot|
+            _timed('Record.build()') { snapshot.record.build }
           end
+          _run
         end
       end
 
       def stop
         _stop
-      end
-
-      def self.usable?
-        const_get('OS_REGEXP') =~ RbConfig::CONFIG['target_os']
+        config.queue.close # this causes queue.pop to return `nil` to the front-end
       end
 
       private
 
       def _stop
+        @run_thread&.kill
+        @run_thread = nil
       end
 
       def _timed(title)
         start = Time.now.to_f
         yield
         diff = Time.now.to_f - start
-        Listen::Logger.info format('%s: %.05f seconds', title, diff)
+        Listen.logger.info format('%s: %.05f seconds', title, diff)
       rescue
-        Listen::Logger.warn "#{title} crashed: #{$ERROR_INFO.inspect}"
+        Listen.logger.warn "#{title} crashed: #{$ERROR_INFO.inspect}"
         raise
       end
 
@@ -114,10 +108,6 @@ module Listen
         @snapshots[dir].invalidate(type, rel_path, options)
       end
 
-      def _log(*args, &block)
-        self.class.send(:_log, *args, &block)
-      end
-
       def _log_exception(msg, caller_stack)
         formatted = format(
           msg,
@@ -126,14 +116,12 @@ module Listen
           caller_stack * "\n"
         )
 
-        _log(:error, formatted)
+        Listen.logger.error(formatted)
       end
 
       class << self
-        private
-
-        def _log(*args, &block)
-          Listen::Logger.send(*args, &block)
+        def usable?
+          const_get('OS_REGEXP') =~ RbConfig::CONFIG['target_os']
         end
       end
     end