zeitwerk 2.6.7 → 2.7.3

data/lib/zeitwerk/cref/map.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Description of the structure
+# ----------------------------
+#
+# This class emulates a hash table whose keys are of type Zeitwerk::Cref.
+#
+# It is a synchronized 2-level hash.
+#
+# The keys of the top one, stored in `@map`, are class and module objects, but
+# their hash code is forced to be their object IDs because class and module
+# objects may not be hashable (https://github.com/fxn/zeitwerk/issues/188).
+#
+# Then, each one of them stores a hash table with their constants and values.
+# Constants are stored as symbols.
+#
+# For example, if we store values 0, 1, and 2 for the crefs that would
+# correspond to `M::X`, `M::Y`, and `N::Z`, the map will look like this:
+#
+#   { M => { X: 0, :Y => 1 }, N => { Z: 2 } }
+#
+# This structure is internal, so only the needed interface is implemented.
+#
+# Alternative approaches
+# -----------------------
+#
+# 1. We could also use a 1-level hash whose keys are constant paths. In the
+#    example above it would be:
+#
+#      { "M::X" => 0, "M::Y" => 1, "N::Z" => 2 }
+#
+#    The gem used this approach for several years.
+#
+#  2. Write a custom `hash`/`eql?` in Zeitwerk::Cref. Hash code would be
+#
+#       real_mod_hash(@mod) ^ @cname.hash
+#
+#     where `real_mod_hash(@mod)` would actually be a call to the real `hash`
+#     method in Module. Like what we do for module names to bypass overrides.
+#
+#  3. Similar to 2, but use
+#
+#       @mod.object_id ^ @cname.object_id
+#
+#     as hash code instead.
+#
+# Benchamrks
+# ----------
+#
+# Writing:
+#
+#   map - baseline
+#   (3) - 1.74x  slower
+#   (2) - 2.91x  slower
+#   (1) - 3.87x  slower
+#
+# Reading:
+#
+#   map - baseline
+#   (3) - 1.99x  slower
+#   (2) - 2.80x  slower
+#   (1) - 3.48x  slower
+#
+# Extra ball
+# ----------
+#
+# In addition to that, the map is synchronized and provides `delete_mod_cname`,
+# which is ad-hoc for the hot path in `const_added`, we do not need to create
+# unnecessary cref objects for constants we do not manage (but we do not know in
+# advance there).
+
+#: [Value]
+class Zeitwerk::Cref::Map # :nodoc: all
+  #: () -> void
+  def initialize
+    @map = {}
+    @map.compare_by_identity
+    @mutex = Mutex.new
+  end
+
+  #: (Zeitwerk::Cref, Value) -> Value
+  def []=(cref, value)
+    @mutex.synchronize do
+      cnames = (@map[cref.mod] ||= {})
+      cnames[cref.cname] = value
+    end
+  end
+
+  #: (Zeitwerk::Cref) -> Value?
+  def [](cref)
+    @mutex.synchronize do
+      @map[cref.mod]&.[](cref.cname)
+    end
+  end
+
+  #: (Zeitwerk::Cref, { () -> Value }) -> Value
+  def get_or_set(cref, &block)
+    @mutex.synchronize do
+      cnames = (@map[cref.mod] ||= {})
+      cnames.fetch(cref.cname) { cnames[cref.cname] = block.call }
+    end
+  end
+
+  #: (Zeitwerk::Cref) -> Value?
+  def delete(cref)
+    delete_mod_cname(cref.mod, cref.cname)
+  end
+
+  # Ad-hoc for loader_for, called from const_added. That is a hot path, I prefer
+  # to not create a cref in every call, since that is global.
+  #
+  #: (Module, Symbol) -> Value?
+  def delete_mod_cname(mod, cname)
+    @mutex.synchronize do
+      if cnames = @map[mod]
+        value = cnames.delete(cname)
+        @map.delete(mod) if cnames.empty?
+        value
+      end
+    end
+  end
+
+  #: (Value) -> void
+  def delete_by_value(value)
+    @mutex.synchronize do
+      @map.delete_if do |mod, cnames|
+        cnames.delete_if { _2 == value }
+        cnames.empty?
+      end
+    end
+  end
+
+  # Order of yielded crefs is undefined.
+  #
+  #: () { (Zeitwerk::Cref) -> void } -> void
+  def each_key
+    @mutex.synchronize do
+      @map.each do |mod, cnames|
+        cnames.each_key do |cname|
+          yield Zeitwerk::Cref.new(mod, cname)
+        end
+      end
+    end
+  end
+
+  #: () -> void
+  def clear
+    @mutex.synchronize do
+      @map.clear
+    end
+  end
+
+  #: () -> bool
+  def empty? # for tests
+    @mutex.synchronize do
+      @map.empty?
+    end
+  end
+end

data/lib/zeitwerk/cref.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# This private class encapsulates pairs (mod, cname).
+#
+# Objects represent the constant `cname` in the class or module object `mod`,
+# and have API to manage them. Examples:
+#
+#   cref.path
+#   cref.set(value)
+#   cref.get
+#
+# The constant may or may not exist in `mod`.
+class Zeitwerk::Cref
+  require_relative "cref/map"
+
+  include Zeitwerk::RealModName
+
+  #: Module
+  attr_reader :mod
+
+  #: Symbol
+  attr_reader :cname
+
+  # The type of the first argument is Module because Class < Module, class
+  # objects are also valid.
+  #
+  #: (Module, Symbol) -> void
+  def initialize(mod, cname)
+    @mod   = mod
+    @cname = cname
+    @path  = nil
+  end
+
+  #: () -> String
+  def path
+    @path ||= Object == @mod ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
+  end
+  alias to_s path
+
+  #: () -> String?
+  def autoload?
+    @mod.autoload?(@cname, false)
+  end
+
+  #: (String) -> nil
+  def autoload(abspath)
+    @mod.autoload(@cname, abspath)
+  end
+
+  #: () -> bool
+  def defined?
+    @mod.const_defined?(@cname, false)
+  end
+
+  #: (top) -> top
+  def set(value)
+    @mod.const_set(@cname, value)
+  end
+
+  #: () -> top ! NameError
+  def get
+    @mod.const_get(@cname, false)
+  end
+
+  #: () -> void ! NameError
+  def remove
+    @mod.__send__(:remove_const, @cname)
+  end
+end

data/lib/zeitwerk/error.rb

@@ -5,6 +5,7 @@ module Zeitwerk
   end
 
   class ReloadingDisabledError < Error
+    #: () -> void
     def initialize
       super("can't reload, please call loader.enable_reloading before setup")
     end
@@ -14,6 +15,7 @@ module Zeitwerk
   end
 
   class SetupRequired < Error
+    #: () -> void
     def initialize
       super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
     end

data/lib/zeitwerk/gem_inflector.rb

@@ -2,14 +2,14 @@
 
 module Zeitwerk
   class GemInflector < Inflector
-    # @sig (String) -> void
+    #: (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
-      lib_dir       = File.dirname(root_file)
-      @version_file = File.join(lib_dir, namespace, "version.rb")
+      root_dir      = File.dirname(root_file)
+      @version_file = File.join(root_dir, namespace, "version.rb")
     end
 
-    # @sig (String, String) -> String
+    #: (String, String) -> String
     def camelize(basename, abspath)
       abspath == @version_file ? "VERSION" : super
     end

data/lib/zeitwerk/gem_loader.rb

@@ -3,30 +3,34 @@
 module Zeitwerk
   # @private
   class GemLoader < Loader
+    include RealModName
+
     # Users should not create instances directly, the public interface is
     # `Zeitwerk::Loader.for_gem`.
     private_class_method :new
 
     # @private
-    # @sig (String, bool) -> Zeitwerk::GemLoader
-    def self._new(root_file, warn_on_extra_files:)
-      new(root_file, warn_on_extra_files: warn_on_extra_files)
+    #: (String, namespace: Module, warn_on_extra_files: boolish) -> Zeitwerk::GemLoader
+    def self.__new(root_file, namespace:, warn_on_extra_files:)
+      new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
     end
 
-    # @sig (String, bool) -> void
-    def initialize(root_file, warn_on_extra_files:)
+    #: (String, namespace: Module, warn_on_extra_files: boolish) -> void
+    def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
-      @tag                 = File.basename(root_file, ".rb")
+      @tag = File.basename(root_file, ".rb")
+      @tag = real_mod_name(namespace) + "-" + @tag unless namespace.equal?(Object)
+
       @inflector           = GemInflector.new(root_file)
       @root_file           = File.expand_path(root_file)
-      @lib                 = File.dirname(root_file)
+      @root_dir            = File.dirname(root_file)
       @warn_on_extra_files = warn_on_extra_files
 
-      push_dir(@lib)
+      push_dir(@root_dir, namespace: namespace)
     end
 
-    # @sig () -> void
+    #: () -> void
     def setup
       warn_on_extra_files if @warn_on_extra_files
       super
@@ -34,17 +38,16 @@ module Zeitwerk
 
     private
 
-    # @sig () -> void
+    #: () -> void
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@lib) do |basename, abspath|
+      ls(@root_dir) do |basename, abspath, ftype|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 
         basename_without_ext = basename.delete_suffix(".rb")
         cname = inflector.camelize(basename_without_ext, abspath).to_sym
-        ftype = dir?(abspath) ? "directory" : "file"
 
         warn(<<~EOS)
           WARNING: Zeitwerk defines the constant #{cname} after the #{ftype}

data/lib/zeitwerk/inflector.rb

@@ -11,7 +11,7 @@ module Zeitwerk
     #
     # Takes into account hard-coded mappings configured with `inflect`.
     #
-    # @sig (String, String) -> String
+    #: (String, String) -> String
     def camelize(basename, _abspath)
       overrides[basename] || basename.split('_').each(&:capitalize!).join
     end
@@ -28,7 +28,7 @@ module Zeitwerk
     #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
     #   inflector.camelize("users_controller", abspath) # => "UsersController"
     #
-    # @sig (Hash[String, String]) -> void
+    #: (Hash[String, String]) -> void
     def inflect(inflections)
       overrides.merge!(inflections)
     end
@@ -38,7 +38,7 @@ module Zeitwerk
     # Hard-coded basename to constant name user maps that override the default
     # inflection logic.
     #
-    # @sig () -> Hash[String, String]
+    #: () -> Hash[String, String]
     def overrides
       @overrides ||= {}
     end

data/lib/zeitwerk/internal.rb

@@ -2,6 +2,7 @@
 
 # This is a private module.
 module Zeitwerk::Internal
+  #: (Symbol) -> void
   def internal(method_name)
     private method_name
 

data/lib/zeitwerk/loader/callbacks.rb

@@ -1,39 +1,45 @@
 # frozen_string_literal: true
 
-module Zeitwerk::Loader::Callbacks
-  include Zeitwerk::RealModName
+module Zeitwerk::Loader::Callbacks # :nodoc: all
+  extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @private
-  # @sig (String) -> void
-  def on_file_autoloaded(file)
-    cref  = autoloads.delete(file)
-    cpath = cpath(*cref)
-
-    Zeitwerk::Registry.unregister_autoload(file)
-
-    if cdef?(*cref)
-      log("constant #{cpath} loaded from file #{file}") if logger
-      to_unload[cpath] = [file, cref] if reloading_enabled?
-      run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
+  #: (String) -> void ! Zeitwerk::NameError
+  internal def on_file_autoloaded(file)
+    cref = autoloads.delete(file)
+
+    Zeitwerk::Registry.autoloads.unregister(file)
+
+    if cref.defined?
+      log("constant #{cref} loaded from file #{file}") if logger
+      to_unload[file] = cref if reloading_enabled?
+      run_on_load_callbacks(cref.path, cref.get, file) unless on_load_callbacks.empty?
     else
-      msg = "expected file #{file} to define constant #{cpath}, but didn't"
+      msg = "expected file #{file} to define constant #{cref}, but didn't"
       log(msg) if logger
-      crem(*cref)
-      to_unload[cpath] = [file, cref] if reloading_enabled?
-      raise Zeitwerk::NameError.new(msg, cref.last)
+
+      # Ruby still keeps the autoload defined, but we remove it because the
+      # contract in Zeitwerk is more strict.
+      cref.remove
+
+      # Since the expected constant was not defined, there is nothing to unload.
+      # However, if the exception is rescued and reloading is enabled, we still
+      # need to deleted the file from $LOADED_FEATURES.
+      to_unload[file] = cref if reloading_enabled?
+
+      raise Zeitwerk::NameError.new(msg, cref.cname)
     end
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
-  # @private
-  # @sig (String) -> 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.
+  #: (String) -> void
+  internal def on_dir_autoloaded(dir)
+    # Module#autoload does not serialize concurrent requires in CRuby < 3.2, and
+    # we handle directories ourselves without going through Kernel#require, 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
@@ -43,13 +49,12 @@ module Zeitwerk::Loader::Callbacks
     # 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 namespace_dirs entry.
-    mutex2.synchronize do
+    dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
-        autovivified_module = cref[0].const_set(cref[1], Module.new)
-        cpath = autovivified_module.name
-        log("module #{cpath} autovivified from directory #{dir}") if logger
+        implicit_namespace = cref.set(Module.new)
+        log("module #{cref} autovivified from directory #{dir}") if logger
 
-        to_unload[cpath] = [dir, cref] if reloading_enabled?
+        to_unload[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
@@ -57,30 +62,29 @@ module Zeitwerk::Loader::Callbacks
         # these to be able to unregister later if eager loading.
         autoloaded_dirs << dir
 
-        on_namespace_loaded(autovivified_module)
+        on_namespace_loaded(cref, implicit_namespace)
 
-        run_on_load_callbacks(cpath, autovivified_module, dir) unless on_load_callbacks.empty?
+        run_on_load_callbacks(cref.path, implicit_namespace, dir) unless on_load_callbacks.empty?
       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.
+  # Invoked when a namespace is created, either from const_added or from module
+  # autovivification. If the namespace has matching subdirectories, we descend
+  # into them now.
   #
-  # @private
-  # @sig (Module) -> void
-  def on_namespace_loaded(namespace)
-    if dirs = namespace_dirs.delete(real_mod_name(namespace))
+  #: (Zeitwerk::Cref, Module) -> void
+  internal def on_namespace_loaded(cref, namespace)
+    if dirs = namespace_dirs.delete(cref)
       dirs.each do |dir|
-        set_autoloads_in_dir(dir, namespace)
+        define_autoloads_for_dir(dir, namespace)
       end
     end
   end
 
   private
 
-  # @sig (String, Object) -> void
+  #: (String, top, String) -> void
   def run_on_load_callbacks(cpath, value, abspath)
     # Order matters. If present, run the most specific one.
     callbacks = reloading_enabled? ? on_load_callbacks[cpath] : on_load_callbacks.delete(cpath)