zeitwerk 2.3.0

data/lib/zeitwerk/loader/callbacks.rb

@@ -0,0 +1,71 @@
+module Zeitwerk::Loader::Callbacks
+  include Zeitwerk::RealModName
+
+  # Invoked from our decorated Kernel#require when a managed file is autoloaded.
+  #
+  # @private
+  # @param file [String]
+  # @return [void]
+  def on_file_autoloaded(file)
+    cref = autoloads.delete(file)
+    to_unload[cpath(*cref)] = [file, cref] if reloading_enabled?
+    Zeitwerk::Registry.unregister_autoload(file)
+
+    if logger && cdef?(*cref)
+      log("constant #{cpath(*cref)} loaded from file #{file}")
+    elsif !cdef?(*cref)
+      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath(*cref)}, but didn't", cref.last)
+    end
+  end
+
+  # Invoked from our decorated Kernel#require when a managed directory is
+  # autoloaded.
+  #
+  # @private
+  # @param dir [String]
+  # @return [void]
+  def on_dir_autoloaded(dir)
+    # Module#autoload does not serialize concurrent requires, and we handle
+    # directories ourselves, so the callback needs to account for concurrency.
+    #
+    # Multi-threading would introduce a race condition here in which thread t1
+    # autovivifies the module, and while autoloads for its children are being
+    # set, thread t2 autoloads the same namespace.
+    #
+    # Without the mutex and subsequent delete call, t2 would reset the module.
+    # That not only would reassign the constant (undesirable per se) but, worse,
+    # the module object created by t2 wouldn't have any of the autoloads for its
+    # children, since t1 would have correctly deleted its lazy_subdirs entry.
+    mutex2.synchronize do
+      if cref = autoloads.delete(dir)
+        autovivified_module = cref[0].const_set(cref[1], Module.new)
+        log("module #{autovivified_module.name} autovivified from directory #{dir}") if logger
+
+        to_unload[autovivified_module.name] = [dir, cref] if reloading_enabled?
+
+        # We don't unregister `dir` in the registry because concurrent threads
+        # wouldn't find a loader associated to it in Kernel#require and would
+        # try to require the directory. Instead, we are going to keep track of
+        # these to be able to unregister later if eager loading.
+        autoloaded_dirs << dir
+
+        on_namespace_loaded(autovivified_module)
+      end
+    end
+  end
+
+  # Invoked when a class or module is created or reopened, either from the
+  # tracer or from module autovivification. If the namespace has matching
+  # subdirectories, we descend into them now.
+  #
+  # @private
+  # @param namespace [Module]
+  # @return [void]
+  def on_namespace_loaded(namespace)
+    if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
+      subdirs.each do |subdir|
+        set_autoloads_in_dir(subdir, namespace)
+      end
+    end
+  end
+end

data/lib/zeitwerk/real_mod_name.rb

@@ -0,0 +1,21 @@
+module Zeitwerk::RealModName
+  UNBOUND_METHOD_MODULE_NAME = Module.instance_method(:name)
+  private_constant :UNBOUND_METHOD_MODULE_NAME
+
+  # Returns the real name of the class or module, as set after the first
+  # constant to which it was assigned (or nil).
+  #
+  # The name method can be overridden, hence the indirection in this method.
+  #
+  # @param mod [Class, Module]
+  # @return [String, nil]
+  if UnboundMethod.method_defined?(:bind_call)
+    def real_mod_name(mod)
+      UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
+    end
+  else
+    def real_mod_name(mod)
+      UNBOUND_METHOD_MODULE_NAME.bind(mod).call
+    end
+  end
+end

data/lib/zeitwerk/registry.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  module Registry # :nodoc: all
+    class << self
+      # Keeps track of all loaders. Useful to broadcast messages and to prevent
+      # them from being garbage collected.
+      #
+      # @private
+      # @return [<Zeitwerk::Loader>]
+      attr_reader :loaders
+
+      # Registers loaders created with `for_gem` to make the method idempotent
+      # in case of reload.
+      #
+      # @private
+      # @return [{String => Zeitwerk::Loader}]
+      attr_reader :loaders_managing_gems
+
+      # Maps real paths to the loaders responsible for them.
+      #
+      # This information is used by our decorated `Kernel#require` to be able to
+      # invoke callbacks and autovivify modules.
+      #
+      # @private
+      # @return [{String => Zeitwerk::Loader}]
+      attr_reader :autoloads
+
+      # This hash table addresses an edge case in which an autoload is ignored.
+      #
+      # For example, let's suppose we want to autoload in a gem like this:
+      #
+      #   # lib/my_gem.rb
+      #   loader = Zeitwerk::Loader.new
+      #   loader.push_dir(__dir__)
+      #   loader.setup
+      #
+      #   module MyGem
+      #   end
+      #
+      # if you require "my_gem", as Bundler would do, this happens while setting
+      # up autoloads:
+      #
+      #   1. Object.autoload?(:MyGem) returns `nil` because the autoload for
+      #      the constant is issued by Zeitwerk while the same file is being
+      #      required.
+      #   2. The constant `MyGem` is undefined while setup runs.
+      #
+      # Therefore, a directory `lib/my_gem` would autovivify a module according to
+      # the existing information. But that would be wrong.
+      #
+      # To overcome this fundamental limitation, we keep track of the constant
+      # paths that are in this situation ---in the example above, "MyGem"--- and
+      # take this collection into account for the autovivification logic.
+      #
+      # Note that you cannot generally address this by moving the setup code
+      # below the constant definition, because we want libraries to be able to
+      # use managed constants in the module body:
+      #
+      #   module MyGem
+      #     include MyConcern
+      #   end
+      #
+      # @private
+      # @return [{String => (String, Zeitwerk::Loader)}]
+      attr_reader :inceptions
+
+      # Registers a loader.
+      #
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      # @return [void]
+      def register_loader(loader)
+        loaders << loader
+      end
+
+      # This method returns always a loader, the same instance for the same root
+      # file. That is how Zeitwerk::Loader.for_gem is idempotent.
+      #
+      # @private
+      # @param root_file [String]
+      # @return [Zeitwerk::Loader]
+      def loader_for_gem(root_file)
+        loaders_managing_gems[root_file] ||= begin
+          Loader.new.tap do |loader|
+            loader.tag = File.basename(root_file, ".rb")
+            loader.inflector = GemInflector.new(root_file)
+            loader.push_dir(File.dirname(root_file))
+          end
+        end
+      end
+
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      # @param realpath [String]
+      # @return [void]
+      def register_autoload(loader, realpath)
+        autoloads[realpath] = loader
+      end
+
+      # @private
+      # @param realpath [String]
+      # @return [void]
+      def unregister_autoload(realpath)
+        autoloads.delete(realpath)
+      end
+
+      # @private
+      # @param cpath [String]
+      # @param realpath [String]
+      # @param loader [Zeitwerk::Loader]
+      # @return [void]
+      def register_inception(cpath, realpath, loader)
+        inceptions[cpath] = [realpath, loader]
+      end
+
+      # @private
+      # @param cpath [String]
+      # @return [String, nil]
+      def inception?(cpath)
+        if pair = inceptions[cpath]
+          pair.first
+        end
+      end
+
+      # @private
+      # @param path [String]
+      # @return [Zeitwerk::Loader, nil]
+      def loader_for(path)
+        autoloads[path]
+      end
+
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      # @return [void]
+      def on_unload(loader)
+        autoloads.delete_if { |_path, object| object == loader }
+        inceptions.delete_if { |_cpath, (_path, object)| object == loader }
+      end
+    end
+
+    @loaders               = []
+    @loaders_managing_gems = {}
+    @autoloads             = {}
+    @inceptions            = {}
+  end
+end

data/lib/zeitwerk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  VERSION = "2.3.0"
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: zeitwerk
+version: !ruby/object:Gem::Version
+  version: 2.3.0
+platform: ruby
+authors:
+- Xavier Noria
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-03-03 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      Zeitwerk implements constant autoloading with Ruby semantics. Each gem
+      and application may have their own independent autoloader, with its own
+      configuration, inflector, and logger. Supports autoloading, preloading,
+      reloading, and eager loading.
+email: fxn@hashref.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/zeitwerk.rb
+- lib/zeitwerk/error.rb
+- lib/zeitwerk/explicit_namespace.rb
+- lib/zeitwerk/gem_inflector.rb
+- lib/zeitwerk/inflector.rb
+- lib/zeitwerk/kernel.rb
+- lib/zeitwerk/loader.rb
+- lib/zeitwerk/loader/callbacks.rb
+- lib/zeitwerk/real_mod_name.rb
+- lib/zeitwerk/registry.rb
+- lib/zeitwerk/version.rb
+homepage: https://github.com/fxn/zeitwerk
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Efficient and thread-safe constant autoloader
+test_files: []