zeitwerk 1.4.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cb6bd7dd37980b33d67ae3b1a8b5a8228911dd833698617991f6026b06a122c
-  data.tar.gz: 8a9d2438c2008c5c04f21692d1dea9dd0cd7756eb3cd4460262866b1b9eda42f
+  metadata.gz: 5d964999444d0bc99d003d604cb2634d2753c579a4aebcce4fccb4c9ded78530
+  data.tar.gz: 95fc0030faf0472c8359c3665a09fa68dc3c79bff1d813e55d0f03f68c6f5282
 SHA512:
-  metadata.gz: aa2bfe23d1b4c3dde4f6df132c0e6bfb908e540cdc76177cc676fdd7d6843bd6b9af4032978f9948c46c1b74e1979ee592028cafba02fa25f3bdd5eaec0a3d67
-  data.tar.gz: ba5301619afb7d13dd1081330826b06c5bf6a8d520f56aa788423f14fcc2854c70cc9e8d5db7abec9733e05bc7ac3f6e8c7852f4563359abbcc46e5171f96371
+  metadata.gz: 81f2ac76566c1cda996eeac723fa7579dba24011f32fab94458ced0faf5eb7fe920ee2e016ce45ec83fc0d7b17244a1bf98764d71e667cbe067fa8ee87f01ca3
+  data.tar.gz: a90efd80c7caba53d6ec12bc20ee1a76f8d49a6a2e59a82b60a646486eac758348ff1250eee42585dbb2294718a41d59d97c9254ee51b802cddd1ce7add46ead

data/README.md

@@ -7,34 +7,33 @@
 
 <!-- TOC -->
 
-- [Zeitwerk](#zeitwerk)
-    - [Introduction](#introduction)
-    - [Synopsis](#synopsis)
-    - [File structure](#file-structure)
-        - [Implicit namespaces](#implicit-namespaces)
-        - [Explicit namespaces](#explicit-namespaces)
-        - [Nested root directories](#nested-root-directories)
-    - [Usage](#usage)
-        - [Setup](#setup)
-        - [Reloading](#reloading)
-        - [Eager loading](#eager-loading)
-        - [Preloading](#preloading)
-        - [Inflection](#inflection)
-            - [Zeitwerk::Inflector](#zeitwerkinflector)
-            - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
-            - [Custom inflector](#custom-inflector)
-        - [Logging](#logging)
-            - [Loader tag](#loader-tag)
-        - [Ignoring parts of the project](#ignoring-parts-of-the-project)
-            - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
-            - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
-            - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
-        - [Edge cases](#edge-cases)
-    - [Pronunciation](#pronunciation)
-    - [Supported Ruby versions](#supported-ruby-versions)
-    - [Motivation](#motivation)
-    - [Thanks](#thanks)
-    - [License](#license)
+- [Introduction](#introduction)
+- [Synopsis](#synopsis)
+- [File structure](#file-structure)
+    - [Implicit namespaces](#implicit-namespaces)
+    - [Explicit namespaces](#explicit-namespaces)
+    - [Nested root directories](#nested-root-directories)
+- [Usage](#usage)
+    - [Setup](#setup)
+    - [Reloading](#reloading)
+    - [Eager loading](#eager-loading)
+    - [Preloading](#preloading)
+    - [Inflection](#inflection)
+        - [Zeitwerk::Inflector](#zeitwerkinflector)
+        - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
+        - [Custom inflector](#custom-inflector)
+    - [Logging](#logging)
+        - [Loader tag](#loader-tag)
+    - [Ignoring parts of the project](#ignoring-parts-of-the-project)
+        - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
+        - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
+        - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
+    - [Edge cases](#edge-cases)
+- [Pronunciation](#pronunciation)
+- [Supported Ruby versions](#supported-ruby-versions)
+- [Motivation](#motivation)
+- [Thanks](#thanks)
+- [License](#license)
 
 <!-- /TOC -->
 
@@ -79,13 +78,18 @@ loader.setup # ready!
 
 The `loader` variable can go out of scope. Zeitwerk keeps a registry with all of them, and so the object won't be garbage collected.
 
-Later, you can reload if you want to:
+You can reload if you want to:
 
 ```ruby
+loader = Zeitwerk::Loader.new
+loader.push_dir(...)
+loader.enable_reloading # you need to opt-in before setup
+loader.setup
+...
 loader.reload
 ```
 
-and you can also eager load all the code:
+and you can eager load all the code:
 
 ```ruby
 loader.eager_load
@@ -192,17 +196,26 @@ Zeitwerk works internally only with absolute paths to avoid costly file searches
 
 ### Reloading
 
-In order to reload code:
+Zeitwer is able to reload code, but you need to enable this feature:
 
 ```ruby
+loader = Zeitwerk::Loader.new
+loader.push_dir(...)
+loader.enable_reloading # you need to opt-in before setup
+loader.setup
+...
 loader.reload
 ```
 
-Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, won't normally have a use case for reloading.
+There is no way to undo this, either you want to reload or you don't.
+
+Enabling reloading after setup raises `Zeitwerk::Error`. Similarly, calling `reload` without having enabled reloading also raises `Zeitwerk::Error`.
+
+Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, or services running in testing or production environments, won't normally have a use case for reloading. If reloading is not enabled, Zeitwerk is able to use less memory.
 
 Reloading removes the currently loaded classes and modules, resets the loader so that it will pick whatever is in the file system now, and runs preloads if there are any.
 
-It is important to highlight that this is an instance method. Don't worry about the project dependencies, their loaders are independent.
+It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
 
 In order for reloading to be thread-safe, you need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible RW lock. When a request comes in, the framework acquires the lock for reading at the beginning, and the code in the framework that calls `loader.reload` needs to acquire the lock for writing.
 

data/lib/zeitwerk.rb

@@ -7,5 +7,5 @@ module Zeitwerk
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
   require_relative "zeitwerk/kernel"
-  require_relative "zeitwerk/conflicting_directory"
+  require_relative "zeitwerk/error"
 end

data/lib/zeitwerk/error.rb

@@ -0,0 +1,2 @@
+class Zeitwerk::Error < StandardError
+end

data/lib/zeitwerk/loader.rb

@@ -79,6 +79,13 @@ module Zeitwerk
     # @return [{String => (Module, String)}]
     attr_reader :autoloads
 
+    # We keep track of autoloaded directories to remove them from the registry
+    # at the end of eager loading.
+    #
+    # Files are removed as they are autoloaded, but directories need to wait due
+    # to concurrency (see why in Zeitwerk::Loader::Callbacks#on_dir_autoloaded).
+    attr_reader :autoloaded_dirs
+
     # Constant paths loaded so far.
     #
     # @private
@@ -129,6 +136,7 @@ module Zeitwerk
       @ignored               = Set.new
       @ignored_paths         = Set.new
       @autoloads             = {}
+      @autoloaded_dirs       = []
       @loaded_cpaths         = Set.new
       @lazy_subdirs          = {}
       @shadowed_files        = {}
@@ -140,6 +148,8 @@ module Zeitwerk
       @setup        = false
       @eager_loaded = false
 
+      @reloading_enabled = false
+
       Registry.register_loader(self)
     end
 
@@ -161,6 +171,7 @@ module Zeitwerk
     # Pushes `paths` to the list of root directories.
     #
     # @param path [<String, Pathname>]
+    # @raise [Zeitwerk::Error]
     # @return [void]
     def push_dir(path)
       abspath = File.expand_path(path)
@@ -168,10 +179,32 @@ module Zeitwerk
         raise_if_conflicting_directory(abspath)
         root_dirs[abspath] = true
       else
-        raise ArgumentError, "the root directory #{abspath} does not exist"
+        raise Error, "the root directory #{abspath} does not exist"
+      end
+    end
+
+    # You need to call this method before setup in order to be able to reload.
+    # There is no way to undo this, either you want to reload or you don't.
+    #
+    # @raise [Zeitwerk::Error]
+    # @return [void]
+    def enable_reloading
+      mutex.synchronize do
+        break if @reloading_enabled
+
+        if @setup
+          raise Error, "cannot enable reloading after setup"
+        else
+          @reloading_enabled = true
+        end
       end
     end
 
+    # @return [Boolean]
+    def reloading_enabled?
+      @reloading_enabled
+    end
+
     # Files or directories to be preloaded instead of lazy loaded.
     #
     # @param paths [<String, Pathname, <String, Pathname>>]
@@ -251,10 +284,22 @@ module Zeitwerk
         end
 
         unless unloaded_files.empty?
+          # Bootsnap decorates Kernel#require to speed it up using a cache and
+          # this optimization does not check if $LOADED_FEATURES has the file.
+          #
+          # To make it aware of changes, the gem defines singleton methods in
+          # $LOADED_FEATURES:
+          #
+          #   https://github.com/Shopify/bootsnap/blob/master/lib/bootsnap/load_path_cache/core_ext/loaded_features.rb
+          #
+          # Rails applications may depend on bootsnap, so for unloading to work
+          # in that setting it is preferable that we restrict our API choice to
+          # one of those methods.
           $LOADED_FEATURES.reject! { |file| unloaded_files.member?(file) }
         end
 
         autoloads.clear
+        autoloaded_dirs.clear
         loaded_cpaths.clear
         lazy_subdirs.clear
         shadowed_files.clear
@@ -272,10 +317,15 @@ module Zeitwerk
     # This method is not thread-safe, please see how this can be achieved by
     # client code in the README of the project.
     #
+    # @raise [Zeitwerk::Error]
     # @return [void]
     def reload
-      unload
-      setup
+      if reloading_enabled?
+        unload
+        setup
+      else
+        raise Error, "can't reload, please call loader.enable_reloading before setup"
+      end
     end
 
     # Eager loads all files in the root directories, recursively. Files do not
@@ -301,6 +351,11 @@ module Zeitwerk
           end
         end
 
+        autoloaded_dirs.each do |dir|
+          Registry.unregister_autoload(dir)
+        end
+        autoloaded_dirs.clear
+
         @eager_loaded = true
       end
     end
@@ -598,7 +653,7 @@ module Zeitwerk
           loader.dirs.each do |already_managed_dir|
             if dir.start_with?(already_managed_dir) || already_managed_dir.start_with?(dir)
               require "pp"
-              raise ConflictingDirectory,
+              raise Error,
                 "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
                 " which is already managed by\n\n#{loader.pretty_inspect}\n"
               EOS

data/lib/zeitwerk/loader/callbacks.rb

@@ -5,8 +5,9 @@ module Zeitwerk::Loader::Callbacks
   # @param file [String]
   # @return [void]
   def on_file_autoloaded(file)
-    parent, cname = autoloads[file]
+    parent, cname = cref_autoloaded_from(file)
     loaded_cpaths.add(cpath(parent, cname))
+    Zeitwerk::Registry.unregister_autoload(file)
     log("constant #{cpath(parent, cname)} loaded from file #{file}") if logger
   end
 
@@ -18,25 +19,28 @@ module Zeitwerk::Loader::Callbacks
   # @return [void]
   def on_dir_autoloaded(dir)
     # Module#autoload does not serialize concurrent requires, and we handle
-    # directories ourselves.
+    # directories ourselves, so the callback needs to account for concurrency.
     #
-    # That introduces a race condition here in which thread t1 autovivifies the
-    # module, and while autoloads are being set on that module object, thread t2
-    # autoloads the same namespace.
+    # 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.
     #
-    # In that situation, t2 resets the constant to store a new module. That not
-    # only sets the constant twice (undesirable per se), but it gets worse,
-    # because the module object created by t2 won't have any of the autoloads
-    # for child constants set, since t1 correctly deleted the lazy_dirs entry,
-    # thus resulting in NameErrors when client code tries to reach them.
+    # Without the mutex and short-circuiting break, 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
-      parent, cname = autoloads[dir]
-      break if loaded_cpaths.include?(cpath(parent, cname))
+      parent, cname = cref_autoloaded_from(dir)
+      # If reloading is disabled and there are several threads autoloading the
+      # same namespace at the same time, the parent is going to bbe nil for all
+      # except the first one.
+      break if parent.nil? || loaded_cpaths.include?(cpath(parent, cname))
 
       autovivified_module = parent.const_set(cname, Module.new)
       log("module #{autovivified_module.name} autovivified from directory #{dir}") if logger
 
       loaded_cpaths.add(autovivified_module.name)
+      autoloaded_dirs << dir
       on_namespace_loaded(autovivified_module)
     end
   end
@@ -55,4 +59,10 @@ module Zeitwerk::Loader::Callbacks
       end
     end
   end
+
+  # @private
+  # @return [(Module, String)]
+  def cref_autoloaded_from(path)
+    reloading_enabled? ? autoloads[path] : autoloads.delete(path)
+  end
 end

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 1.4.3
+  version: 2.0.0
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-26 00:00:00.000000000 Z
+date: 2019-04-07 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -22,7 +22,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/zeitwerk.rb
-- lib/zeitwerk/conflicting_directory.rb
+- lib/zeitwerk/error.rb
 - lib/zeitwerk/explicit_namespace.rb
 - lib/zeitwerk/gem_inflector.rb
 - lib/zeitwerk/inflector.rb

data/lib/zeitwerk/conflicting_directory.rb

@@ -1,2 +0,0 @@
-class Zeitwerk::ConflictingDirectory < StandardError
-end