listen 2.10.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 617639ec10e92398c4bb2ac0ee386f9f51301b77
-  data.tar.gz: 56e366a55edf6c6f926f7d70a898ed86e02e0a76
+  metadata.gz: c4dbb678714e27c96553c3eeb428437dec7fdd06
+  data.tar.gz: 852d550603e6e96e47266c54d60a14cf2d680f01
 SHA512:
-  metadata.gz: cc5839d65676759b511acbecbaef944fb8f23d4add9f5c210392b50cfab51f4ed8f4296584131f264a6b7d30218ab27c3e0c63ec6bfed0439d382112d1a34a1b
-  data.tar.gz: 63c675e1adeae3ba7fa84e35f0729558db2eefcf3ad5a0447773bbfed7328412da623cccbea50ff00ead0f4ff9a8c205793da1b6d2609b6a90f52f27e986e8f5
+  metadata.gz: 080e123c08eb97243cf24d3dbb8f989c89fe797c5be172253d393b814550c50c66f765981125a825d47b61153c69715d6501b59d4f0bbabc36883d03c65623c1
+  data.tar.gz: a601fa4b17c2fcb5345fe4cb3fa8f10aaa28f6e31b22c5d456ede3dcf8ac8b641ee3c6b31fe53f411c5f69c3bcca8cd0a51b354e7ec778f08e5486d9081327e0

data/README.md

@@ -8,7 +8,10 @@ The Listen gem listens to file modifications and notifies you about the changes.
 
 ## Known issues / Quickfixes / Workarounds
 
-Just head over here: https://github.com/guard/listen/wiki/Quickfixes,-known-issues-and-workarounds
+*NOTE: TCP functionality has been removed from Listen 3.x - please use Listen
+2.x until alternative server and client gems are created/released for 3.x.*
+
+For other issues, just head over here: https://github.com/guard/listen/wiki/Quickfixes,-known-issues-and-workarounds
 
 ## Tips and Techniques
 
@@ -20,15 +23,17 @@ Make sure you know these few basic tricks: https://github.com/guard/listen/wiki/
 * Detects file modification, addition and removal.
 * You can watch multiple directories.
 * Regexp-patterns for ignoring paths for more accuracy and speed
-* Forwarding file events over TCP, [more info](#forwarding-file-events-over-tcp) below.
 * Increased change detection accuracy on OS X HFS and VFAT volumes.
 * Tested on MRI Ruby environments (1.9+ only) via [Travis CI](https://travis-ci.org/guard/listen),
 
-Please note that:
+NOTE: TCP functionality has been moved to a separate gem (listen-server and listen-client)
+
+NOTES:
 - 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 automaticaly tested.
 
+
 ## Pending features / issues
 
 * symlinked directories aren't fully transparent yet: https://github.com/guard/listen/issues/279
@@ -42,9 +47,10 @@ Pull request or help is very welcome for these.
 The simplest way to install Listen is to use [Bundler](http://bundler.io).
 
 ```ruby
-gem 'listen', '~> 2.7' # this prevents upgrading to 3.x
+gem 'listen', '~> 3.0' # NOTE: for TCP functionality, use '~> 2.10' for now
 ```
 
+
 ## Usage
 
 Call `Listen.to` with either a single directory or multiple directories, then define the "changes" callback in a block.
@@ -166,7 +172,7 @@ force_polling: true                             # Force the use of the polling a
 relative: false                                 # Whether changes should be relative to current dir or not
                                                 # default: false
 
-debug: true                                     # Enable Celluloid logger
+debug: true                                     # Enable Listen logger
                                                 # default: false
 
 polling_fallback_message: 'custom message'      # Set a custom polling fallback message (or disable it with false)
@@ -247,47 +253,6 @@ Also, if the directories you're watching contain many files, make sure you're:
 
 When in doubt, LISTEN_GEM_DEBUGGING=2 can help discover the actual events and time they happened.
 
-## Forwarding file events over TCP
-
-Listen is capable of forwarding file events over the network using a messaging protocol. This can be useful for virtualized development environments when file events are unavailable, as is the case with shared folders in VMs.
-
-[Vagrant](https://github.com/mitchellh/vagrant) uses Listen in it's rsync-auto mode to solve this issue.
-
-To broadcast events over TCP programmatically, use the `forward_to` option with an address - just a port or a hostname/port combination:
-
-```ruby
-listener = Listen.to 'path/to/app', forward_to: '10.0.0.2:4000' do |modified, added, removed|
-  # After broadcasting the changes to any connected recipients,
-  # this block will still be called
-end
-listener.start
-sleep
-```
-
-As a convenience, the `listen` script is supplied which listens to a directory and forwards the events to a network address
-
-```bash
-listen -f "10.0.0.2:4000" # changes in current directory are sent as absolute paths
-listen -r -f "10.0.0.2:4000" # changes in current directory are sent as relative paths
-listen -v -d "/projects/my_project" -f "10.0.0.2:4000" # changes in given directory are also shown
-```
-
-*NOTE: if you are using a gem like `guard` and the paths on host and guest are not exactly the same, you'll generally want to use the `-r` option for relative paths*
-
-To connect to a broadcasting listener as a recipient, specify its address using `Listen.on`:
-
-```ruby
-listener = Listen.on '10.0.0.2:4000' do |modified, added, removed|
-  # This block will be called
-end
-listener.start
-sleep
-```
-
-### Security considerations
-
-Since file events potentially expose sensitive information, care must be taken when specifying the broadcaster address. It is recommended to **always** specify a hostname and make sure it is as specific as possible to reduce any undesirable eavesdropping.
-
 ## Development
 
 * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/listen/master/frames).

data/lib/listen.rb

@@ -1,16 +1,27 @@
-require 'celluloid'
+require 'logger'
+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}"
+
 module Listen
   class << self
     # Listens to file system modifications on a either single directory or
     # multiple directories.
     #
-    # When :forward_to is specified, this listener will broadcast modifications
-    # over TCP.
-    #
     # @param (see Listen::Listener#new)
     #
     # @yield [modified, added, removed] the changed files
@@ -21,18 +32,12 @@ module Listen
     # @return [Listen::Listener] the listener
     #
     def to(*args, &block)
-      Celluloid.boot unless Celluloid.running?
-      options = args.last.is_a?(Hash) ? args.last : {}
-      target = options.delete(:forward_to)
-      args = ([target, :broadcaster] + args) if target
-      _add_listener(*args, &block)
+      @listeners ||= []
+      Listener.new(*args, &block).tap do |listener|
+        @listeners << listener
+      end
     end
 
-    # Stop all listeners & Celluloid
-    #
-    # Use it for testing purpose or when you are sure that Celluloid could be
-    # ended.
-    #
     # This is used by the `listen` binary to handle Ctrl-C
     #
     def stop
@@ -45,32 +50,6 @@ module Listen
         listener.stop
       end
       @listeners = nil
-
-      Celluloid.shutdown
-    end
-
-    # Listens to file system modifications broadcast over TCP.
-    #
-    # @param [String/Fixnum] target to listen on (hostname:port or port)
-    #
-    # @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
-    #
-    # @return [Listen::Listener] the listener
-    #
-    def on(target, *args, &block)
-      _add_listener(target, :recipient, *args, &block)
-    end
-
-    private
-
-    def _add_listener(*args, &block)
-      @listeners ||= []
-      Listener.new(*args, &block).tap do |listener|
-        @listeners << listener
-      end
     end
   end
 end

data/lib/listen/adapter.rb

@@ -12,8 +12,6 @@ module Listen
       'Learn more at https://github.com/guard/listen#listen-adapters.'
 
     def self.select(options = {})
-      _log :debug, 'Adapter: considering TCP ...'
-      return TCP if options[:force_tcp]
       _log :debug, 'Adapter: considering polling ...'
       return Polling if options[:force_polling]
       _log :debug, 'Adapter: considering optimized backend...'
@@ -39,7 +37,7 @@ module Listen
     end
 
     def self._log(type, message)
-      Celluloid::Logger.send(type, message)
+      Listen::Logger.send(type, message)
     end
   end
 end

data/lib/listen/adapter/base.rb

@@ -1,32 +1,27 @@
 require 'listen/options'
+require 'listen/record'
+require 'listen/change'
 
 module Listen
   module Adapter
     class Base
-      include Celluloid
-
       attr_reader :options
 
       # TODO: only used by tests
       DEFAULTS = {}
 
-      def initialize(opts)
-        @configured = nil
-        options = opts.dup
-        @mq = options.delete(:mq)
-        @directories = options.delete(:directories)
+      attr_reader :config
 
-        Array(@directories).each do |dir|
-          next if dir.is_a?(Pathname)
-          fail ArgumentError, "not a Pathname: #{dir.inspect}"
-        end
+      def initialize(config)
+        @started = false
+        @config = config
 
-        # TODO: actually use this in every adapter
-        @recursion = options.delete(:recursion)
-        @recursion = true if @recursion.nil?
+        @configured = nil
+
+        fail 'No directories to watch!' if config.directories.empty?
 
         defaults = self.class.const_get('DEFAULTS')
-        @options = Listen::Options.new(options, defaults)
+        @options = Listen::Options.new(config.adapter_options, defaults)
       rescue
         _log_exception 'adapter config failed: %s:%s called from: %s', caller
         raise
@@ -34,50 +29,82 @@ module Listen
 
       # TODO: it's a separate method as a temporary workaround for tests
       def configure
-        return if @configured
+        if @configured
+          _log(:warn, 'Adapter already configured!')
+          return
+        end
+
         @configured = true
 
         @callbacks ||= {}
-        @directories.each do |dir|
-          unless dir.is_a?(Pathname)
-            fail ArgumentError, "not a Pathname: #{dir.inspect}"
-          end
-
+        config.directories.each do |dir|
           callback = @callbacks[dir] || lambda do |event|
             _process_event(dir, event)
           end
           @callbacks[dir] = callback
           _configure(dir, &callback)
         end
+
+        @snapshots ||= {}
+        # TODO: separate config per directory (some day maybe)
+        change_config = Change::Config.new(config.queue, config.silencer)
+        config.directories.each do |dir|
+          record = Record.new(dir)
+          snapshot = Change.new(change_config, record)
+          @snapshots[dir] = snapshot
+        end
+      end
+
+      def started?
+        @started
       end
 
       def start
         configure
+
+        if started?
+          _log(: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
-            _log_exception "run() in thread failed: %s:\n %s\n\ncalled from:\n %s", calling_stack
-            raise
+            msg = 'run() in thread failed: %s:\n'\
+              ' %s\n\ncalled from:\n %s'
+            _log_exception(msg, calling_stack)
+            raise # for unit tests mostly
           end
         end
       end
 
-      def self.local_fs?
-        true
-      end
-
       def self.usable?
         const_get('OS_REGEXP') =~ RbConfig::CONFIG['target_os']
       end
 
       private
 
+      def _timed(title)
+        start = Time.now.to_f
+        yield
+        diff = Time.now.to_f - start
+        Listen::Logger.info format('%s: %.05f seconds', title, diff)
+      rescue
+        Listen::Logger.warn "#{title} crashed: #{$ERROR_INFO.inspect}"
+        raise
+      end
+
+      # TODO: allow backend adapters to pass specific invalidation objects
+      # e.g. Darwin -> DirRescan, INotify -> MoveScan, etc.
       def _queue_change(type, dir, rel_path, options)
-        # TODO: temporary workaround to remove dependency on Change through
-        # Celluloid in tests
-        @mq.send(:_queue_raw_change, type, dir, rel_path, options)
+        @snapshots[dir].invalidate(type, rel_path, options)
       end
 
       def _log(*args, &block)
@@ -85,15 +112,18 @@ module Listen
       end
 
       def _log_exception(msg, caller_stack)
-        _log :error, format(msg, $ERROR_INFO, $ERROR_POSITION * "\n", caller_stack * "\n")
+        formatted = format(
+          msg,
+          $ERROR_INFO,
+          $ERROR_POSITION * "\n",
+          caller_stack * "\n"
+        )
+
+        _log(:error, formatted)
       end
 
       def self._log(*args, &block)
-        if block
-          Celluloid::Logger.send(*args, block.call)
-        else
-          Celluloid::Logger.send(*args)
-        end
+        Listen::Logger.send(*args, &block)
       end
     end
   end

data/lib/listen/adapter/config.rb

@@ -0,0 +1,21 @@
+module Listen
+  module Adapter
+    class Config
+      attr_reader :directories
+      attr_reader :silencer
+      attr_reader :queue
+      attr_reader :adapter_options
+
+      def initialize(directories, queue, silencer, adapter_options)
+        # TODO: fix (flatten, array, compact?)
+        @directories = directories.map do |directory|
+          Pathname.new(directory.to_s).realpath
+        end
+
+        @silencer = silencer
+        @queue = queue
+        @adapter_options = adapter_options
+      end
+    end
+  end
+end

data/lib/listen/adapter/linux.rb

@@ -12,7 +12,8 @@ module Listen
           :delete,
           :move,
           :close_write
-        ]
+        ],
+        wait_for_delay: 0.1
       }
 
       private
@@ -26,13 +27,10 @@ module Listen
       EOS
 
       def _configure(directory, &callback)
-        require 'rb-inotify'
-        @worker ||= INotify::Notifier.new
+        Kernel.require 'rb-inotify'
+        @worker ||= ::INotify::Notifier.new
         @worker.watch(directory.to_s, *options.events, &callback)
       rescue Errno::ENOSPC
-        # workaround - Celluloid catches abort and prints nothing
-        STDERR.puts INOTIFY_LIMIT_MESSAGE
-        STDERR.flush
         abort(INOTIFY_LIMIT_MESSAGE)
       end
 
@@ -47,7 +45,7 @@ module Listen
         path = Pathname.new(event.watcher.path) + event.name
         rel_path = path.relative_path_from(dir).to_s
 
-        _log :debug, "inotify: #{rel_path} (#{event.flags.inspect})"
+        _log(:debug) { "inotify: #{rel_path} (#{event.flags.inspect})" }
 
         if /1|true/ =~ ENV['LISTEN_GEM_SIMULATE_FSEVENT']
           if (event.flags & [:moved_to, :moved_from]) || _dir_event?(event)

data/lib/listen/adapter/polling.rb

@@ -8,7 +8,7 @@ module Listen
     class Polling < Base
       OS_REGEXP = // # match every OS
 
-      DEFAULTS = { latency: 1.0 }
+      DEFAULTS = { latency: 1.0, wait_for_delay: 0.05 }
 
       private
 
@@ -23,6 +23,7 @@ module Listen
           @polling_callbacks.each do |callback|
             callback.call(nil)
             nap_time = options.latency - (Time.now.to_f - start)
+            # TODO: warn if nap_time is negative (polling too slow)
             sleep(nap_time) if nap_time > 0
           end
         end