listen 3.1.5 → 3.7.0

data/lib/listen/event/loop.rb

@@ -1,55 +1,62 @@
+# frozen_string_literal: true
+
 require 'thread'
 
 require 'timeout'
 require 'listen/event/processor'
+require 'listen/thread'
+require 'listen/error'
 
 module Listen
   module Event
     class Loop
-      class Error < RuntimeError
-        class NotStarted < Error
-        end
-      end
+      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
-        @state = :paused
         @reasons = ::Queue.new
+        initialize_fsm
       end
 
       def wakeup_on_event
-        return if stopped?
-        return unless processing?
-        return unless wait_thread.alive?
-        _wakeup(:event)
+        if started? && @wait_thread&.alive?
+          _wakeup(:event)
+        end
       end
 
-      def paused?
-        wait_thread && state == :paused
+      def started?
+        state == :started
       end
 
-      def processing?
-        return false if stopped?
-        return false if paused?
-        state == :processing
-      end
+      MAX_STARTUP_SECONDS = 5.0
 
-      def setup
+      # @raises Error::NotStarted if background thread hasn't started in MAX_STARTUP_SECONDS
+      def start
         # TODO: use a Fiber instead?
-        q = ::Queue.new
-        @wait_thread = Internals::ThreadPool.add do
-          _wait_for_changes(q, config)
+        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...')
-        Timeout.timeout(5) { q.pop }
-      end
+        Listen.logger.debug("Waiting for processing to start...")
 
-      def resume
-        fail Error::NotStarted if stopped?
-        return unless wait_thread
-        _wakeup(:resume)
+        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
@@ -57,60 +64,30 @@ module Listen
         # fail NotImplementedError
       end
 
-      def teardown
-        return unless wait_thread
-        if wait_thread.alive?
-          _wakeup(:teardown)
-          wait_thread.join
-        end
+      def stop
+        transition! :stopped
+
+        @wait_thread&.join
         @wait_thread = nil
       end
 
       def stopped?
-        !wait_thread
+        state == :stopped
       end
 
       private
 
-      attr_reader :config
-      attr_reader :wait_thread
-
-      attr_accessor :state
-
-      def _wait_for_changes(ready_queue, config)
-        processor = Event::Processor.new(config, @reasons)
+      def _process_changes
+        processor = Event::Processor.new(@config, @reasons)
 
-        _wait_until_resumed(ready_queue)
-        processor.loop_for(config.min_delay_between_events)
-      rescue StandardError => ex
-        _nice_error(ex)
-      end
-
-      def _sleep(*args)
-        Kernel.sleep(*args)
-      end
-
-      def _wait_until_resumed(ready_queue)
-        self.state = :paused
-        ready_queue << :ready
-        sleep
-        self.state = :processing
-      end
+        transition! :started
 
-      def _nice_error(ex)
-        indent = "\n -- "
-        msg = format(
-          'exception while processing events: %s Backtrace:%s%s',
-          ex,
-          indent,
-          ex.backtrace * indent
-        )
-        Listen::Logger.error(msg)
+        processor.loop_for(@config.min_delay_between_events)
       end
 
       def _wakeup(reason)
         @reasons << reason
-        wait_thread.wakeup
+        @wait_thread.wakeup
       end
     end
   end

data/lib/listen/event/processor.rb

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+
+require 'listen/monotonic_time'
+
 module Listen
   module Event
     class Processor
       def initialize(config, reasons)
         @config = config
+        @listener = config.listener
         @reasons = reasons
         _reset_no_unprocessed_events
       end
@@ -13,13 +18,14 @@ module Listen
         @latency = latency
 
         loop do
-          _wait_until_events
+          event = _wait_until_events
+          _check_stopped
           _wait_until_events_calm_down
           _wait_until_no_longer_paused
-          _process_changes
+          _process_changes(event)
         end
       rescue Stopped
-        Listen::Logger.debug('Processing stopped')
+        Listen.logger.debug('Processing stopped')
       end
 
       private
@@ -29,7 +35,7 @@ module Listen
 
       def _wait_until_events_calm_down
         loop do
-          now = _timestamp
+          now = MonotonicTime.now
 
           # Assure there's at least latency between callbacks to allow
           # for accumulating changes
@@ -38,82 +44,80 @@ module Listen
 
           # give events a bit of time to accumulate so they can be
           # compressed/optimized
-          _sleep(:waiting_until_latency, diff)
+          _sleep(diff)
         end
       end
 
       def _wait_until_no_longer_paused
-        # TODO: may not be a good idea?
-        _sleep(:waiting_for_unpause) while config.paused?
+        @listener.wait_for_state(*(Listener.states.keys - [:paused]))
       end
 
       def _check_stopped
-        return unless config.stopped?
-
-        _flush_wakeup_reasons
-        raise Stopped
+        if @listener.stopped?
+          _flush_wakeup_reasons
+          raise Stopped
+        end
       end
 
-      def _sleep(_local_reason, *args)
+      def _sleep(seconds)
         _check_stopped
-        sleep_duration = config.sleep(*args)
+        config.sleep(seconds)
         _check_stopped
 
         _flush_wakeup_reasons do |reason|
-          next unless reason == :event
-          _remember_time_of_first_unprocessed_event unless config.paused?
+          if reason == :event && !@listener.paused?
+            _remember_time_of_first_unprocessed_event
+          end
         end
-
-        sleep_duration
       end
 
       def _remember_time_of_first_unprocessed_event
-        @first_unprocessed_event_time ||= _timestamp
+        @_remember_time_of_first_unprocessed_event ||= MonotonicTime.now
       end
 
       def _reset_no_unprocessed_events
-        @first_unprocessed_event_time = nil
+        @_remember_time_of_first_unprocessed_event = nil
       end
 
       def _deadline
-        @first_unprocessed_event_time + @latency
+        @_remember_time_of_first_unprocessed_event + @latency
       end
 
+      # blocks until event is popped
+      # returns the event or `nil` when the event_queue is closed
       def _wait_until_events
-        # TODO: long sleep may not be a good idea?
-        _sleep(:waiting_for_events) while config.event_queue.empty?
-        @first_unprocessed_event_time ||= _timestamp
+        config.event_queue.pop.tap do |_event|
+          @_remember_time_of_first_unprocessed_event ||= MonotonicTime.now
+        end
       end
 
       def _flush_wakeup_reasons
-        reasons = @reasons
-        until reasons.empty?
-          reason = reasons.pop
+        until @reasons.empty?
+          reason = @reasons.pop
           yield reason if block_given?
         end
       end
 
-      def _timestamp
-        config.timestamp
-      end
-
       # for easier testing without sleep loop
-      def _process_changes
+      def _process_changes(event)
         _reset_no_unprocessed_events
 
-        changes = []
+        changes = [event]
         changes << config.event_queue.pop until config.event_queue.empty?
 
-        callable = config.callable?
-        return unless callable
+        return unless config.callable?
 
         hash = config.optimize_changes(changes)
         result = [hash[:modified], hash[:added], hash[:removed]]
         return if result.all?(&:empty?)
 
-        block_start = _timestamp
-        config.call(*result)
-        Listen::Logger.debug "Callback took #{_timestamp - block_start} sec"
+        block_start = MonotonicTime.now
+        exception_note = " (exception)"
+        ::Listen::Thread.rescue_and_log('_process_changes') do
+          config.call(*result)
+          exception_note = nil
+        end
+        Listen.logger.debug "Callback#{exception_note} took #{MonotonicTime.now - block_start} sec"
       end
 
       attr_reader :config

data/lib/listen/event/queue.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'thread'
 
 require 'forwardable'
@@ -17,9 +19,8 @@ module Listen
         end
       end
 
-      def initialize(config, &block)
+      def initialize(config)
         @event_queue = ::Queue.new
-        @block = block
         @config = config
       end
 
@@ -29,23 +30,21 @@ module Listen
         fail "Invalid change: #{change.inspect}" unless change.is_a?(Symbol)
         fail "Invalid path: #{path.inspect}" unless path.is_a?(String)
 
-        dir = _safe_relative_from_cwd(dir)
-        event_queue.public_send(:<<, [type, change, dir, path, options])
-
-        block.call(args) if block
+        dir = if @config.relative?
+          _safe_relative_from_cwd(dir)
+        else
+          dir
+        end
+        @event_queue << [type, change, dir, path, options]
       end
 
-      delegate empty?: :event_queue
-      delegate pop: :event_queue
+      delegate empty?: :@event_queue
+      delegate pop: :@event_queue
+      delegate close: :@event_queue
 
       private
 
-      attr_reader :event_queue
-      attr_reader :block
-      attr_reader :config
-
       def _safe_relative_from_cwd(dir)
-        return dir unless config.relative?
         dir.relative_path_from(Pathname.pwd)
       rescue ArgumentError
         dir

data/lib/listen/file.rb

@@ -1,12 +1,17 @@
-require 'digest/md5'
+# frozen_string_literal: true
+
+require 'digest'
 
 module Listen
   class File
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
     def self.change(record, rel_path)
       path = Pathname.new(record.root) + rel_path
       lstat = path.lstat
 
-      data = { mtime: lstat.mtime.to_f, mode: lstat.mode }
+      data = { mtime: lstat.mtime.to_f, mode: lstat.mode, size: lstat.size }
 
       record_data = record.file_data(rel_path)
 
@@ -25,6 +30,11 @@ module Listen
         return :modified
       end
 
+      if data[:size] != record_data[:size]
+        record.update_file(rel_path, data)
+        return :modified
+      end
+
       return if /1|true/ =~ ENV['LISTEN_GEM_DISABLE_HASHING']
       return unless inaccurate_mac_time?(lstat)
 
@@ -43,7 +53,7 @@ module Listen
       # then at ???14.998, but the fstat time would be ???14.0 in
       # both cases).
       #
-      # If change happend at ???14.999997, the mtime is 14.0, so for
+      # If change happened at ???14.999997, the mtime is 14.0, so for
       # an mtime=???14.0 we assume it could even be almost ???15.0
       #
       # So if Time.now.to_f is ???15.999998 and stat reports mtime
@@ -57,16 +67,21 @@ module Listen
       #
       return if data[:mtime].to_i + 2 <= Time.now.to_f
 
-      md5 = Digest::MD5.file(path).digest
-      record.update_file(rel_path, data.merge(md5: md5))
-      :modified if record_data[:md5] && md5 != record_data[:md5]
+      sha = Digest::SHA256.file(path).digest
+      record.update_file(rel_path, data.merge(sha: sha))
+      if record_data[:sha] && sha != record_data[:sha]
+        :modified
+      end
     rescue SystemCallError
       record.unset_path(rel_path)
       :removed
     rescue
-      Listen::Logger.debug "lstat failed for: #{rel_path} (#{$ERROR_INFO})"
+      Listen.logger.debug "lstat failed for: #{rel_path} (#{$ERROR_INFO})"
       raise
     end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
 
     def self.inaccurate_mac_time?(stat)
       # 'mac' means Modified/Accessed/Created

data/lib/listen/fsm.rb

@@ -1,120 +1,123 @@
+# frozen_string_literal: true
+
 # Code copied from https://github.com/celluloid/celluloid-fsm
+
+require 'thread'
+
 module Listen
   module FSM
-    DEFAULT_STATE = :default # Default state name unless one is explicitly set
-
     # Included hook to extend class methods
     def self.included(klass)
       klass.send :extend, ClassMethods
     end
 
     module ClassMethods
-      # Obtain or set the default state
-      # Passing a state name sets the default state
-      def default_state(new_default = nil)
-        if new_default
-          @default_state = new_default.to_sym
+      # Obtain or set the start state
+      # Passing a state name sets the start state
+      def start_state(new_start_state = nil)
+        if new_start_state
+          new_start_state.is_a?(Symbol) or raise ArgumentError, "state name must be a Symbol (got #{new_start_state.inspect})"
+          @start_state = new_start_state
         else
-          defined?(@default_state) ? @default_state : DEFAULT_STATE
+          defined?(@start_state) or raise ArgumentError, "`start_state :<state>` must be declared before `new`"
+          @start_state
         end
       end
 
-      # Obtain the valid states for this FSM
+      # The valid states for this FSM, as a hash with state name symbols as keys and State objects as values.
       def states
         @states ||= {}
       end
 
-      # Declare an FSM state and optionally provide a callback block to fire
+      # Declare an FSM state and optionally provide a callback block to fire on state entry
       # Options:
       # * to: a state or array of states this state can transition to
-      def state(*args, &block)
-        if args.last.is_a? Hash
-          # Stringify keys :/
-          options = args.pop.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
-        else
-          options = {}
-        end
-
-        args.each do |name|
-          name = name.to_sym
-          default_state name if options['default']
-          states[name] = State.new(name, options['to'], &block)
-        end
+      def state(state_name, to: nil, &block)
+        state_name.is_a?(Symbol) or raise ArgumentError, "state name must be a Symbol (got #{state_name.inspect})"
+        states[state_name] = State.new(state_name, to, &block)
       end
     end
 
-    # Be kind and call super if you must redefine initialize
-    def initialize
-      @state = self.class.default_state
+    # Note: including classes must call initialize_fsm from their initialize method.
+    def initialize_fsm
+      @fsm_initialized = true
+      @state = self.class.start_state
+      @mutex = ::Mutex.new
+      @state_changed = ::ConditionVariable.new
     end
 
-    # Obtain the current state of the FSM
+    # Current state of the FSM, stored as a symbol
     attr_reader :state
 
-    def transition(state_name)
-      new_state = validate_and_sanitize_new_state(state_name)
-      return unless new_state
-      transition_with_callbacks!(new_state)
+    # checks for one of the given states to wait for
+    # if not already, waits for a state change (up to timeout seconds--`nil` means infinite)
+    # returns truthy iff the transition to one of the desired state has occurred
+    def wait_for_state(*wait_for_states, timeout: nil)
+      wait_for_states.each do |state|
+        state.is_a?(Symbol) or raise ArgumentError, "states must be symbols (got #{state.inspect})"
+      end
+      @mutex.synchronize do
+        if !wait_for_states.include?(@state)
+          @state_changed.wait(@mutex, timeout)
+        end
+        wait_for_states.include?(@state)
+      end
     end
 
-    # Immediate state transition with no checks, or callbacks. "Dangerous!"
-    def transition!(state_name)
-      @state = state_name
-    end
+    private
 
-    protected
+    def transition(new_state_name)
+      new_state_name.is_a?(Symbol) or raise ArgumentError, "state name must be a Symbol (got #{new_state_name.inspect})"
+      if (new_state = validate_and_sanitize_new_state(new_state_name))
+        transition_with_callbacks!(new_state)
+      end
+    end
 
-    def validate_and_sanitize_new_state(state_name)
-      state_name = state_name.to_sym
+    # Low-level, immediate state transition with no checks or callbacks.
+    def transition!(new_state_name)
+      new_state_name.is_a?(Symbol) or raise ArgumentError, "state name must be a Symbol (got #{new_state_name.inspect})"
+      @fsm_initialized or raise ArgumentError, "FSM not initialized. You must call initialize_fsm from initialize!"
+      @mutex.synchronize do
+        yield if block_given?
+        @state = new_state_name
+        @state_changed.broadcast
+      end
+    end
 
-      return if current_state_name == state_name
+    def validate_and_sanitize_new_state(new_state_name)
+      return nil if @state == new_state_name
 
-      if current_state && !current_state.valid_transition?(state_name)
+      if current_state && !current_state.valid_transition?(new_state_name)
         valid = current_state.transitions.map(&:to_s).join(', ')
-        msg = "#{self.class} can't change state from '#{@state}'"\
-          " to '#{state_name}', only to: #{valid}"
-        fail ArgumentError, msg
+        msg = "#{self.class} can't change state from '#{@state}' to '#{new_state_name}', only to: #{valid}"
+        raise ArgumentError, msg
       end
 
-      new_state = states[state_name]
-
-      unless new_state
-        return if state_name == default_state
-        fail ArgumentError, "invalid state for #{self.class}: #{state_name}"
+      unless (new_state = self.class.states[new_state_name])
+        new_state_name == self.class.start_state or raise ArgumentError, "invalid state for #{self.class}: #{new_state_name}"
       end
 
       new_state
     end
 
-    def transition_with_callbacks!(state_name)
-      transition! state_name.name
-      state_name.call(self)
-    end
-
-    def states
-      self.class.states
-    end
-
-    def default_state
-      self.class.default_state
+    def transition_with_callbacks!(new_state)
+      transition! new_state.name
+      new_state.call(self)
     end
 
     def current_state
-      states[@state]
-    end
-
-    def current_state_name
-      current_state && current_state.name || ''
+      self.class.states[@state]
     end
 
     class State
       attr_reader :name, :transitions
 
-      def initialize(name, transitions = nil, &block)
+      def initialize(name, transitions, &block)
         @name = name
         @block = block
-        @transitions = nil
-        @transitions = Array(transitions).map(&:to_sym) if transitions
+        @transitions = if transitions
+          Array(transitions).map(&:to_sym)
+        end
       end
 
       def call(obj)
@@ -122,10 +125,8 @@ module Listen
       end
 
       def valid_transition?(new_state)
-        # All transitions are allowed unless expressly
-        return true unless @transitions
-
-        @transitions.include? new_state.to_sym
+        # All transitions are allowed if none are expressly declared
+        !@transitions || @transitions.include?(new_state.to_sym)
       end
     end
   end

data/lib/listen/listener/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Listen
   class Listener
     class Config
@@ -23,9 +25,7 @@ module Listen
         @relative
       end
 
-      attr_reader :min_delay_between_events
-
-      attr_reader :silencer_rules
+      attr_reader :min_delay_between_events, :silencer_rules
 
       def adapter_instance_options(klass)
         valid_keys = klass.const_get('DEFAULTS').keys
@@ -33,7 +33,7 @@ module Listen
       end
 
       def adapter_select_options
-        valid_keys = %w(force_polling polling_fallback_message).map(&:to_sym)
+        valid_keys = %w[force_polling polling_fallback_message].map(&:to_sym)
         Hash[@options.select { |key, _| valid_keys.include?(key) }]
       end
     end