From 404e81cc69255fa835dcbd5bb8c46fb893979813 Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Sat, 13 Sep 2025 11:20:14 +0100 Subject: [PATCH 1/3] minor changes to runloop --- guides/release/applications/run-loop.md | 52 ++++++++++++++++++------- 1 file changed, 38 insertions(+), 14 deletions(-) diff --git a/guides/release/applications/run-loop.md b/guides/release/applications/run-loop.md index e424dae961..1ba933bd8e 100644 --- a/guides/release/applications/run-loop.md +++ b/guides/release/applications/run-loop.md @@ -1,6 +1,22 @@ -**Note:** -* _For basic Ember app development scenarios, you don't need to understand the run loop or use it directly. All common paths are paved nicely for you and don't require working with the run loop._ -* _However, the run loop will be helpful to understand the internals of Ember and to assist in customized performance tuning by manually batching costly work._ +
+
+
+
Zoey says...
+
+ +

+ For basic Ember app development scenarios, you don't need to understand the run loop or use it directly. All common paths are paved nicely for you and don't require working with the run loop. +

+ +

+ However, the run loop will be helpful to understand the internals of Ember and to assist in customized performance tuning by manually batching costly work. +

+ +
+
+ +
+
Ember's internals and most of the code you will write in your applications takes place in a run loop. The run loop is used to batch, and order (or reorder) work in a way that is most effective and efficient. @@ -83,9 +99,11 @@ class Image { and a template to display its attributes: -```handlebars -{{this.width}} -{{this.aspectRatio}} +```gjs + ``` If we execute the following code without the run loop: @@ -174,8 +192,10 @@ In this example, `Ember.run` is used to handle an online event (browser gains internet access) and run some Ember code. ```javascript +import { run } from '@ember/runloop'; + window.addEventListener('online', () => { - Ember.run(() => { // begin loop + run(() => { // begin loop // Code that results in jobs being scheduled goes here }); // end loop, jobs are flushed and executed }); @@ -190,10 +210,12 @@ If you don't, Ember will try to approximate a beginning and end for you. Consider the following callback: ```javascript +import { run } from '@ember/runloop'; + window.addEventListener('online', () => { console.log('Doing things...'); - Ember.run.schedule('actions', () => { + run.schedule('actions', () => { // Do more things }); }); @@ -207,26 +229,28 @@ These automatically created run loops we call _autoruns_. Here is some pseudocode to describe what happens using the example above: ```javascript +import { run } from '@ember/runloop'; + window.addEventListener('online', () => { // 1. autoruns do not change the execution of arbitrary code in a callback. // This code is still run when this callback is executed and will not be // scheduled on an autorun. console.log('Doing things...'); - Ember.run.schedule('actions', () => { + run.schedule('actions', () => { // 2. schedule notices that there is no currently available run loop so it // creates one. It schedules it to close and flush queues on the next // turn of the JS event loop. - if (! Ember.run.hasOpenRunLoop()) { - Ember.run.begin(); + if (! run.hasOpenRunLoop()) { + run.begin(); nextTick(() => { - Ember.run.end() + run.end() }, 0); } // 3. There is now a run loop available so schedule adds its item to the // given queue - Ember.run.schedule('actions', () => { + run.schedule('actions', () => { // Do more things }); @@ -234,7 +258,7 @@ window.addEventListener('online', () => { // 4. This schedule sees the autorun created by schedule above as an available // run loop and adds its item to the given queue. - Ember.run.schedule('afterRender', () => { + run.schedule('afterRender', () => { // Do yet more things }); }); From 1a27b396c5c5289b73e966e877ebb8cf34667b08 Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Mon, 15 Sep 2025 20:23:34 +0100 Subject: [PATCH 2/3] catch the last few references to Ember.run --- guides/release/applications/run-loop.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/guides/release/applications/run-loop.md b/guides/release/applications/run-loop.md index 1ba933bd8e..69dac09508 100644 --- a/guides/release/applications/run-loop.md +++ b/guides/release/applications/run-loop.md @@ -100,9 +100,11 @@ class Image { and a template to display its attributes: ```gjs +let profilePhoto = new Image({ width: 250, height: 500 }); + ``` @@ -187,8 +189,8 @@ which will make you a better Ember developer. You should begin a run loop when the callback fires. -The `Ember.run` method can be used to create a run loop. -In this example, `Ember.run` is used to handle an online +The `run()` method, imported from `@ember/runloop`, can be used to create a run loop. +In this example, `run()` is used to handle an online event (browser gains internet access) and run some Ember code. ```javascript @@ -205,7 +207,7 @@ window.addEventListener('online', () => { ## What happens if I forget to start a run loop in an async handler? -As mentioned above, you should wrap any non-Ember async callbacks in `Ember.run`. +As mentioned above, you should wrap any non-Ember async callbacks in `run()`. If you don't, Ember will try to approximate a beginning and end for you. Consider the following callback: @@ -266,5 +268,5 @@ window.addEventListener('online', () => { ## Where can I find more information? -Check out the [Ember.run](https://api.emberjs.com/ember/release/classes/@ember%2Frunloop) API documentation, +Check out the [@ember/runloop](https://api.emberjs.com/ember/release/classes/@ember%2Frunloop) API documentation, as well as the [Backburner library](https://github.com/ebryn/backburner.js/) that powers the run loop. From 11c0041999ccd02636c5ec8d41ced6c762aa437c Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Mon, 15 Sep 2025 20:28:09 +0100 Subject: [PATCH 3/3] fix lint --- guides/release/applications/run-loop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/release/applications/run-loop.md b/guides/release/applications/run-loop.md index 69dac09508..b8f0ab7ebb 100644 --- a/guides/release/applications/run-loop.md +++ b/guides/release/applications/run-loop.md @@ -268,5 +268,5 @@ window.addEventListener('online', () => { ## Where can I find more information? -Check out the [@ember/runloop](https://api.emberjs.com/ember/release/classes/@ember%2Frunloop) API documentation, +Check out the [`@ember/runloop`](https://api.emberjs.com/ember/release/classes/@ember%2Frunloop) API documentation, as well as the [Backburner library](https://github.com/ebryn/backburner.js/) that powers the run loop.