Class: Im::Loader
- Inherits:
-
Module
- Object
- Module
- Im::Loader
- Defined in:
- lib/im/loader.rb
Direct Known Subclasses
Defined Under Namespace
Modules: Callbacks, Config, EagerLoad, Helpers
Constant Summary collapse
- UNBOUND_METHOD_MODULE_TO_S =
Module.instance_method(:to_s)
- UNBOUND_METHOD_REMOVE_CONST =
Module.instance_method(:remove_const)
Class Attribute Summary collapse
-
.default_logger ⇒ Object
Returns the value of attribute default_logger.
Instance Attribute Summary collapse
-
#autoloaded_dirs ⇒ Object
readonly
We keep track of autoloaded directories to remove them from the registry at the end of eager loading.
-
#autoloads ⇒ Object
readonly
Maps absolute paths for which an autoload has been set —and not executed— to their corresponding parent class or module and constant name.
- #module_cpaths ⇒ Object readonly
- #module_prefix ⇒ Object readonly
- #mutex ⇒ Object readonly
- #mutex2 ⇒ Object readonly
-
#namespace_dirs ⇒ Object
readonly
Maps namespace constant paths to their respective directories.
-
#shadowed_files ⇒ Object
readonly
A shadowed file is a file managed by this loader that is ignored when setting autoloads because its matching constant is already taken.
-
#to_unload ⇒ Object
readonly
Stores metadata needed for unloading.
Attributes included from Config
#inflector, #logger, #root_dirs
Class Method Summary collapse
-
.all_dirs ⇒ Object
Returns an array with the absolute paths of the root directories of all registered loaders.
-
.eager_load_all ⇒ Object
Broadcasts ‘eager_load` to all loaders.
-
.eager_load_namespace(mod) ⇒ Object
Broadcasts ‘eager_load_namespace` to all loaders.
-
.for_gem(warn_on_extra_files: true) ⇒ Object
This is a shortcut for.
Instance Method Summary collapse
-
#initialize ⇒ Loader
constructor
A new instance of Loader.
-
#inspect ⇒ Object
Make debugging easier.
- #pretty_print(q) ⇒ Object
-
#reload ⇒ Object
Unloads all loaded code, and calls setup again so that the loader is able to pick any changes in the file system.
-
#setup ⇒ Object
Sets autoloads in the root namespaces.
-
#shadowed_file?(file) ⇒ Boolean
The return value of this predicate is only meaningful if the loader has scanned the file.
-
#unload ⇒ Object
Removes loaded constants and configured autoloads.
-
#unloadable_cpath?(cpath) ⇒ Boolean
Says if the given constant path would be unloaded on reload.
-
#unloadable_cpaths ⇒ Object
Returns an array with the constant paths that would be unloaded on reload.
-
#unregister ⇒ Object
This is a dangerous method.
Methods included from EagerLoad
#eager_load, #eager_load_dir, #eager_load_namespace, #load_file
Methods included from Config
#collapse, #dirs, #do_not_eager_load, #enable_reloading, #ignore, #log!, #on_load, #on_setup, #on_unload, #push_dir, #reloading_enabled?, #tag, #tag=
Methods included from Internal
Methods included from Callbacks
#on_dir_autoloaded, #on_file_autoloaded, #on_namespace_loaded
Constructor Details
#initialize ⇒ Loader
Returns a new instance of Loader.
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 |
# File 'lib/im/loader.rb', line 115 def initialize super @module_prefix = "#{UNBOUND_METHOD_MODULE_TO_S.bind_call(self)}::" @autoloads = {} @autoloaded_dirs = [] @to_unload = {} @namespace_dirs = Hash.new { |h, cpath| h[cpath] = [] } @shadowed_files = Set.new @module_cpaths = {} @mutex = Mutex.new @mutex2 = Mutex.new @setup = false @eager_loaded = false Registry.register_loader(self) Registry.register_autoloaded_module(self, nil, self) end |
Class Attribute Details
.default_logger ⇒ Object
Returns the value of attribute default_logger.
291 292 293 |
# File 'lib/im/loader.rb', line 291 def default_logger @default_logger end |
Instance Attribute Details
#autoloaded_dirs ⇒ Object (readonly)
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 Im::Loader::Callbacks#on_dir_autoloaded).
52 53 54 |
# File 'lib/im/loader.rb', line 52 def autoloaded_dirs @autoloaded_dirs end |
#autoloads ⇒ Object (readonly)
Maps absolute paths for which an autoload has been set —and not executed— to their corresponding parent class or module and constant name.
"/Users/fxn/blog/app/models/user.rb" => [Object, :User],
"/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
...
42 43 44 |
# File 'lib/im/loader.rb', line 42 def autoloads @autoloads end |
#module_cpaths ⇒ Object (readonly)
101 102 103 |
# File 'lib/im/loader.rb', line 101 def module_cpaths @module_cpaths end |
#module_prefix ⇒ Object (readonly)
105 106 107 |
# File 'lib/im/loader.rb', line 105 def module_prefix @module_prefix end |
#mutex ⇒ Object (readonly)
109 110 111 |
# File 'lib/im/loader.rb', line 109 def mutex @mutex end |
#mutex2 ⇒ Object (readonly)
113 114 115 |
# File 'lib/im/loader.rb', line 113 def mutex2 @mutex2 end |
#namespace_dirs ⇒ Object (readonly)
Maps namespace constant paths to their respective directories.
For example, given this mapping:
"Admin" => [
"/Users/fxn/blog/app/controllers/admin",
"/Users/fxn/blog/app/models/admin",
...
]
when ‘Admin` gets defined we know that it plays the role of a namespace and that its children are spread over those directories. We’ll visit them to set up the corresponding autoloads.
86 87 88 |
# File 'lib/im/loader.rb', line 86 def namespace_dirs @namespace_dirs end |
#shadowed_files ⇒ Object (readonly)
A shadowed file is a file managed by this loader that is ignored when setting autoloads because its matching constant is already taken.
This private set is populated as we descend. For example, if the loader has only scanned the top-level, ‘shadowed_files` does not have shadowed files that may exist deep in the project tree yet.
97 98 99 |
# File 'lib/im/loader.rb', line 97 def shadowed_files @shadowed_files end |
#to_unload ⇒ Object (readonly)
Stores metadata needed for unloading. Its entries look like this:
"Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
The cpath as key helps implementing unloadable_cpath? The file name is stored in order to be able to delete it from $LOADED_FEATURES, and the pair [Module, Symbol] is used to remove_const the constant from the class or module object.
If reloading is enabled, this hash is filled as constants are autoloaded or eager loaded. Otherwise, the collection remains empty.
68 69 70 |
# File 'lib/im/loader.rb', line 68 def to_unload @to_unload end |
Class Method Details
.all_dirs ⇒ Object
Returns an array with the absolute paths of the root directories of all registered loaders. This is a read-only collection.
345 346 347 |
# File 'lib/im/loader.rb', line 345 def all_dirs Registry.loaders.map(&:dirs).inject(&:+).freeze end |
.eager_load_all ⇒ Object
Broadcasts ‘eager_load` to all loaders. Those that have not been setup are skipped.
317 318 319 320 321 322 323 324 325 |
# File 'lib/im/loader.rb', line 317 def eager_load_all Registry.loaders.each do |loader| begin loader.eager_load rescue SetupRequired # This is fine, we eager load what can be eager loaded. end end end |
.eager_load_namespace(mod) ⇒ Object
Broadcasts ‘eager_load_namespace` to all loaders. Those that have not been setup are skipped.
331 332 333 334 335 336 337 338 339 |
# File 'lib/im/loader.rb', line 331 def eager_load_namespace(mod) Registry.loaders.each do |loader| begin loader.eager_load_namespace(mod) rescue SetupRequired # This is fine, we eager load what can be eager loaded. end end end |
.for_gem(warn_on_extra_files: true) ⇒ Object
This is a shortcut for
require "im"
loader = Im::Loader.new
loader.tag = File.basename(__FILE__, ".rb")
loader.inflector = Im::GemInflector.new(__FILE__)
loader.push_dir(__dir__)
except that this method returns the same object in subsequent calls from the same file, in the unlikely case the gem wants to be able to reload.
This method returns a subclass of Im::Loader, but the exact type is private, client code can only rely on the interface.
308 309 310 311 |
# File 'lib/im/loader.rb', line 308 def for_gem(warn_on_extra_files: true) called_from = caller_locations(1, 1).first.path Registry.loader_for_gem(called_from, warn_on_extra_files: warn_on_extra_files) end |
Instance Method Details
#inspect ⇒ Object
Make debugging easier
24 25 26 |
# File 'lib/im/loader.rb', line 24 def inspect Object.instance_method(:inspect).bind_call(self) end |
#pretty_print(q) ⇒ Object
28 29 30 |
# File 'lib/im/loader.rb', line 28 def pretty_print(q) q.pp_object(self) end |
#reload ⇒ Object
Unloads all loaded code, and calls setup again so that the loader is able to pick any changes in the file system.
This method is not thread-safe, please see how this can be achieved by client code in the README of the project.
243 244 245 246 247 248 249 250 251 |
# File 'lib/im/loader.rb', line 243 def reload raise ReloadingDisabledError unless reloading_enabled? raise SetupRequired unless @setup unload recompute_ignored_paths recompute_collapse_dirs setup end |
#setup ⇒ Object
Sets autoloads in the root namespaces.
137 138 139 140 141 142 143 144 145 146 147 |
# File 'lib/im/loader.rb', line 137 def setup mutex.synchronize do break if @setup actual_roots.each { |root_dir| set_autoloads_in_dir(root_dir) } on_setup_callbacks.each(&:call) @setup = true end end |
#shadowed_file?(file) ⇒ Boolean
The return value of this predicate is only meaningful if the loader has scanned the file. This is the case in the spots where we use it.
283 284 285 |
# File 'lib/im/loader.rb', line 283 def shadowed_file?(file) shadowed_files.member?(file) end |
#unload ⇒ Object
Removes loaded constants and configured autoloads.
The objects the constants stored are no longer reachable through them. In addition, since said objects are normally not referenced from anywhere else, they are eligible for garbage collection, which would effectively unload them.
This method is public but undocumented. Main interface is ‘reload`, which means `unload` + `setup`. This one is avaiable to be used together with `unregister`, which is undocumented too.
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 |
# File 'lib/im/loader.rb', line 161 def unload mutex.synchronize do raise SetupRequired unless @setup # We are going to keep track of the files that were required by our # autoloads to later remove them from $LOADED_FEATURES, thus making them # loadable by Kernel#require again. # # Directories are not stored in $LOADED_FEATURES, keeping track of files # is enough. unloaded_files = Set.new autoloads.each do |abspath, (parent, cname)| if parent.autoload?(cname) unload_autoload(parent, cname) else # Could happen if loaded with require_relative. That is unsupported, # and the constant path would escape unloadable_cpath? This is just # defensive code to clean things up as much as we are able to. unload_cref(parent, cname) unloaded_files.add(abspath) if ruby?(abspath) end end to_unload.each do |cpath, (abspath, (parent, cname))| unless on_unload_callbacks.empty? begin value = cget(parent, cname) rescue ::NameError # Perhaps the user deleted the constant by hand, or perhaps an # autoload failed to define the expected constant but the user # rescued the exception. else run_on_unload_callbacks(cpath, value, abspath) end end # Replace all inbound references to constant by autoloads. reset_inbound_references(parent, cname) unload_cref(parent, cname) unloaded_files.add(abspath) if ruby?(abspath) 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 to_unload.clear namespace_dirs.clear shadowed_files.clear module_cpaths.clear Registry.on_unload(self) ExplicitNamespace.__unregister_loader(self) @setup = false @eager_loaded = false end end |
#unloadable_cpath?(cpath) ⇒ Boolean
Says if the given constant path would be unloaded on reload. This predicate returns ‘false` if reloading is disabled.
257 258 259 |
# File 'lib/im/loader.rb', line 257 def unloadable_cpath?(cpath) to_unload.key?(cpath) end |
#unloadable_cpaths ⇒ Object
Returns an array with the constant paths that would be unloaded on reload. This predicate returns an empty array if reloading is disabled.
265 266 267 |
# File 'lib/im/loader.rb', line 265 def unloadable_cpaths to_unload.keys.freeze end |
#unregister ⇒ Object
This is a dangerous method.
273 274 275 276 |
# File 'lib/im/loader.rb', line 273 def unregister Registry.unregister_loader(self) ExplicitNamespace.__unregister_loader(self) end |