zeitwerk 2.7.2 → 2.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a07f90eb2f155582d05f58527ffcbc2f4d76c9a1983260ca8d527becaeb7972
-  data.tar.gz: 65e8dc78ca8e6de674f0fc7d88aad5c9bad0d7687bc9ed26f93d6fa0e6d18e90
+  metadata.gz: 1500c4f54c6ac7e64eef74c8702682764fa845533a5b16c67a48ee11781ef3e0
+  data.tar.gz: f7201576b8b59ab3786cd4bc6fd58f3cd3afa3d8dcc1e86477121000f06ac50a
 SHA512:
-  metadata.gz: d7b9d13e3d3d5bf0497ec259bf0817256586e245f7d47c951b8392784f715bc71c20d0ec3c9e465077da6d8e729ca6888fbaaa24820fe4459771e29340ee6d05
-  data.tar.gz: 8b1322d36bc9115a56b6abab6be9549c868e0edd2025fe82dd2c5d0abb082fac8532c82ed03f895d34f2875f27b160f4861185112c4aef2a3129e46569115c0f
+  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,17 +1,17 @@
 # frozen_string_literal: true
 
 module Zeitwerk::ConstAdded # :nodoc:
-  # @sig (Symbol) -> void
+  #: (Symbol) -> void
   def const_added(cname)
-    if loader = Zeitwerk::Registry::ExplicitNamespaces.__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} is expected to be a namespace, should be a class or module (got #{namespace.class})"
       end
 
-      loader.__on_namespace_loaded(Zeitwerk::Cref.new(self, cname), namespace)
+      loader.__on_namespace_loaded(cref, namespace)
     end
     super
   end

data/lib/zeitwerk/cref/map.rb

@@ -1,11 +1,18 @@
 # 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 (see why below). Then, each one of them stores a hash table keyed on
-# constant names as symbols. We finally store the values in those.
+# 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:
@@ -14,36 +21,64 @@
 #
 # This structure is internal, so only the needed interface is implemented.
 #
-# Why not use tables that map pairs [Module, Symbol] to their values? Because
-# class and module objects are not guaranteed to be hashable, the `hash` method
-# may have been overridden:
+# 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.
 #
-#   https://github.com/fxn/zeitwerk/issues/188
+#  2. Write a custom `hash`/`eql?` in Zeitwerk::Cref. Hash code would be
 #
-# We can also use a 1-level hash whose keys are the corresponding class and
-# module names. In the example above it would be:
+#       real_mod_hash(@mod) ^ @cname.hash
 #
-#   { "M::X" => 0, "M::Y" => 1, "N::Z" => 2 }
+#     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.
 #
-# The gem used this approach for several years.
+#  3. Similar to 2, but use
 #
-# Another option would be to make crefs hashable. I tried with hash code
+#       @mod.object_id ^ @cname.object_id
 #
-#   real_mod_hash(mod) ^ cname.hash
+#     as hash code instead.
 #
-# and the matching eql?, but that was about 1.8x slower.
+# Benchamrks
+# ----------
 #
-# Finally, I came with this solution which is 1.6x faster than the previous one
-# based on class and module names, even being synchronized. Also, client code
-# feels natural, since crefs are central objects in Zeitwerk's implementation.
+# 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
 
-  # @sig (Zeitwerk::Cref, V) -> V
+  #: (Zeitwerk::Cref, Value) -> Value
   def []=(cref, value)
     @mutex.synchronize do
       cnames = (@map[cref.mod] ||= {})
@@ -51,14 +86,14 @@ class Zeitwerk::Cref::Map # :nodoc: all
     end
   end
 
-  # @sig (Zeitwerk::Cref) -> top?
+  #: (Zeitwerk::Cref) -> Value?
   def [](cref)
     @mutex.synchronize do
       @map[cref.mod]&.[](cref.cname)
     end
   end
 
-  # @sig (Zeitwerk::Cref, { () -> V }) -> V
+  #: (Zeitwerk::Cref, { () -> Value }) -> Value
   def get_or_set(cref, &block)
     @mutex.synchronize do
       cnames = (@map[cref.mod] ||= {})
@@ -66,7 +101,7 @@ class Zeitwerk::Cref::Map # :nodoc: all
     end
   end
 
-  # @sig (Zeitwerk::Cref) -> top?
+  #: (Zeitwerk::Cref) -> Value?
   def delete(cref)
     delete_mod_cname(cref.mod, cref.cname)
   end
@@ -74,7 +109,7 @@ class Zeitwerk::Cref::Map # :nodoc: all
   # 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.
   #
-  # @sig (Module, Symbol) -> top?
+  #: (Module, Symbol) -> Value?
   def delete_mod_cname(mod, cname)
     @mutex.synchronize do
       if cnames = @map[mod]
@@ -85,7 +120,7 @@ class Zeitwerk::Cref::Map # :nodoc: all
     end
   end
 
-  # @sig (top) -> void
+  #: (Value) -> void
   def delete_by_value(value)
     @mutex.synchronize do
       @map.delete_if do |mod, cnames|
@@ -97,7 +132,7 @@ class Zeitwerk::Cref::Map # :nodoc: all
 
   # Order of yielded crefs is undefined.
   #
-  # @sig () { (Zeitwerk::Cref) -> void } -> void
+  #: () { (Zeitwerk::Cref) -> void } -> void
   def each_key
     @mutex.synchronize do
       @map.each do |mod, cnames|
@@ -108,14 +143,14 @@ class Zeitwerk::Cref::Map # :nodoc: all
     end
   end
 
-  # @sig () -> void
+  #: () -> void
   def clear
     @mutex.synchronize do
       @map.clear
     end
   end
 
-  # @sig () -> bool
+  #: () -> bool
   def empty? # for tests
     @mutex.synchronize do
       @map.empty?

data/lib/zeitwerk/cref.rb

@@ -2,69 +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. 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 (top) -> top
+  #: (top) -> top
   def set(value)
     @mod.const_set(@cname, value)
   end
 
-  # @raise [NameError]
-  # @sig () -> top
+  #: () -> 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,7 +2,7 @@
 
 # This is a private module.
 module Zeitwerk::Internal
-  # @sig (Symbol) -> void
+  #: (Symbol) -> void
   def internal(method_name)
     private method_name
 

data/lib/zeitwerk/loader/callbacks.rb

@@ -5,12 +5,11 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
 
   # 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} loaded from file #{file}") if logger
@@ -36,7 +35,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
   # 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
@@ -53,8 +52,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
     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[dir] = cref if reloading_enabled?
 
@@ -66,7 +64,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
 
         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
@@ -75,7 +73,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
   # autovivification. If the namespace has matching subdirectories, we descend
   # into them now.
   #
-  # @sig (Zeitwerk::Cref, Module) -> void
+  #: (Zeitwerk::Cref, Module) -> void
   internal def on_namespace_loaded(cref, namespace)
     if dirs = namespace_dirs.delete(cref)
       dirs.each do |dir|
@@ -86,7 +84,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
 
   private
 
-  # @sig (String, top, String) -> 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)