Runloop guides are out of date

[sohara]

The guides for the runloop (version 3.4) are quite out of date. They refer to things that no longer exist, such as Ember.run.queues (there are still queues but they are no longer accessible on Ember.run and there is an embedded demo app here: https://s3.amazonaws.com/emberjs.com/run-loop-guide/index.html

That demo app uses an extremely old version of Ember (1.3.2+pre.25108e91).

Not sure what to do here, because it seems a sizable portion of the docs on the runloop are no longer applicable. Perhaps we should just remove the misleading information for now?

[jenweber]

@sohara at minimum, our guides should not provide incorrect info, so I agree that we should remove misleading information.

Do you know any more specifics about which parts are incorrect/unavailable now? Thanks!

[sohara]

@jenweber At a minimum parts of the guides that refer to the internals as being publicly available are misleading. E.g. this section: https://github.com/ember-learn/guides-source/blob/master/guides/v3.4.0/applications/run-loop.md#how-does-the-run-loop-work-in-ember
It refers to Ember.run.queues being a publicly accessible array of available queues. This used to be the case but it has been made private at some point in the last year.

Overall I'm not sure how useful it is for the guides to delve into the internals, especially when they are no longer public.

The greatest offender is of course the linked toy app for demonstrating the behaviour of the run loop. It's a good illustration of the behaviour, but since it's literally at least 5 years old it's difficult to say how applicable it is today. I think if the guides are to maintain such demo apps the source could should be embedded in the guides repo and pinned to the respective version of Ember, in order to guarantee they are up to date. Additionally they should only employ public API.

My understanding is that the run loop is to become far less prominent in Ember with the transition to a more modern programming model (roughly the one offered by Octane) and greater employment of async/await are expected to reduce the need for application developers to interact with the runloop directly. I think others would be better placed to elaborate on this (e.g. core team members). At some point I wouldn't be surprised if there is no need for a section on the runloop in the guides, but that's a larger question.

Two options I can think of are 1) simply removing the reference to no-longer public API in this section and 2) trying to rewrite the section to ensure that is as informative about the workings of the runloop as it currently is, but without mention of now-private API. The latter would take some more work and I would probably want input from core team members to ensure it accurately accounts for the current state of the runloop and where things are heading.

Sorry for the long-winded response!

[jenweber]

@sohara it is perfect, thank you.

To-dos for anyone who wants to pick up this issue:

• remove reference to Ember.run.queues
• Add a disclaimer at the very top of the Run Loop Guide that says something to indicate that most Ember developers don't have to think about or learn the run loop, but those who are interested in the internals of Ember and performance tuning should read on.
• remove the embedded app leave it for now. We should find out where it came from and if we can update it.
• only make changes to the markdown file for the latest version of the guides

[gokatz]

I would love to help with this

[sivakumar-kailasam]

In addition to @jenweber's comments, anyone working on this can get feedback on the content by checking with framework core authors by reaching out via the #dev-ember-js on discord

[jenweber]

Additional possible fixes for the run loop: #183 (comment)