Publish AS::Executor and AS::Reloader APIs

These should allow external code to run blocks of user code to do
"work", at a similar unit size to a web request, without needing to get
intimate with ActionDipatch.

11 files changed, 382 insertions, 10 deletions

diff --git a/activesupport/CHANGELOG.md b/activesupport/CHANGELOG.md
index 1a169d36be..28ce293bce 100644
--- a/activesupport/CHANGELOG.md
+++ b/activesupport/CHANGELOG.md
@@ -1,3 +1,10 @@
+*   Publish ActiveSupport::Executor and ActiveSupport::Reloader APIs to allow
+    components and libraries to manage, and participate in, the execution of
+    application code, and the application reloading process.
+
+    *Matthew Draper*
+
+
 ## Rails 5.0.0.beta3 (February 24, 2016) ##
 
 *   Deprecate arguments on `assert_nothing_raised`.
diff --git a/activesupport/lib/active_support.rb b/activesupport/lib/active_support.rb
index 94fe893149..72777baecd 100644
--- a/activesupport/lib/active_support.rb
+++ b/activesupport/lib/active_support.rb
@@ -33,10 +33,13 @@ module ActiveSupport
   autoload :Concern
   autoload :Dependencies
   autoload :DescendantsTracker
+  autoload :ExecutionWrapper
+  autoload :Executor
   autoload :FileUpdateChecker
   autoload :EventedFileUpdateChecker
   autoload :LogSubscriber
   autoload :Notifications
+  autoload :Reloader
 
   eager_autoload do
     autoload :BacktraceCleaner
diff --git a/activesupport/lib/active_support/dependencies/interlock.rb b/activesupport/lib/active_support/dependencies/interlock.rb
index 47bcecbb35..f1865ca2f8 100644
--- a/activesupport/lib/active_support/dependencies/interlock.rb
+++ b/activesupport/lib/active_support/dependencies/interlock.rb
@@ -19,14 +19,12 @@ module ActiveSupport #:nodoc:
         end
       end
 
-      # Attempt to obtain an "unloading" (exclusive) lock. If possible,
-      # execute the supplied block while holding the lock. If there is
-      # concurrent activity, return immediately (without executing the
-      # block) instead of waiting.
-      def attempt_unloading
-        @lock.exclusive(purpose: :unload, compatible: [:load, :unload], after_compatible: [:load, :unload], no_wait: true) do
-          yield
-        end
+      def start_unloading
+        @lock.start_exclusive(purpose: :unload, compatible: [:load, :unload])
+      end
+
+      def done_unloading
+        @lock.stop_exclusive(compatible: [:load, :unload])
       end
 
       def start_running
diff --git a/activesupport/lib/active_support/evented_file_update_checker.rb b/activesupport/lib/active_support/evented_file_update_checker.rb
index 315be85fb3..63f4f7e277 100644
--- a/activesupport/lib/active_support/evented_file_update_checker.rb
+++ b/activesupport/lib/active_support/evented_file_update_checker.rb
@@ -37,6 +37,7 @@ module ActiveSupport
 
     def execute_if_updated
       if updated?
+        yield if block_given?
         execute
         true
       end
diff --git a/activesupport/lib/active_support/execution_wrapper.rb b/activesupport/lib/active_support/execution_wrapper.rb
new file mode 100644
index 0000000000..e784556abf
--- /dev/null
+++ b/activesupport/lib/active_support/execution_wrapper.rb
@@ -0,0 +1,69 @@
+require 'active_support/callbacks'
+
+module ActiveSupport
+  class ExecutionWrapper
+    include ActiveSupport::Callbacks
+
+    define_callbacks :run
+    define_callbacks :complete
+
+    def self.to_run(*args, &block)
+      set_callback(:run, *args, &block)
+    end
+
+    def self.to_complete(*args, &block)
+      set_callback(:complete, *args, &block)
+    end
+
+    # Run this execution.
+    #
+    # Returns an instance, whose +complete!+ method *must* be invoked
+    # after the work has been performed.
+    #
+    # Where possible, prefer +wrap+.
+    def self.run!
+      new.tap(&:run!)
+    end
+
+    # Perform the work in the supplied block as an execution.
+    def self.wrap
+      return yield if active?
+
+      state = run!
+      begin
+        yield
+      ensure
+        state.complete!
+      end
+    end
+
+    class << self # :nodoc:
+      attr_accessor :active
+    end
+
+    def self.inherited(other) # :nodoc:
+      super
+      other.active = Concurrent::Hash.new(0)
+    end
+
+    self.active = Concurrent::Hash.new(0)
+
+    def self.active? # :nodoc:
+      @active[Thread.current] > 0
+    end
+
+    def run! # :nodoc:
+      self.class.active[Thread.current] += 1
+      run_callbacks(:run)
+    end
+
+    # Complete this in-flight execution. This method *must* be called
+    # exactly once on the result of any call to +run!+.
+    #
+    # Where possible, prefer +wrap+.
+    def complete!
+      run_callbacks(:complete)
+      self.class.active.delete Thread.current if (self.class.active[Thread.current] -= 1) == 0
+    end
+  end
+end
diff --git a/activesupport/lib/active_support/executor.rb b/activesupport/lib/active_support/executor.rb
new file mode 100644
index 0000000000..602fb11a44
--- /dev/null
+++ b/activesupport/lib/active_support/executor.rb
@@ -0,0 +1,6 @@
+require 'active_support/execution_wrapper'
+
+module ActiveSupport
+  class Executor < ExecutionWrapper
+  end
+end
diff --git a/activesupport/lib/active_support/file_update_checker.rb b/activesupport/lib/active_support/file_update_checker.rb
index 1fa9335080..dc7434fcac 100644
--- a/activesupport/lib/active_support/file_update_checker.rb
+++ b/activesupport/lib/active_support/file_update_checker.rb
@@ -81,6 +81,7 @@ module ActiveSupport
     # Execute the block given if updated.
     def execute_if_updated
       if updated?
+        yield if block_given?
         execute
         true
       else
diff --git a/activesupport/lib/active_support/i18n_railtie.rb b/activesupport/lib/active_support/i18n_railtie.rb
index 82aacf3b24..6cc7c90c12 100644
--- a/activesupport/lib/active_support/i18n_railtie.rb
+++ b/activesupport/lib/active_support/i18n_railtie.rb
@@ -64,8 +64,8 @@ module I18n
       end
 
       app.reloaders << reloader
-      ActionDispatch::Reloader.to_prepare do
-        reloader.execute_if_updated
+      app.reloader.to_run do
+        reloader.execute_if_updated { require_unload_lock! }
         # TODO: remove the following line as soon as the return value of
         # callbacks is ignored, that is, returning `false` does not
         # display a deprecation warning or halts the callback chain.
diff --git a/activesupport/lib/active_support/reloader.rb b/activesupport/lib/active_support/reloader.rb
new file mode 100644
index 0000000000..639b987ba8
--- /dev/null
+++ b/activesupport/lib/active_support/reloader.rb
@@ -0,0 +1,126 @@
+require 'active_support/execution_wrapper'
+
+module ActiveSupport
+  #--
+  # This class defines several callbacks:
+  #
+  #   to_prepare -- Run once at application startup, and also from
+  #   +to_run+.
+  #
+  #   to_run -- Run before a work run that is reloading. If
+  #   +reload_classes_only_on_change+ is true (the default), the class
+  #   unload will have already occurred.
+  #
+  #   to_complete -- Run after a work run that has reloaded. If
+  #   +reload_classes_only_on_change+ is false, the class unload will
+  #   have occurred after the work run, but before this callback.
+  #
+  #   before_class_unload -- Run immediately before the classes are
+  #   unloaded.
+  #
+  #   after_class_unload -- Run immediately after the classes are
+  #   unloaded.
+  #
+  class Reloader < ExecutionWrapper
+    Null = Class.new(ExecutionWrapper) # :nodoc:
+
+    define_callbacks :prepare
+
+    define_callbacks :class_unload
+
+    def self.to_prepare(*args, &block)
+      set_callback(:prepare, *args, &block)
+    end
+
+    def self.before_class_unload(*args, &block)
+      set_callback(:class_unload, *args, &block)
+    end
+
+    def self.after_class_unload(*args, &block)
+      set_callback(:class_unload, :after, *args, &block)
+    end
+
+    to_run(:after) { self.class.prepare! }
+
+    # Initiate a manual reload
+    def self.reload!
+      executor.wrap do
+        new.tap(&:run!).complete!
+      end
+      prepare!
+    end
+
+    def self.run! # :nodoc:
+      if check!
+        super
+      else
+        Null.run!
+      end
+    end
+
+    # Run the supplied block as a work unit, reloading code as needed
+    def self.wrap
+      executor.wrap do
+        super
+      end
+    end
+
+    class << self
+      attr_accessor :executor
+      attr_accessor :check
+    end
+    self.executor = Executor
+    self.check = lambda { false }
+
+    def self.check! # :nodoc:
+      @should_reload ||= check.call
+    end
+
+    def self.reloaded! # :nodoc:
+      @should_reload = false
+    end
+
+    def self.prepare! # :nodoc:
+      new.run_callbacks(:prepare)
+    end
+
+    def initialize
+      super
+      @locked = false
+    end
+
+    # Acquire the ActiveSupport::Dependencies::Interlock unload lock,
+    # ensuring it will be released automatically
+    def require_unload_lock!
+      unless @locked
+        ActiveSupport::Dependencies.interlock.start_unloading
+        @locked = true
+      end
+    end
+
+    # Release the unload lock if it has been previously obtained
+    def release_unload_lock!
+      if @locked
+        @locked = false
+        ActiveSupport::Dependencies.interlock.done_unloading
+      end
+    end
+
+    def run! # :nodoc:
+      super
+      release_unload_lock!
+    end
+
+    def class_unload!(&block) # :nodoc:
+      require_unload_lock!
+      run_callbacks(:class_unload, &block)
+    end
+
+    def complete! # :nodoc:
+      super
+      self.class.reloaded!
+    ensure
+      release_unload_lock!
+    end
+  end
+end
diff --git a/activesupport/test/executor_test.rb b/activesupport/test/executor_test.rb
new file mode 100644
index 0000000000..6db6db4fa8
--- /dev/null
+++ b/activesupport/test/executor_test.rb
@@ -0,0 +1,76 @@
+require 'abstract_unit'
+
+class ExecutorTest < ActiveSupport::TestCase
+  def test_wrap_invokes_callbacks
+    called = []
+    executor.to_run { called << :run }
+    executor.to_complete { called << :complete }
+
+    executor.wrap do
+      called << :body
+    end
+
+    assert_equal [:run, :body, :complete], called
+  end
+
+  def test_callbacks_share_state
+    result = false
+    executor.to_run { @foo = true }
+    executor.to_complete { result = @foo }
+
+    executor.wrap { }
+
+    assert result
+  end
+
+  def test_separated_calls_invoke_callbacks
+    called = []
+    executor.to_run { called << :run }
+    executor.to_complete { called << :complete }
+
+    state = executor.run!
+    called << :body
+    state.complete!
+
+    assert_equal [:run, :body, :complete], called
+  end
+
+  def test_avoids_double_wrapping
+    called = []
+    executor.to_run { called << :run }
+    executor.to_complete { called << :complete }
+
+    executor.wrap do
+      called << :early
+      executor.wrap do
+        called << :body
+      end
+      called << :late
+    end
+
+    assert_equal [:run, :early, :body, :late, :complete], called
+  end
+
+  def test_separate_classes_can_wrap
+    other_executor = Class.new(ActiveSupport::Executor)
+
+    called = []
+    executor.to_run { called << :run }
+    executor.to_complete { called << :complete }
+    other_executor.to_run { called << :other_run }
+    other_executor.to_complete { called << :other_complete }
+
+    executor.wrap do
+      other_executor.wrap do
+        called << :body
+      end
+    end
+
+    assert_equal [:run, :other_run, :body, :other_complete, :complete], called
+  end
+
+  private
+    def executor
+      @executor ||= Class.new(ActiveSupport::Executor)
+    end
+end
diff --git a/activesupport/test/reloader_test.rb b/activesupport/test/reloader_test.rb
new file mode 100644
index 0000000000..958cb49993
--- /dev/null
+++ b/activesupport/test/reloader_test.rb
@@ -0,0 +1,85 @@
+require 'abstract_unit'
+
+class ReloaderTest < ActiveSupport::TestCase
+  def test_prepare_callback
+    prepared = false
+    reloader.to_prepare { prepared = true }
+
+    assert !prepared
+    reloader.prepare!
+    assert prepared
+
+    prepared = false
+    reloader.wrap do
+      assert prepared
+      prepared = false
+    end
+    assert !prepared
+  end
+
+  def test_only_run_when_check_passes
+    r = new_reloader { true }
+    invoked = false
+    r.to_run { invoked = true }
+    r.wrap { }
+    assert invoked
+
+    r = new_reloader { false }
+    invoked = false
+    r.to_run { invoked = true }
+    r.wrap { }
+    assert !invoked
+  end
+
+  def test_full_reload_sequence
+    called = []
+    reloader.to_prepare { called << :prepare }
+    reloader.to_run { called << :reloader_run }
+    reloader.to_complete { called << :reloader_complete }
+    reloader.executor.to_run { called << :executor_run }
+    reloader.executor.to_complete { called << :executor_complete }
+
+    reloader.wrap { }
+    assert_equal [:executor_run, :reloader_run, :prepare, :reloader_complete, :executor_complete], called
+
+    called = []
+    reloader.reload!
+    assert_equal [:executor_run, :reloader_run, :prepare, :reloader_complete, :executor_complete, :prepare], called
+
+    reloader.check = lambda { false }
+
+    called = []
+    reloader.wrap { }
+    assert_equal [:executor_run, :executor_complete], called
+
+    called = []
+    reloader.reload!
+    assert_equal [:executor_run, :reloader_run, :prepare, :reloader_complete, :executor_complete, :prepare], called
+  end
+
+  def test_class_unload_block
+    called = []
+    reloader.before_class_unload { called << :before_unload }
+    reloader.after_class_unload { called << :after_unload }
+    reloader.to_run do
+      class_unload! do
+        called << :unload
+      end
+    end
+    reloader.wrap { called << :body }
+
+    assert_equal [:before_unload, :unload, :after_unload, :body], called
+  end
+
+  private
+    def new_reloader(&check)
+      Class.new(ActiveSupport::Reloader).tap do |r|
+        r.check = check
+        r.executor = Class.new(ActiveSupport::Executor)
+      end
+    end
+
+    def reloader
+      @reloader ||= new_reloader { true }
+    end
+end