zeitwerk 2.7.1 → 2.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aba46812169c8e26085b099c708093b00a29bfd39e8d8210d29bc99e7df0e7fa
-  data.tar.gz: 0fc20386009d52d21a0cb79a64c5d800f7aecfce5a38e8430a10dc5d04c2609d
+  metadata.gz: 1500c4f54c6ac7e64eef74c8702682764fa845533a5b16c67a48ee11781ef3e0
+  data.tar.gz: f7201576b8b59ab3786cd4bc6fd58f3cd3afa3d8dcc1e86477121000f06ac50a
 SHA512:
-  metadata.gz: 3edac5ad6f940caa70c4cac093bf271b8399b078d7124f450513c963ec5099e9b9082841ceb9893b81f1edf8e34dc642ec811403415fb230211670c63a950766
-  data.tar.gz: 47339a8b35dc06108fde9aadd62e83b1ea4e4ef22854c31849069f09ece1115dce07d63ec354fe96fbc599bba411ecff48db6a8b0c8b150ad7ee016787e9d75c
+  metadata.gz: ab113d90c9a42ec5c75c6ebe68ab5a04395f1b33228de42de6952f2e673a329f30de85477977ec11d582df82f40c4dc5c08e8ba2305f46a6d07ac4e88c564887
+  data.tar.gz: 73fb9dc78a9a7148119b306f93a513f841e4888d421fbf178963bbfa1368a8c7c66cd8661a28e8d95d14f51dab16fb4ff886f23183ec13a74847c45c1850f30d

data/lib/zeitwerk/core_ext/kernel.rb

@@ -19,9 +19,9 @@ module Kernel
     alias_method :zeitwerk_original_require, :require
   end
 
-  # @sig (String) -> true | false
+  #: (String) -> bool
   def require(path)
-    if loader = Zeitwerk::Registry.loader_for(path)
+    if loader = Zeitwerk::Registry.autoloads.registered?(path)
       if path.end_with?(".rb")
         required = zeitwerk_original_require(path)
         loader.__on_file_autoloaded(path) if required
@@ -34,7 +34,7 @@ module Kernel
       required = zeitwerk_original_require(path)
       if required
         abspath = $LOADED_FEATURES.last
-        if loader = Zeitwerk::Registry.loader_for(abspath)
+        if loader = Zeitwerk::Registry.autoloads.registered?(abspath)
           loader.__on_file_autoloaded(abspath)
         end
       end

data/lib/zeitwerk/core_ext/module.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-module Zeitwerk::ConstAdded
+module Zeitwerk::ConstAdded # :nodoc:
+  #: (Symbol) -> void
   def const_added(cname)
-    if loader = Zeitwerk::ExplicitNamespace.__loader_for(self, cname)
+    if loader = Zeitwerk::Registry.explicit_namespaces.loader_for(self, cname)
       namespace = const_get(cname, false)
+      cref = Zeitwerk::Cref.new(self, cname)
 
       unless namespace.is_a?(Module)
-        cref = Zeitwerk::Cref.new(self, cname)
-        raise Zeitwerk::Error, "#{cref.path} is expected to be a namespace, should be a class or module (got #{namespace.class})"
+        raise Zeitwerk::Error, "#{cref} is expected to be a namespace, should be a class or module (got #{namespace.class})"
       end
 
-      loader.on_namespace_loaded(namespace)
+      loader.__on_namespace_loaded(cref, namespace)
     end
     super
   end

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

@@ -2,66 +2,67 @@
 
 # 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 that encapsulates the constants API. Examples:
+# 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.
+# The constant may or may not exist in `mod`.
 class Zeitwerk::Cref
+  require_relative "cref/map"
+
   include Zeitwerk::RealModName
 
-  # @sig Module
+  #: Module
   attr_reader :mod
 
-  # @sig Symbol
+  #: Symbol
   attr_reader :cname
 
   # The type of the first argument is Module because Class < Module, class
   # objects are also valid.
   #
-  # @sig (Module, Symbol) -> void
+  #: (Module, Symbol) -> void
   def initialize(mod, cname)
     @mod   = mod
     @cname = cname
     @path  = nil
   end
 
-  # @sig () -> String
+  #: () -> String
   def path
-    @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
+    @path ||= Object == @mod ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
   end
+  alias to_s path
 
-  # @sig () -> String?
+  #: () -> String?
   def autoload?
     @mod.autoload?(@cname, false)
   end
 
-  # @sig (String) -> bool
+  #: (String) -> nil
   def autoload(abspath)
     @mod.autoload(@cname, abspath)
   end
 
-  # @sig () -> bool
+  #: () -> bool
   def defined?
     @mod.const_defined?(@cname, false)
   end
 
-  # @sig (Object) -> Object
+  #: (top) -> top
   def set(value)
     @mod.const_set(@cname, value)
   end
 
-  # @raise [NameError]
-  # @sig () -> Object
+  #: () -> top ! NameError
   def get
     @mod.const_get(@cname, false)
   end
 
-  # @raise [NameError]
-  # @sig () -> void
+  #: () -> void ! NameError
   def remove
     @mod.__send__(:remove_const, @cname)
   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")
       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

@@ -10,12 +10,12 @@ module Zeitwerk
     private_class_method :new
 
     # @private
-    # @sig (String, bool) -> Zeitwerk::GemLoader
+    #: (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
+    #: (String, namespace: Module, warn_on_extra_files: boolish) -> void
     def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
@@ -30,7 +30,7 @@ module Zeitwerk
       push_dir(@root_dir, namespace: namespace)
     end
 
-    # @sig () -> void
+    #: () -> void
     def setup
       warn_on_extra_files if @warn_on_extra_files
       super
@@ -38,7 +38,7 @@ module Zeitwerk
 
     private
 
-    # @sig () -> void
+    #: () -> void
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 

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,24 +1,22 @@
 # 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.
   #
-  # @raise [Zeitwerk::NameError]
-  # @sig (String) -> void
+  #: (String) -> void ! Zeitwerk::NameError
   internal def on_file_autoloaded(file)
     cref = autoloads.delete(file)
 
-    Zeitwerk::Registry.unregister_autoload(file)
+    Zeitwerk::Registry.autoloads.unregister(file)
 
     if cref.defined?
-      log("constant #{cref.path} loaded from file #{file}") if logger
-      to_unload[cref.path] = [file, cref] if reloading_enabled?
+      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 #{cref.path}, but didn't"
+      msg = "expected file #{file} to define constant #{cref}, but didn't"
       log(msg) if logger
 
       # Ruby still keeps the autoload defined, but we remove it because the
@@ -28,7 +26,7 @@ module Zeitwerk::Loader::Callbacks
       # 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[cref.path] = [file, cref] if reloading_enabled?
+      to_unload[file] = cref if reloading_enabled?
 
       raise Zeitwerk::NameError.new(msg, cref.cname)
     end
@@ -37,7 +35,7 @@ module Zeitwerk::Loader::Callbacks
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
-  # @sig (String) -> void
+  #: (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
@@ -54,10 +52,9 @@ module Zeitwerk::Loader::Callbacks
     dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
         implicit_namespace = cref.set(Module.new)
-        cpath = implicit_namespace.name
-        log("module #{cpath} autovivified from directory #{dir}") if logger
+        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
@@ -65,21 +62,20 @@ module Zeitwerk::Loader::Callbacks
         # these to be able to unregister later if eager loading.
         autoloaded_dirs << dir
 
-        on_namespace_loaded(implicit_namespace)
+        on_namespace_loaded(cref, implicit_namespace)
 
-        run_on_load_callbacks(cpath, implicit_namespace, 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
-  # const_added 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|
         define_autoloads_for_dir(dir, namespace)
       end
@@ -88,7 +84,7 @@ module Zeitwerk::Loader::Callbacks
 
   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)