-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathautoloading_and_reloading_constants.html
1273 lines (1175 loc) · 69.8 KB
/
autoloading_and_reloading_constants.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Autoloading and Reloading Constants — Ruby on Rails Guides</title>
<link rel="stylesheet" type="text/css" href="stylesheets/style.css" data-turbolinks-track="reload">
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print">
<link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shCore.css" data-turbolinks-track="reload">
<link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shThemeRailsGuides.css" data-turbolinks-track="reload">
<link rel="stylesheet" type="text/css" href="stylesheets/fixes.css" data-turbolinks-track="reload">
<link href="images/favicon.ico" rel="shortcut icon" type="image/x-icon" />
<script src="javascripts/syntaxhighlighter.js" data-turbolinks-track="reload"></script>
<script src="javascripts/turbolinks.js" data-turbolinks-track="reload"></script>
<script src="javascripts/guides.js" data-turbolinks-track="reload"></script>
<script src="javascripts/responsive-tables.js" data-turbolinks-track="reload"></script>
</head>
<body class="guide">
<div>
<img src="images/edge_badge.png" alt="edge-badge" id="edge-badge" />
</div>
<div id="topNav">
<div class="wrapper">
<strong class="more-info-label">Veja mais em <a href="http://rubyonrails.org/">rubyonrails.org:</a> </strong>
<span class="red-button more-info-button">
Mais Ruby on Rails
</span>
<ul class="more-info-links s-hidden">
<li class="more-info"><a href="https://weblog.rubyonrails.org/">Blog</a></li>
<li class="more-info"><a href="https://guides.rubyonrails.org/">Guia</a></li>
<li class="more-info"><a href="http://api.rubyonrails.org/">API</a></li>
<li class="more-info"><a href="https://stackoverflow.com/questions/tagged/ruby-on-rails">Pedir ajuda</a></li>
<li class="more-info"><a href="https://github.com/rails/rails">Contribuir no GitHub</a></li>
</ul>
</div>
</div>
<div id="header">
<div class="wrapper clearfix">
<h1><a href="index.html" title="Return to home page">Guides.rubyonrails.org</a></h1>
<ul class="nav">
<li><a class="nav-item" href="index.html">Home</a></li>
<li class="guides-index guides-index-large">
<a href="index.html" id="guidesMenu" class="guides-index-item nav-item">Guias</a>
<div id="guides" class="clearfix" style="display: none;">
<hr />
<div class="guides-section-container">
<div class="guides-section">
<dt>Comece Aqui</dt>
</div>
<div class="guides-section">
<dt>Models</dt>
</div>
<div class="guides-section">
<dt>Views</dt>
</div>
<div class="guides-section">
<dt>Controllers</dt>
</div>
<div class="guides-section">
<dt>Other Components</dt>
</div>
<div class="guides-section">
<dt>Digging Deeper</dt>
</div>
<div class="guides-section">
<dt>Extending Rails</dt>
<dd><a href="rails_on_rack.html">Rails on Rack</a></dd>
<dd><a href="generators.html">Creating and Customizing Rails Generators & Templates</a></dd>
</div>
<div class="guides-section">
<dt>Contributions</dt>
<dd><a href="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</a></dd>
<dd><a href="api_documentation_guidelines.html">API Documentation Guidelines</a></dd>
<dd><a href="ruby_on_rails_guides_guidelines.html">Guides Guidelines</a></dd>
</div>
<div class="guides-section">
<dt>Policies</dt>
<dd><a href="maintenance_policy.html">Maintenance Policy</a></dd>
</div>
<div class="guides-section">
<dt>Release Notes</dt>
<dd><a href="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</a></dd>
<dd><a href="5_2_release_notes.html">Version 5.2 - April 2018</a></dd>
<dd><a href="5_1_release_notes.html">Version 5.1 - April 2017</a></dd>
<dd><a href="5_0_release_notes.html">Version 5.0 - June 2016</a></dd>
<dd><a href="4_2_release_notes.html">Version 4.2 - December 2014</a></dd>
<dd><a href="4_1_release_notes.html">Version 4.1 - April 2014</a></dd>
<dd><a href="4_0_release_notes.html">Version 4.0 - June 2013</a></dd>
<dd><a href="3_2_release_notes.html">Version 3.2 - January 2012</a></dd>
<dd><a href="3_1_release_notes.html">Version 3.1 - August 2011</a></dd>
<dd><a href="3_0_release_notes.html">Version 3.0 - August 2010</a></dd>
<dd><a href="2_3_release_notes.html">Version 2.3 - March 2009</a></dd>
<dd><a href="2_2_release_notes.html">Version 2.2 - November 2008</a></dd>
</div>
</div>
</div>
</li>
<li><a class="nav-item" href="contributing_to_ruby_on_rails.html">Contribua</a></li>
<li class="guides-index guides-index-small">
<select class="guides-index-item nav-item">
<option value="index.html">Guias</option>
<optgroup label="Comece Aqui">
</optgroup>
<optgroup label="Models">
</optgroup>
<optgroup label="Views">
</optgroup>
<optgroup label="Controllers">
</optgroup>
<optgroup label="Other Components">
</optgroup>
<optgroup label="Digging Deeper">
</optgroup>
<optgroup label="Extending Rails">
<option value="rails_on_rack.html">Rails on Rack</option>
<option value="generators.html">Creating and Customizing Rails Generators & Templates</option>
</optgroup>
<optgroup label="Contributions">
<option value="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</option>
<option value="api_documentation_guidelines.html">API Documentation Guidelines</option>
<option value="ruby_on_rails_guides_guidelines.html">Guides Guidelines</option>
</optgroup>
<optgroup label="Policies">
<option value="maintenance_policy.html">Maintenance Policy</option>
</optgroup>
<optgroup label="Release Notes">
<option value="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</option>
<option value="5_2_release_notes.html">Version 5.2 - April 2018</option>
<option value="5_1_release_notes.html">Version 5.1 - April 2017</option>
<option value="5_0_release_notes.html">Version 5.0 - June 2016</option>
<option value="4_2_release_notes.html">Version 4.2 - December 2014</option>
<option value="4_1_release_notes.html">Version 4.1 - April 2014</option>
<option value="4_0_release_notes.html">Version 4.0 - June 2013</option>
<option value="3_2_release_notes.html">Version 3.2 - January 2012</option>
<option value="3_1_release_notes.html">Version 3.1 - August 2011</option>
<option value="3_0_release_notes.html">Version 3.0 - August 2010</option>
<option value="2_3_release_notes.html">Version 2.3 - March 2009</option>
<option value="2_2_release_notes.html">Version 2.2 - November 2008</option>
</optgroup>
</select>
</li>
</ul>
</div>
</div>
<hr class="hide" />
<div id="feature">
<div class="wrapper">
<h2>Autoloading and Reloading Constants</h2><p>This guide documents how constant autoloading and reloading works.</p><p>After reading this guide, you will know:</p>
<ul>
<li>Key aspects of Ruby constants</li>
<li>What are the <code>autoload_paths</code> and how does eager loading work in production?</li>
<li>How constant autoloading works</li>
<li>What is <code>require_dependency</code></li>
<li>How constant reloading works</li>
<li>Solutions to common autoloading gotchas</li>
</ul>
<div id="subCol">
<h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
<ol class="chapters">
<li><a href="#introduction">Introduction</a></li>
<li>
<a href="#constants-refresher">Constants Refresher</a>
<ul>
<li><a href="#nesting">Nesting</a></li>
<li><a href="#class-and-module-definitions-are-constant-assignments">Class and Module Definitions are Constant Assignments</a></li>
<li><a href="#constants-are-stored-in-modules">Constants are Stored in Modules</a></li>
<li><a href="#resolution-algorithms">Resolution Algorithms</a></li>
</ul>
</li>
<li>
<a href="#vocabulary">Vocabulary</a>
<ul>
<li><a href="#parent-namespaces">Parent Namespaces</a></li>
<li><a href="#loading-mechanism">Loading Mechanism</a></li>
</ul>
</li>
<li><a href="#autoloading-availability">Autoloading Availability</a></li>
<li><a href="#autoload-paths-and-eager-load-paths">autoload_paths and eager_load_paths</a></li>
<li>
<a href="#autoloading-algorithms">Autoloading Algorithms</a>
<ul>
<li><a href="#autoloading-algorithms-relative-references">Relative References</a></li>
<li><a href="#autoloading-algorithms-qualified-references">Qualified References</a></li>
<li><a href="#automatic-modules">Automatic Modules</a></li>
<li><a href="#generic-procedure">Generic Procedure</a></li>
</ul>
</li>
<li><a href="#require-dependency">require_dependency</a></li>
<li><a href="#constant-reloading">Constant Reloading</a></li>
<li><a href="#module-autoload-isn-t-involved">Module#autoload isn't Involved</a></li>
<li>
<a href="#common-gotchas">Common Gotchas</a>
<ul>
<li><a href="#nesting-and-qualified-constants">Nesting and Qualified Constants</a></li>
<li><a href="#autoloading-and-sti">Autoloading and STI</a></li>
<li><a href="#autoloading-and-require">Autoloading and <code>require</code></a></li>
<li><a href="#autoloading-and-initializers">Autoloading and Initializers</a></li>
<li><a href="#require-dependency-and-initializers"><code>require_dependency</code> and Initializers</a></li>
<li><a href="#when-constants-aren-t-missed">When Constants aren't Missed</a></li>
<li><a href="#autoloading-within-singleton-classes">Autoloading within Singleton Classes</a></li>
<li><a href="#autoloading-in-basicobject">Autoloading in <code>BasicObject</code></a></li>
<li><a href="#autoloading-in-the-test-environment">Autoloading in the Test Environment</a></li>
</ul>
</li>
<li>
<a href="#troubleshooting">Troubleshooting</a>
<ul>
<li><a href="#tracing-autoloads">Tracing Autoloads</a></li>
<li><a href="#where-is-a-given-autoload-triggered-questionmark">Where is a Given Autoload Triggered?</a></li>
<li><a href="#which-constants-have-been-autoloaded-questionmark">Which Constants Have Been Autoloaded?</a></li>
</ul>
</li>
</ol>
</div>
</div>
</div>
<div id="container">
<div class="wrapper">
<div id="mainCol">
<h3 id="introduction"><a class="anchorlink" href="#introduction">1 Introduction</a></h3><p>Ruby on Rails allows applications to be written as if their code was preloaded.</p><p>In a normal Ruby program classes need to load their dependencies:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
require 'application_controller'
require 'post'
class PostsController < ApplicationController
def index
@posts = Post.all
end
end
</pre>
</div>
<p>Our Rubyist instinct quickly sees some redundancy in there: If classes were
defined in files matching their name, couldn't their loading be automated
somehow? We could save scanning the file for dependencies, which is brittle.</p><p>Moreover, <code>Kernel#require</code> loads files once, but development is much more smooth
if code gets refreshed when it changes without restarting the server. It would
be nice to be able to use <code>Kernel#load</code> in development, and <code>Kernel#require</code> in
production.</p><p>Indeed, those features are provided by Ruby on Rails, where we just write</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class PostsController < ApplicationController
def index
@posts = Post.all
end
end
</pre>
</div>
<p>This guide documents how that works.</p><h3 id="constants-refresher"><a class="anchorlink" href="#constants-refresher">2 Constants Refresher</a></h3><p>While constants are trivial in most programming languages, they are a rich
topic in Ruby.</p><p>It is beyond the scope of this guide to document Ruby constants, but we are
nevertheless going to highlight a few key topics. Truly grasping the following
sections is instrumental to understanding constant autoloading and reloading.</p><h4 id="nesting"><a class="anchorlink" href="#nesting">2.1 Nesting</a></h4><p>Class and module definitions can be nested to create namespaces:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module XML
class SAXParser
# (1)
end
end
</pre>
</div>
<p>The <em>nesting</em> at any given place is the collection of enclosing nested class and
module objects outwards. The nesting at any given place can be inspected with
<code>Module.nesting</code>. For example, in the previous example, the nesting at
(1) is</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
[XML::SAXParser, XML]
</pre>
</div>
<p>It is important to understand that the nesting is composed of class and module
<em>objects</em>, it has nothing to do with the constants used to access them, and is
also unrelated to their names.</p><p>For instance, while this definition is similar to the previous one:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class XML::SAXParser
# (2)
end
</pre>
</div>
<p>the nesting in (2) is different:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
[XML::SAXParser]
</pre>
</div>
<p><code>XML</code> does not belong to it.</p><p>We can see in this example that the name of a class or module that belongs to a
certain nesting does not necessarily correlate with the namespaces at the spot.</p><p>Even more, they are totally independent, take for instance</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module X
module Y
end
end
module A
module B
end
end
module X::Y
module A::B
# (3)
end
end
</pre>
</div>
<p>The nesting in (3) consists of two module objects:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
[A::B, X::Y]
</pre>
</div>
<p>So, it not only doesn't end in <code>A</code>, which does not even belong to the nesting,
but it also contains <code>X::Y</code>, which is independent from <code>A::B</code>.</p><p>The nesting is an internal stack maintained by the interpreter, and it gets
modified according to these rules:</p>
<ul>
<li><p>The class object following a <code>class</code> keyword gets pushed when its body is
executed, and popped after it.</p></li>
<li><p>The module object following a <code>module</code> keyword gets pushed when its body is
executed, and popped after it.</p></li>
<li><p>A singleton class opened with <code>class << object</code> gets pushed, and popped later.</p></li>
<li><p>When <code>instance_eval</code> is called using a string argument,
the singleton class of the receiver is pushed to the nesting of the eval'ed
code. When <code>class_eval</code> or <code>module_eval</code> is called using a string argument,
the receiver is pushed to the nesting of the eval'ed code.</p></li>
<li><p>The nesting at the top-level of code interpreted by <code>Kernel#load</code> is empty
unless the <code>load</code> call receives a true value as second argument, in which case
a newly created anonymous module is pushed by Ruby.</p></li>
</ul>
<p>It is interesting to observe that blocks do not modify the stack. In particular
the blocks that may be passed to <code>Class.new</code> and <code>Module.new</code> do not get the
class or module being defined pushed to their nesting. That's one of the
differences between defining classes and modules in one way or another.</p><h4 id="class-and-module-definitions-are-constant-assignments"><a class="anchorlink" href="#class-and-module-definitions-are-constant-assignments">2.2 Class and Module Definitions are Constant Assignments</a></h4><p>Let's suppose the following snippet creates a class (rather than reopening it):</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class C
end
</pre>
</div>
<p>Ruby creates a constant <code>C</code> in <code>Object</code> and stores in that constant a class
object. The name of the class instance is "C", a string, named after the
constant.</p><p>That is,</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class Project < ApplicationRecord
end
</pre>
</div>
<p>performs a constant assignment equivalent to</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Project = Class.new(ApplicationRecord)
</pre>
</div>
<p>including setting the name of the class as a side-effect:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Project.name # => "Project"
</pre>
</div>
<p>Constant assignment has a special rule to make that happen: if the object
being assigned is an anonymous class or module, Ruby sets the object's name to
the name of the constant.</p><div class="info"><p>From then on, what happens to the constant and the instance does not
matter. For example, the constant could be deleted, the class object could be
assigned to a different constant, be stored in no constant anymore, etc. Once
the name is set, it doesn't change.</p></div><p>Similarly, module creation using the <code>module</code> keyword as in</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module Admin
end
</pre>
</div>
<p>performs a constant assignment equivalent to</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Admin = Module.new
</pre>
</div>
<p>including setting the name as a side-effect:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Admin.name # => "Admin"
</pre>
</div>
<div class="warning"><p>The execution context of a block passed to <code>Class.new</code> or <code>Module.new</code>
is not entirely equivalent to the one of the body of the definitions using the
<code>class</code> and <code>module</code> keywords. But both idioms result in the same constant
assignment.</p></div><p>Thus, an informal expression like "the <code>String</code> class" technically means the
class object stored in the constant called "String". That constant, in turn,
belongs to the class object stored in the constant called "Object".</p><p><code>String</code> is an ordinary constant, and everything related to them such as
resolution algorithms applies to it.</p><p>Likewise, in the controller</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class PostsController < ApplicationController
def index
@posts = Post.all
end
end
</pre>
</div>
<p><code>Post</code> is not syntax for a class. Rather, <code>Post</code> is a regular Ruby constant. If
all is good, the constant is evaluated to an object that responds to <code>all</code>.</p><p>That is why we talk about <em>constant</em> autoloading, Rails has the ability to
load constants on the fly.</p><h4 id="constants-are-stored-in-modules"><a class="anchorlink" href="#constants-are-stored-in-modules">2.3 Constants are Stored in Modules</a></h4><p>Constants belong to modules in a very literal sense. Classes and modules have
a constant table; think of it as a hash table.</p><p>Let's analyze an example to really understand what that means. While common
abuses of language like "the <code>String</code> class" are convenient, the exposition is
going to be precise here for didactic purposes.</p><p>Let's consider the following module definition:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module Colors
RED = '0xff0000'
end
</pre>
</div>
<p>First, when the <code>module</code> keyword is processed, the interpreter creates a new
entry in the constant table of the class object stored in the <code>Object</code> constant.
Said entry associates the name "Colors" to a newly created module object.
Furthermore, the interpreter sets the name of the new module object to be the
string "Colors".</p><p>Later, when the body of the module definition is interpreted, a new entry is
created in the constant table of the module object stored in the <code>Colors</code>
constant. That entry maps the name "RED" to the string "0xff0000".</p><p>In particular, <code>Colors::RED</code> is totally unrelated to any other <code>RED</code> constant
that may live in any other class or module object. If there were any, they
would have separate entries in their respective constant tables.</p><p>Pay special attention in the previous paragraphs to the distinction between
class and module objects, constant names, and value objects associated to them
in constant tables.</p><h4 id="resolution-algorithms"><a class="anchorlink" href="#resolution-algorithms">2.4 Resolution Algorithms</a></h4><h5 id="resolution-algorithm-for-relative-constants"><a class="anchorlink" href="#resolution-algorithm-for-relative-constants">2.4.1 Resolution Algorithm for Relative Constants</a></h5><p>At any given place in the code, let's define <em>cref</em> to be the first element of
the nesting if it is not empty, or <code>Object</code> otherwise.</p><p>Without getting too much into the details, the resolution algorithm for relative
constant references goes like this:</p>
<ol>
<li><p>If the nesting is not empty the constant is looked up in its elements and in
order. The ancestors of those elements are ignored.</p></li>
<li><p>If not found, then the algorithm walks up the ancestor chain of the cref.</p></li>
<li><p>If not found and the cref is a module, the constant is looked up in <code>Object</code>.</p></li>
<li><p>If not found, <code>const_missing</code> is invoked on the cref. The default
implementation of <code>const_missing</code> raises <code>NameError</code>, but it can be overridden.</p></li>
</ol>
<p>Rails autoloading <strong>does not emulate this algorithm</strong>, but its starting point is
the name of the constant to be autoloaded, and the cref. See more in <a href="#autoloading-algorithms-relative-references">Relative
References</a>.</p><h5 id="resolution-algorithm-for-qualified-constants"><a class="anchorlink" href="#resolution-algorithm-for-qualified-constants">2.4.2 Resolution Algorithm for Qualified Constants</a></h5><p>Qualified constants look like this:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Billing::Invoice
</pre>
</div>
<p><code>Billing::Invoice</code> is composed of two constants: <code>Billing</code> is relative and is
resolved using the algorithm of the previous section.</p><div class="info"><p>Leading colons would make the first segment absolute rather than
relative: <code>::Billing::Invoice</code>. That would force <code>Billing</code> to be looked up
only as a top-level constant.</p></div><p><code>Invoice</code> on the other hand is qualified by <code>Billing</code> and we are going to see
its resolution next. Let's define <em>parent</em> to be that qualifying class or module
object, that is, <code>Billing</code> in the example above. The algorithm for qualified
constants goes like this:</p>
<ol>
<li><p>The constant is looked up in the parent and its ancestors. In Ruby >= 2.5,
<code>Object</code> is skipped if present among the ancestors. <code>Kernel</code> and <code>BasicObject</code>
are still checked though.</p></li>
<li><p>If the lookup fails, <code>const_missing</code> is invoked in the parent. The default
implementation of <code>const_missing</code> raises <code>NameError</code>, but it can be overridden.</p></li>
</ol>
<div class="info"><p>In Ruby < 2.5 <code>String::Hash</code> evaluates to <code>Hash</code> and the interpreter
issues a warning: "toplevel constant Hash referenced by String::Hash". Starting
with 2.5, <code>String::Hash</code> raises <code>NameError</code> because <code>Object</code> is skipped.</p></div><p>As you see, this algorithm is simpler than the one for relative constants. In
particular, the nesting plays no role here, and modules are not special-cased,
if neither they nor their ancestors have the constants, <code>Object</code> is <strong>not</strong>
checked.</p><p>Rails autoloading <strong>does not emulate this algorithm</strong>, but its starting point is
the name of the constant to be autoloaded, and the parent. See more in
<a href="#autoloading-algorithms-qualified-references">Qualified References</a>.</p><h3 id="vocabulary"><a class="anchorlink" href="#vocabulary">3 Vocabulary</a></h3><h4 id="parent-namespaces"><a class="anchorlink" href="#parent-namespaces">3.1 Parent Namespaces</a></h4><p>Given a string with a constant path we define its <em>parent namespace</em> to be the
string that results from removing its rightmost segment.</p><p>For example, the parent namespace of the string "A::B::C" is the string "A::B",
the parent namespace of "A::B" is "A", and the parent namespace of "A" is "".</p><p>The interpretation of a parent namespace when thinking about classes and modules
is tricky though. Let's consider a module M named "A::B":</p>
<ul>
<li><p>The parent namespace, "A", may not reflect nesting at a given spot.</p></li>
<li><p>The constant <code>A</code> may no longer exist, some code could have removed it from
<code>Object</code>.</p></li>
<li><p>If <code>A</code> exists, the class or module that was originally in <code>A</code> may not be there
anymore. For example, if after a constant removal there was another constant
assignment there would generally be a different object in there.</p></li>
<li><p>In such case, it could even happen that the reassigned <code>A</code> held a new class or
module called also "A"!</p></li>
<li><p>In the previous scenarios M would no longer be reachable through <code>A::B</code> but
the module object itself could still be alive somewhere and its name would
still be "A::B".</p></li>
</ul>
<p>The idea of a parent namespace is at the core of the autoloading algorithms
and helps explain and understand their motivation intuitively, but as you see
that metaphor leaks easily. Given an edge case to reason about, take always into
account that by "parent namespace" the guide means exactly that specific string
derivation.</p><h4 id="loading-mechanism"><a class="anchorlink" href="#loading-mechanism">3.2 Loading Mechanism</a></h4><p>Rails autoloads files with <code>Kernel#load</code> when <code>config.cache_classes</code> is false,
the default in development mode, and with <code>Kernel#require</code> otherwise, the
default in production mode.</p><p><code>Kernel#load</code> allows Rails to execute files more than once if <a href="#constant-reloading">constant
reloading</a> is enabled.</p><p>This guide uses the word "load" freely to mean a given file is interpreted, but
the actual mechanism can be <code>Kernel#load</code> or <code>Kernel#require</code> depending on that
flag.</p><h3 id="autoloading-availability"><a class="anchorlink" href="#autoloading-availability">4 Autoloading Availability</a></h3><p>Rails is always able to autoload provided its environment is in place. For
example the <code>runner</code> command autoloads:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ rails runner 'p User.column_names'
["id", "email", "created_at", "updated_at"]
</pre>
</div>
<p>The console autoloads, the test suite autoloads, and of course the application
autoloads.</p><p>By default, Rails eager loads the application files when it boots in production
mode, so most of the autoloading going on in development does not happen. But
autoloading may still be triggered during eager loading.</p><p>For example, given</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class BeachHouse < House
end
</pre>
</div>
<p>if <code>House</code> is still unknown when <code>app/models/beach_house.rb</code> is being eager
loaded, Rails autoloads it.</p><h3 id="autoload-paths-and-eager-load-paths"><a class="anchorlink" href="#autoload-paths-and-eager-load-paths">5 autoload_paths and eager_load_paths</a></h3><p>As you probably know, when <code>require</code> gets a relative file name:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
require 'erb'
</pre>
</div>
<p>Ruby looks for the file in the directories listed in <code>$LOAD_PATH</code>. That is, Ruby
iterates over all its directories and for each one of them checks whether they
have a file called "erb.rb", or "erb.so", or "erb.o", or "erb.dll". If it finds
any of them, the interpreter loads it and ends the search. Otherwise, it tries
again in the next directory of the list. If the list gets exhausted, <code>LoadError</code>
is raised.</p><p>We are going to cover how constant autoloading works in more detail later, but
the idea is that when a constant like <code>Post</code> is hit and missing, if there's a
<code>post.rb</code> file for example in <code>app/models</code> Rails is going to find it, evaluate
it, and have <code>Post</code> defined as a side-effect.</p><p>All right, Rails has a collection of directories similar to <code>$LOAD_PATH</code> in which
to look up <code>post.rb</code>. That collection is called <code>autoload_paths</code> and by
default it contains:</p>
<ul>
<li><p>All subdirectories of <code>app</code> in the application and engines present at boot
time. For example, <code>app/controllers</code>. They do not need to be the default
ones, any custom directories like <code>app/workers</code> belong automatically to
<code>autoload_paths</code>.</p></li>
<li><p>Any existing second level directories called <code>app/*/concerns</code> in the
application and engines.</p></li>
<li><p>The directory <code>test/mailers/previews</code>.</p></li>
</ul>
<p><code>eager_load_paths</code> is initially the <code>app</code> paths above</p><p>How files are autoloaded depends on <code>eager_load</code> and <code>cache_classes</code> config settings which typically vary in development, production, and test modes:</p>
<ul>
<li>In <strong>development</strong>, you want quicker startup with incremental loading of application code. So <code>eager_load</code> should be set to <code>false</code>, and Rails will autoload files as needed (see <a href="#autoloading-algorithms">Autoloading Algorithms</a> below) -- and then reload them when they change (see <a href="#constant-reloading">Constant Reloading</a> below).</li>
<li>In <strong>production</strong>, however, you want consistency and thread-safety and can live with a longer boot time. So <code>eager_load</code> is set to <code>true</code>, and then during boot (before the app is ready to receive requests) Rails loads all files in the <code>eager_load_paths</code> and then turns off auto loading (NB: autoloading may be needed during eager loading). Not autoloading after boot is a <code>good thing</code>, as autoloading can cause the app to be have thread-safety problems.</li>
<li>In <strong>test</strong>, for speed of execution (of individual tests) <code>eager_load</code> is <code>false</code>, so Rails follows development behaviour.</li>
</ul>
<p>What is described above are the defaults with a newly generated Rails app. There are multiple ways this can be configured differently (see <a href="configuring.html#rails-general-configuration">Configuring Rails Applications</a>.
). But using <code>autoload_paths</code> on its own in the past (before Rails 5) developers might configure <code>autoload_paths</code> to add in extra locations (e.g. <code>lib</code> which used to be an autoload path list years ago, but no longer is). However this is now discouraged for most purposes, as it is likely to lead to production-only errors. It is possible to add new locations to both <code>config.eager_load_paths</code> and <code>config.autoload_paths</code> but use at your own risk.</p><p>See also <a href="#autoloading-in-the-test-environment">Autoloading in the Test Environment</a>.</p><p><code>config.autoload_paths</code> is not changeable from environment-specific configuration files.</p><p>The value of <code>autoload_paths</code> can be inspected. In a just-generated application
it is (edited):</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ rails r 'puts ActiveSupport::Dependencies.autoload_paths'
.../app/assets
.../app/channels
.../app/controllers
.../app/controllers/concerns
.../app/helpers
.../app/jobs
.../app/mailers
.../app/models
.../app/models/concerns
.../activestorage/app/assets
.../activestorage/app/controllers
.../activestorage/app/javascript
.../activestorage/app/jobs
.../activestorage/app/models
.../actioncable/app/assets
.../actionview/app/assets
.../test/mailers/previews
</pre>
</div>
<div class="info"><p><code>autoload_paths</code> is computed and cached during the initialization process.
The application needs to be restarted to reflect any changes in the directory
structure.</p></div><h3 id="autoloading-algorithms"><a class="anchorlink" href="#autoloading-algorithms">6 Autoloading Algorithms</a></h3><h4 id="autoloading-algorithms-relative-references"><a class="anchorlink" href="#autoloading-algorithms-relative-references">6.1 Relative References</a></h4><p>A relative constant reference may appear in several places, for example, in</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class PostsController < ApplicationController
def index
@posts = Post.all
end
end
</pre>
</div>
<p>all three constant references are relative.</p><h5 id="constants-after-the-class-and-module-keywords"><a class="anchorlink" href="#constants-after-the-class-and-module-keywords">6.1.1 Constants after the <code>class</code> and <code>module</code> Keywords</a></h5><p>Ruby performs a lookup for the constant that follows a <code>class</code> or <code>module</code>
keyword because it needs to know if the class or module is going to be created
or reopened.</p><p>If the constant is not defined at that point it is not considered to be a
missing constant, autoloading is <strong>not</strong> triggered.</p><p>So, in the previous example, if <code>PostsController</code> is not defined when the file
is interpreted Rails autoloading is not going to be triggered, Ruby will just
define the controller.</p><h5 id="top-level-constants"><a class="anchorlink" href="#top-level-constants">6.1.2 Top-Level Constants</a></h5><p>On the contrary, if <code>ApplicationController</code> is unknown, the constant is
considered missing and an autoload is going to be attempted by Rails.</p><p>In order to load <code>ApplicationController</code>, Rails iterates over <code>autoload_paths</code>.
First it checks if <code>app/assets/application_controller.rb</code> exists. If it does not,
which is normally the case, it continues and finds
<code>app/controllers/application_controller.rb</code>.</p><p>If the file defines the constant <code>ApplicationController</code> all is fine, otherwise
<code>LoadError</code> is raised:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
unable to autoload constant ApplicationController, expected
<full path to application_controller.rb> to define it (LoadError)
</pre>
</div>
<div class="info"><p>Rails does not require the value of autoloaded constants to be a class or
module object. For example, if the file <code>app/models/max_clients.rb</code> defines
<code>MAX_CLIENTS = 100</code> autoloading <code>MAX_CLIENTS</code> works just fine.</p></div><h5 id="namespaces"><a class="anchorlink" href="#namespaces">6.1.3 Namespaces</a></h5><p>Autoloading <code>ApplicationController</code> looks directly under the directories of
<code>autoload_paths</code> because the nesting in that spot is empty. The situation of
<code>Post</code> is different, the nesting in that line is <code>[PostsController]</code> and support
for namespaces comes into play.</p><p>The basic idea is that given</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module Admin
class BaseController < ApplicationController
@@all_roles = Role.all
end
end
</pre>
</div>
<p>to autoload <code>Role</code> we are going to check if it is defined in the current or
parent namespaces, one at a time. So, conceptually we want to try to autoload
any of</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
Admin::BaseController::Role
Admin::Role
Role
</pre>
</div>
<p>in that order. That's the idea. To do so, Rails looks in <code>autoload_paths</code>
respectively for file names like these:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
admin/base_controller/role.rb
admin/role.rb
role.rb
</pre>
</div>
<p>modulus some additional directory lookups we are going to cover soon.</p><div class="info"><p><code>'Constant::Name'.underscore</code> gives the relative path without extension of
the file name where <code>Constant::Name</code> is expected to be defined.</p></div><p>Let's see how Rails autoloads the <code>Post</code> constant in the <code>PostsController</code>
above assuming the application has a <code>Post</code> model defined in
<code>app/models/post.rb</code>.</p><p>First it checks for <code>posts_controller/post.rb</code> in <code>autoload_paths</code>:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
app/assets/posts_controller/post.rb
app/controllers/posts_controller/post.rb
app/helpers/posts_controller/post.rb
...
test/mailers/previews/posts_controller/post.rb
</pre>
</div>
<p>Since the lookup is exhausted without success, a similar search for a directory
is performed, we are going to see why in the <a href="#automatic-modules">next section</a>:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
app/assets/posts_controller/post
app/controllers/posts_controller/post
app/helpers/posts_controller/post
...
test/mailers/previews/posts_controller/post
</pre>
</div>
<p>If all those attempts fail, then Rails starts the lookup again in the parent
namespace. In this case only the top-level remains:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
app/assets/post.rb
app/controllers/post.rb
app/helpers/post.rb
app/mailers/post.rb
app/models/post.rb
</pre>
</div>
<p>A matching file is found in <code>app/models/post.rb</code>. The lookup stops there and the
file is loaded. If the file actually defines <code>Post</code> all is fine, otherwise
<code>LoadError</code> is raised.</p><h4 id="autoloading-algorithms-qualified-references"><a class="anchorlink" href="#autoloading-algorithms-qualified-references">6.2 Qualified References</a></h4><p>When a qualified constant is missing Rails does not look for it in the parent
namespaces. But there is a caveat: when a constant is missing, Rails is
unable to tell if the trigger was a relative reference or a qualified one.</p><p>For example, consider</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module Admin
User
end
</pre>
</div>
<p>and</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Admin::User
</pre>
</div>
<p>If <code>User</code> is missing, in either case all Rails knows is that a constant called
"User" was missing in a module called "Admin".</p><p>If there is a top-level <code>User</code> Ruby would resolve it in the former example, but
wouldn't in the latter. In general, Rails does not emulate the Ruby constant
resolution algorithms, but in this case it tries using the following heuristic:</p>
<blockquote>
<p>If none of the parent namespaces of the class or module has the missing
constant then Rails assumes the reference is relative. Otherwise qualified.</p>
</blockquote>
<p>For example, if this code triggers autoloading</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Admin::User
</pre>
</div>
<p>and the <code>User</code> constant is already present in <code>Object</code>, it is not possible that
the situation is</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module Admin
User
end
</pre>
</div>
<p>because otherwise Ruby would have resolved <code>User</code> and no autoloading would have
been triggered in the first place. Thus, Rails assumes a qualified reference and
considers the file <code>admin/user.rb</code> and directory <code>admin/user</code> to be the only
valid options.</p><p>In practice, this works quite well as long as the nesting matches all parent
namespaces respectively and the constants that make the rule apply are known at
that time.</p><p>However, autoloading happens on demand. If by chance the top-level <code>User</code> was
not yet loaded, then Rails assumes a relative reference by contract.</p><p>Naming conflicts of this kind are rare in practice, but if one occurs,
<code>require_dependency</code> provides a solution by ensuring that the constant needed
to trigger the heuristic is defined in the conflicting place.</p><h4 id="automatic-modules"><a class="anchorlink" href="#automatic-modules">6.3 Automatic Modules</a></h4><p>When a module acts as a namespace, Rails does not require the application to
define a file for it, a directory matching the namespace is enough.</p><p>Suppose an application has a back office whose controllers are stored in
<code>app/controllers/admin</code>. If the <code>Admin</code> module is not yet loaded when
<code>Admin::UsersController</code> is hit, Rails needs first to autoload the constant
<code>Admin</code>.</p><p>If <code>autoload_paths</code> has a file called <code>admin.rb</code> Rails is going to load that
one, but if there's no such file and a directory called <code>admin</code> is found, Rails
creates an empty module and assigns it to the <code>Admin</code> constant on the fly.</p><h4 id="generic-procedure"><a class="anchorlink" href="#generic-procedure">6.4 Generic Procedure</a></h4><p>Relative references are reported to be missing in the cref where they were hit,
and qualified references are reported to be missing in their parent (see
<a href="#resolution-algorithm-for-relative-constants">Resolution Algorithm for Relative
Constants</a> at the beginning of
this guide for the definition of <em>cref</em>, and <a href="#resolution-algorithm-for-qualified-constants">Resolution Algorithm for Qualified
Constants</a> for the definition of
<em>parent</em>).</p><p>The procedure to autoload constant <code>C</code> in an arbitrary situation is as follows:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
if the class or module in which C is missing is Object
let ns = ''
else
let M = the class or module in which C is missing
if M is anonymous
let ns = ''
else
let ns = M.name
end
end
loop do
# Look for a regular file.
for dir in autoload_paths
if the file "#{dir}/#{ns.underscore}/c.rb" exists
load/require "#{dir}/#{ns.underscore}/c.rb"
if C is now defined
return
else
raise LoadError
end
end
end
# Look for an automatic module.
for dir in autoload_paths
if the directory "#{dir}/#{ns.underscore}/c" exists
if ns is an empty string
let C = Module.new in Object and return
else
let C = Module.new in ns.constantize and return
end
end
end
if ns is empty
# We reached the top-level without finding the constant.
raise NameError
else
if C exists in any of the parent namespaces
# Qualified constants heuristic.
raise NameError
else
# Try again in the parent namespace.
let ns = the parent namespace of ns and retry
end
end
end
</pre>
</div>
<h3 id="require-dependency"><a class="anchorlink" href="#require-dependency">7 require_dependency</a></h3><p>Constant autoloading is triggered on demand and therefore code that uses a
certain constant may have it already defined or may trigger an autoload. That
depends on the execution path and it may vary between runs.</p><p>There are times, however, in which you want to make sure a certain constant is
known when the execution reaches some code. <code>require_dependency</code> provides a way
to load a file using the current <a href="#loading-mechanism">loading mechanism</a>, and
keeping track of constants defined in that file as if they were autoloaded to
have them reloaded as needed.</p><p><code>require_dependency</code> is rarely needed, but see a couple of use-cases in
<a href="#autoloading-and-sti">Autoloading and STI</a> and <a href="#when-constants-aren-t-missed">When Constants aren't
Triggered</a>.</p><div class="warning"><p>Unlike autoloading, <code>require_dependency</code> does not expect the file to
define any particular constant. Exploiting this behavior would be a bad practice
though, file and constant paths should match.</p></div><h3 id="constant-reloading"><a class="anchorlink" href="#constant-reloading">8 Constant Reloading</a></h3><p>When <code>config.cache_classes</code> is false Rails is able to reload autoloaded
constants.</p><p>For example, if you're in a console session and edit some file behind the
scenes, the code can be reloaded with the <code>reload!</code> command:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
> reload!
</pre>
</div>
<p>When the application runs, code is reloaded when something relevant to this
logic changes. In order to do that, Rails monitors a number of things:</p>
<ul>
<li><p><code>config/routes.rb</code>.</p></li>
<li><p>Locales.</p></li>
<li><p>Ruby files under <code>autoload_paths</code>.</p></li>
<li><p><code>db/schema.rb</code> and <code>db/structure.sql</code>.</p></li>
</ul>
<p>If anything in there changes, there is a middleware that detects it and reloads
the code.</p><p>Autoloading keeps track of autoloaded constants. Reloading is implemented by
removing them all from their respective classes and modules using
<code>Module#remove_const</code>. That way, when the code goes on, those constants are
going to be unknown again, and files reloaded on demand.</p><div class="info"><p>This is an all-or-nothing operation, Rails does not attempt to reload only
what changed since dependencies between classes makes that really tricky.
Instead, everything is wiped.</p></div><h3 id="module-autoload-isn-t-involved"><a class="anchorlink" href="#module-autoload-isn-t-involved">9 Module#autoload isn't Involved</a></h3><p><code>Module#autoload</code> provides a lazy way to load constants that is fully integrated
with the Ruby constant lookup algorithms, dynamic constant API, etc. It is quite
transparent.</p><p>Rails internals make extensive use of it to defer as much work as possible from
the boot process. But constant autoloading in Rails is <strong>not</strong> implemented with
<code>Module#autoload</code>.</p><p>One possible implementation based on <code>Module#autoload</code> would be to walk the
application tree and issue <code>autoload</code> calls that map existing file names to
their conventional constant name.</p><p>There are a number of reasons that prevent Rails from using that implementation.</p><p>For example, <code>Module#autoload</code> is only capable of loading files using <code>require</code>,
so reloading would not be possible. Not only that, it uses an internal <code>require</code>
which is not <code>Kernel#require</code>.</p><p>Then, it provides no way to remove declarations in case a file is deleted. If a
constant gets removed with <code>Module#remove_const</code> its <code>autoload</code> is not triggered
again. Also, it doesn't support qualified names, so files with namespaces should
be interpreted during the walk tree to install their own <code>autoload</code> calls, but
those files could have constant references not yet configured.</p><p>An implementation based on <code>Module#autoload</code> would be awesome but, as you see,
at least as of today it is not possible. Constant autoloading in Rails is
implemented with <code>Module#const_missing</code>, and that's why it has its own contract,
documented in this guide.</p><h3 id="common-gotchas"><a class="anchorlink" href="#common-gotchas">10 Common Gotchas</a></h3><h4 id="nesting-and-qualified-constants"><a class="anchorlink" href="#nesting-and-qualified-constants">10.1 Nesting and Qualified Constants</a></h4><p>Let's consider</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module Admin
class UsersController < ApplicationController
def index
@users = User.all
end
end
end
</pre>
</div>
<p>and</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class Admin::UsersController < ApplicationController
def index
@users = User.all
end
end
</pre>
</div>
<p>To resolve <code>User</code> Ruby checks <code>Admin</code> in the former case, but it does not in
the latter because it does not belong to the nesting (see <a href="#nesting">Nesting</a>
and <a href="#resolution-algorithms">Resolution Algorithms</a>).</p><p>Unfortunately Rails autoloading does not know the nesting in the spot where the
constant was missing and so it is not able to act as Ruby would. In particular,
<code>Admin::User</code> will get autoloaded in either case.</p><p>Albeit qualified constants with <code>class</code> and <code>module</code> keywords may technically
work with autoloading in some cases, it is preferable to use relative constants
instead:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module Admin
class UsersController < ApplicationController
def index
@users = User.all
end
end
end
</pre>
</div>
<h4 id="autoloading-and-sti"><a class="anchorlink" href="#autoloading-and-sti">10.2 Autoloading and STI</a></h4><p>Single Table Inheritance (STI) is a feature of Active Record that enables
storing a hierarchy of models in one single table. The API of such models is
aware of the hierarchy and encapsulates some common needs. For example, given
these classes:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# app/models/polygon.rb
class Polygon < ApplicationRecord
end
# app/models/triangle.rb
class Triangle < Polygon
end
# app/models/rectangle.rb
class Rectangle < Polygon
end
</pre>
</div>
<p><code>Triangle.create</code> creates a row that represents a triangle, and
<code>Rectangle.create</code> creates a row that represents a rectangle. If <code>id</code> is the
ID of an existing record, <code>Polygon.find(id)</code> returns an object of the correct
type.</p><p>Methods that operate on collections are also aware of the hierarchy. For
example, <code>Polygon.all</code> returns all the records of the table, because all
rectangles and triangles are polygons. Active Record takes care of returning
instances of their corresponding class in the result set.</p><p>Types are autoloaded as needed. For example, if <code>Polygon.first</code> is a rectangle
and <code>Rectangle</code> has not yet been loaded, Active Record autoloads it and the
record is correctly instantiated.</p><p>All good, but if instead of performing queries based on the root class we need
to work on some subclass, things get interesting.</p><p>While working with <code>Polygon</code> you do not need to be aware of all its descendants,
because anything in the table is by definition a polygon, but when working with
subclasses Active Record needs to be able to enumerate the types it is looking
for. Let's see an example.</p><p><code>Rectangle.all</code> only loads rectangles by adding a type constraint to the query:</p><div class="code_container">
<pre class="brush: sql; gutter: false; toolbar: false">
SELECT "polygons".* FROM "polygons"
WHERE "polygons"."type" IN ("Rectangle")
</pre>
</div>
<p>Let's introduce now a subclass of <code>Rectangle</code>:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# app/models/square.rb
class Square < Rectangle
end
</pre>
</div>
<p><code>Rectangle.all</code> should now return rectangles <strong>and</strong> squares:</p><div class="code_container">
<pre class="brush: sql; gutter: false; toolbar: false">
SELECT "polygons".* FROM "polygons"
WHERE "polygons"."type" IN ("Rectangle", "Square")
</pre>
</div>
<p>But there's a caveat here: How does Active Record know that the class <code>Square</code>
exists at all?</p><p>Even if the file <code>app/models/square.rb</code> exists and defines the <code>Square</code> class,
if no code yet used that class, <code>Rectangle.all</code> issues the query</p><div class="code_container">
<pre class="brush: sql; gutter: false; toolbar: false">
SELECT "polygons".* FROM "polygons"
WHERE "polygons"."type" IN ("Rectangle")
</pre>
</div>
<p>That is not a bug, the query includes all <em>known</em> descendants of <code>Rectangle</code>.</p><p>A way to ensure this works correctly regardless of the order of execution is to
manually load the direct subclasses at the bottom of the file that defines each
intermediate class:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# app/models/rectangle.rb
class Rectangle < Polygon
end
require_dependency 'square'
</pre>
</div>
<p>This needs to happen for every intermediate (non-root and non-leaf) class. The
root class does not scope the query by type, and therefore does not necessarily
have to know all its descendants.</p><h4 id="autoloading-and-require"><a class="anchorlink" href="#autoloading-and-require">10.3 Autoloading and <code>require</code></a></h4><p>Files defining constants to be autoloaded should never be <code>require</code>d:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
require 'user' # DO NOT DO THIS
class UsersController < ApplicationController
...
end
</pre>
</div>
<p>There are two possible gotchas here in development mode:</p>
<ol>
<li><p>If <code>User</code> is autoloaded before reaching the <code>require</code>, <code>app/models/user.rb</code>
runs again because <code>load</code> does not update <code>$LOADED_FEATURES</code>.</p></li>
<li><p>If the <code>require</code> runs first Rails does not mark <code>User</code> as an autoloaded
constant and changes to <code>app/models/user.rb</code> aren't reloaded.</p></li>
</ol>
<p>Just follow the flow and use constant autoloading always, never mix
autoloading and <code>require</code>. As a last resort, if some file absolutely needs to
load a certain file use <code>require_dependency</code> to play nice with constant
autoloading. This option is rarely needed in practice, though.</p><p>Of course, using <code>require</code> in autoloaded files to load ordinary 3rd party
libraries is fine, and Rails is able to distinguish their constants, they are
not marked as autoloaded.</p><h4 id="autoloading-and-initializers"><a class="anchorlink" href="#autoloading-and-initializers">10.4 Autoloading and Initializers</a></h4><p>Consider this assignment in <code>config/initializers/set_auth_service.rb</code>:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
AUTH_SERVICE = if Rails.env.production?
RealAuthService
else
MockedAuthService
end
</pre>
</div>
<p>The purpose of this setup would be that the application uses the class that
corresponds to the environment via <code>AUTH_SERVICE</code>. In development mode
<code>MockedAuthService</code> gets autoloaded when the initializer runs. Let's suppose
we do some requests, change its implementation, and hit the application again.
To our surprise the changes are not reflected. Why?</p><p>As <a href="#constant-reloading">we saw earlier</a>, Rails removes autoloaded constants,
but <code>AUTH_SERVICE</code> stores the original class object. Stale, non-reachable
using the original constant, but perfectly functional.</p><p>The following code summarizes the situation:</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class C
def quack
'quack!'
end
end
X = C
Object.instance_eval { remove_const(:C) }