Skip to content

Commit c978035

Browse files
committed
Modernizes some examples in the autoloading guide
Those examples were obsolete, because nowadays using a reloadable constant in initializers is not just a bad idea, it is indeed not possible. The patch updates the examples accordingly.
1 parent 835ff19 commit c978035

File tree

1 file changed

+6
-10
lines changed

1 file changed

+6
-10
lines changed

guides/source/autoloading_and_reloading_constants.md

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -244,12 +244,10 @@ Let's imagine `ApiGateway` is a reloadable class and you need to configure its e
244244

245245
```ruby
246246
# config/initializers/api_gateway_setup.rb
247-
ApiGateway.endpoint = "https://example.com" # DO NOT DO THIS
247+
ApiGateway.endpoint = "https://example.com" # NameError
248248
```
249249

250-
a reloaded `ApiGateway` would have a `nil` endpoint, because the code above does not run again.
251-
252-
You can still set things up during boot, but you need to wrap them in a `to_prepare` block, which runs on boot, and after each reload:
250+
Initializers cannot refer to reloadable constants, you need to wrap that in a `to_prepare` block, which runs on boot, and after each reload:
253251

254252
```ruby
255253
# config/initializers/api_gateway_setup.rb
@@ -277,15 +275,15 @@ end
277275

278276
### Use Case 2: During Boot, Load Code that Remains Cached
279277

280-
Some configurations take a class or module object, and they store it in a place that is not reloaded.
278+
Some configurations take a class or module object, and they store it in a place that is not reloaded. It is important that these are not reloadable, because edits would not be reflected in those cached stale objects.
281279

282280
One example is middleware:
283281

284282
```ruby
285283
config.middleware.use MyApp::Middleware::Foo
286284
```
287285

288-
When you reload, the middleware stack is not affected, so, whatever object was stored in `MyApp::Middleware::Foo` at boot time remains there stale.
286+
When you reload, the middleware stack is not affected, so it would be confusing that `MyApp::Middleware::Foo` is reloadable. Changes in its implementation would have no effect.
289287

290288
Another example is Active Job serializers:
291289

@@ -294,7 +292,7 @@ Another example is Active Job serializers:
294292
Rails.application.config.active_job.custom_serializers << MoneySerializer
295293
```
296294

297-
Whatever `MoneySerializer` evaluates to during initialization gets pushed to the custom serializers. If that was reloadable, the initial object would be still within Active Job, not reflecting your changes.
295+
Whatever `MoneySerializer` evaluates to during initialization gets pushed to the custom serializers, and that object stays there on reloads.
298296

299297
Yet another example are railties or engines decorating framework classes by including modules. For instance, [`turbo-rails`](https://github.com/hotwired/turbo-rails) decorates `ActiveRecord::Base` this way:
300298

@@ -321,12 +319,10 @@ Let's suppose an engine works with the reloadable application class that models
321319
```ruby
322320
# config/initializers/my_engine.rb
323321
MyEngine.configure do |config|
324-
config.user_model = User # DO NOT DO THIS
322+
config.user_model = User # NameError
325323
end
326324
```
327325

328-
On reload, `config.user_model` would be pointing to a stale object, because the reloaded `User` class would not be reset in the engine configuration. Therefore, edits to `User` would be missed by the engine.
329-
330326
In order to play well with reloadable application code, the engine instead needs applications to configure the _name_ of that class:
331327

332328
```ruby

0 commit comments

Comments
 (0)